Usage Examples

Install v8x

Install v8x with uv:

uv venv
source .venv/bin/activate

uvx v8x

Vantage Login

If this is your first time using the CLI, inspect the login options with:

uvx v8x login --help

In most cases, uvx v8x login is enough. The command starts the authentication flow for your active profile and stores credentials locally for later commands.

Key options:

• Use the active profile by default
• Add -v when you need more login diagnostics

uvx v8x login

Success looks like this: the browser or device flow completes, the CLI returns to the shell without an auth error, and later commands such as uvx v8x whoami work without requiring another login.

Cluster Management Commands

To inspect the available cluster subcommands and flags, start with:

uvx v8x cluster --help
uvx v8x cluster create --help

The commands below let you list existing clusters, create a new cluster from a cloud account, and inspect a specific cluster after creation.

Key options:

• --cloud-account-id selects the cloud account to deploy against
• --cluster-type chooses the cluster mode, such as slurm or k8s
• --app deploys an application during cluster creation
• --json returns machine-readable output for scripting

# List clusters
uvx v8x cluster list
uvx v8x cluster list --json | jq '.clusters | length'

# Create a cluster from a cloud account
uvx v8x cluster create compute-multipass-00 \
  --cloud-account-id 320 \
  --app slurm-multipass-localhost \
  --cluster-type slurm

# Get a specific cluster
uvx v8x cluster get compute-multipass-00 --json | jq '.cluster | {name,id,status}'

Success looks like this: list commands return cluster records, create returns an accepted cluster request, and get shows a named cluster with an ID and status you can monitor.

Vantage Applications (app)

Use uvx v8x app --help to inspect filters and output options before listing available applications.

Key options:

• Use the default table output for manual browsing
• Use --json when you want to filter or script against the result

# List available applications
uvx v8x app list

This shows the deployment applications the platform currently supports, which helps you choose a value for --app during cluster creation.

Cloud Provider Management

To inspect cloud account options before creating or listing accounts, run:

uvx v8x cloud account create --help
uvx v8x cloud account list --help

The key options are --provider for the infrastructure type, --attributes for provider-specific configuration, and --json when you want machine-readable output.

Key options:

• --provider chooses the infrastructure type
• --attributes passes provider-specific JSON
• --json returns structured output for scripting

# Create cloud accounts
uvx v8x cloud account create aws-prod --provider aws \
  --attributes '{"role_arn": "arn:aws:iam::123456789012:role/VantageRole", "region": "us-east-1"}'
uvx v8x cloud account create gcp-dev --provider gcp \
  --attributes '{"project_id": "my-project", "region": "us-central1"}'
uvx v8x cloud account create compute-a-on-site-us-east --provider on_prem

# List cloud accounts
uvx v8x cloud account list --json | jq '.cloud_accounts[] | {id, name, provider}'

{
  "id": 318,
  "name": "aws-prod",
  "provider": "aws"
}
{
  "id": 319,
  "name": "gcp-dev",
  "provider": "gcp"
}

These commands register reusable cloud accounts in your organization and let you retrieve the numeric IDs needed for cluster creation.

Success looks like this: create returns a successful account registration, and list shows the account name, provider, and ID that you can feed into uvx v8x cluster create.

Network and Storage

Inspect the available storage and network flags with:

uvx v8x storage create --help
uvx v8x network create --help

These commands create reusable storage and network resources, then list them so you can verify the resulting names, sizes, and status values.

Key options:

• --size sets the requested storage capacity
• --cidr defines the network range
• --json makes the output easier to parse with tools like jq

# Create a storage volume (cluster name is positional)
uvx v8x storage create data-vol my-cluster --size 100Gi

# Create network
uvx v8x network create cluster-net --cidr 10.0.0.0/16

# List resources
uvx v8x storage list my-cluster --json | jq '.volumes[] | {name, size, status}'
uvx v8x network list --json | jq '.networks[] | {name, cidr}'

Success looks like this: the create commands return new resource records, and the list commands show those resources with stable names and expected sizing or CIDR details.

Job Management Workflow

If you are new to the job commands, inspect the available options with:

uvx v8x job script list --help
uvx v8x job submission create --help
uvx v8x job submission list --help

The commands below start from an existing job script and then create a runnable submission that you can monitor from the CLI.

Key options:

• --search, --user-only, and pagination flags help you find the right job script
• --name labels the submission you are creating
• --job-script-id selects the script to run
• --json returns machine-readable output for scripting

# List job scripts
uvx v8x job script list

# Submit job
uvx v8x job submission create \
  --name myjobsubmission \
  --job-script-id 123

# List submissions
uvx v8x job submission list

# Monitor job status
uvx v8x job submission get 789 --json | jq '.status'

Success looks like this: the script list helps you identify an existing script, the submission returns an ID, and later status checks show the submission moving through its scheduler states.

For a dedicated step-by-step workflow, see Use the CLI with jobs.

Team Collaboration

Start with uvx v8x team --help if you want to inspect team and membership operations before running them.

These commands create a team, add members with roles, and then let you verify the resulting membership list.

Key options:

• --description documents the team purpose
• positional team and user identifiers select the target objects for membership operations
• --role on set-roles assigns one or more team roles

# Create team
uvx v8x team create ml-research --description "ML Research Team"

# Add team members
uvx v8x team add-member ml-research alice@company.com
uvx v8x team add-member ml-research bob@company.com

# Set team roles
uvx v8x team set-roles ml-research --role kubeflow-admin

# List team members
uvx v8x team list-members ml-research

Success looks like this: the team exists, membership commands return without validation errors, and the list output shows the expected users.

Switch Profiles

Use uvx v8x profile --help or uvx v8x profile create --help to inspect profile settings before creating one.

Profiles let you store separate endpoint and authentication contexts, which is especially useful when you work with more than one Vantage environment.

Key options:

• --activate makes the new profile current immediately
• Profile names let you switch between environments without re-entering endpoint settings each time

uvx v8x profile list
uvx v8x profile create staging --activate
uvx v8x profile use staging
uvx v8x login

Success looks like this: the new profile appears in uvx v8x profile list, the active profile changes as expected, and login authenticates against that selected environment.

For a dedicated environment workflow, see Manage CLI profiles.

GraphQL Query (Programmatic)

import asyncio
from v8x.gql_client import create_async_graphql_client
from v8x.config import Settings
from v8x.auth import extract_persona

async def main():
    settings = Settings()
    persona = extract_persona("default")
    client = create_async_graphql_client(settings, "default")
    data = await client.execute_async("""query { __typename }""")
    print(data)

asyncio.run(main())

Token Cache Inspection

from v8x.cache import load_tokens_from_cache
from v8x.schemas import TokenSet

tokens: TokenSet = load_tokens_from_cache("default")
print(tokens.access_token[:16] + "..." if tokens.access_token else "NO TOKEN")

Piping and Automation

# Email of current authenticated user
auth_email=$(uvx v8x whoami --json | jq -r '.identity.email')

echo "Authenticated as: $auth_email"

# Collect cluster names into a shell array
mapfile -t clusters < <(uvx v8x cluster list --json | jq -r '.clusters[].name')
printf 'Found %d clusters\n' "${#clusters[@]}"

Handling Errors

Add -v to surface debug logs:

uvx v8x -v whoami

If tokens are expired the CLI will attempt a refresh; if that fails re-run uvx v8x login.

For command-specific troubleshooting, append --help first to confirm the expected subcommand and flags before debugging the environment.

Success looks like this: verbose mode surfaces the failing layer clearly enough to distinguish command usage issues from auth, network, or API problems.

JSON Extraction Template

uvx v8x cluster list --json | jq '{count: (.clusters | length), names: [.clusters[].name]}'

---

See also: Commands | Troubleshooting