CLI quickstart
Get from an authenticated CLI session to a running cluster in a few commands. This quickstart uses the current cloud-account-first workflow: create a cloud account, then create a cluster from that account.
If you are learning the CLI for the first time, keep uvx v8x --help and
command-specific --help output nearby while you work through this page.
Install the CLI
Use uvx(recommended):
uvx v8x --help
or install from PyPI:
pip install v8x
This makes the v8x command available in your environment. If you prefer not to install, prefix any command with uvx v8x instead.
Verify the install:
uvx v8x version
or with uv:
uvx v8x version
Success looks like this: the version prints the installed CLI version, and --help shows the available command groups without errors.
Log in
Authenticate with your Vantage account so later commands can run against your active profile.
uvx v8x login
The CLI opens the login flow for your Vantage account and stores the resulting credentials in your active profile.
Success looks like this: the login flow completes, the CLI returns to the shell, and later commands such as uvx v8x whoami work without another prompt.
Create a cloud account
Create a cloud account for the infrastructure Vantage should provision against. This example uses an on-premises account, whose provider value is on_prem.
Start with:
uvx v8x cloud account create --help
The most important options are:
--provider, required, to choose the infrastructure type--description, optional, to label the account for your team--attributes, optional JSON for provider-specific settings
Supported provider values include aws, gcp, azure, on_prem, lxd, and microk8s. For a minimal on-premises setup, only the account name and --provider on_prem are required.
uvx v8x cloud account create mydatacenter-west --provider on_prem
This registers mydatacenter-west as a reusable cloud account in your organization.
If the command does not return the new cloud account ID directly, list your accounts and capture the numeric ID for the next step:
uvx v8x cloud account list
Create your first cluster
Use the cloud account from the previous step to create a Slurm cluster and deploy the Multipass application.
Start with:
uvx v8x cluster create --help
The most important options in this quickstart are:
--cloud-account-name, required, to select the cloud account you just created by name--cluster-type, optional, to choose betweenslurmandk8s--app, optional, to deploy an application immediately after the cluster is created--create-team, optional, to create a team alongside the cluster
uvx v8x cluster create slurm-multipass-demo \
--app slurm-multipass \
--cloud-account-name mydatacenter-west \
--cluster-type slurm \
--create-team
This creates a new cluster record in Vantage, provisions a Multipass VM, and deploys SLURM on it.
Success looks like this:
✓ Cluster 'slurm-multipass-demo' created successfully
📋 Created Resource Details:
╭─────────────────────────────┬──────────────────────────────────────╮
│ Field │ Value │
├─────────────────────────────┼──────────────────────────────────────┤
│ Name │ slurm-multipass-demo │
│ Status │ pending │
│ Cluster Type │ slurm │
│ Cluster Type Display │ Slurm │
│ Cloud Account Name │ mydatacenter-west │
│ Client ID │ slurm-multipass-demo-client │
│ Client Secret │ ******** │
│ Description │ Cluster slurm-multipass-demo │
│ │ created via CLI │
│ Is Ready │ ✗ │
│ Owner Email │ user@example.com │
│ SSSD Binder Password │ ******** │
│ Creation Parameters │ {...} │
╰─────────────────────────────┴──────────────────────────────────────╯
✓ App 'slurm-multipass' deployed successfully!
🎉 SLURM Multipass deployment completed successfully!
Access your cluster in the Vantage UI:
https://app.vantagecompute.ai/compute/clusters/slurm-multipass-demo-client
Deployment Summary:
• Instance name: vantage-multipass-slurm
• Cluster name: slurm-multipass-demo
• Deployment ID: dep-abc123
• Environment: Multipass VM
• Status: Active
Multipass VM Access:
• Open shell in VM: multipass shell vantage-multipass-slurm
• Execute command: multipass exec vantage-multipass-slurm -- <command>
• View VM info: multipass info vantage-multipass-slurm
• VM status: multipass list
SLURM Cluster Access:
• SSH to VM: multipass shell vantage-multipass-slurm
• Check SLURM status: multipass exec vantage-multipass-slurm -- sinfo
• View compute nodes: multipass exec vantage-multipass-slurm -- scontrol show nodes
• Check job queue: multipass exec vantage-multipass-slurm -- squeue
File Transfer:
• Copy to VM: multipass transfer <local-file> vantage-multipass-slurm:<remote-path>
• Copy from VM: multipass transfer vantage-multipass-slurm:<remote-path> <local-file>
• Shared directory: ~/multipass-slurm/shared (mounted at /shared in VM)
SLURM Job Management:
• Submit test job: multipass exec vantage-multipass-slurm -- sbatch /path/to/script.sh
• Interactive session: multipass exec vantage-multipass-slurm -- srun --pty bash
• Cancel job: multipass exec vantage-multipass-slurm -- scancel <job-id>
• Job history: multipass exec vantage-multipass-slurm -- sacct
VM Management:
• Stop VM: multipass stop vantage-multipass-slurm
• Start VM: multipass start vantage-multipass-slurm
• Restart VM: multipass restart vantage-multipass-slurm
• View VM logs: multipass info vantage-multipass-slurm --format yaml
Monitoring & Logs:
• VM resource usage: multipass info vantage-multipass-slurm
• System logs: multipass exec vantage-multipass-slurm -- journalctl -xe
• SLURM logs: multipass exec vantage-multipass-slurm -- journalctl -u slurmd -u slurmctld
Cleanup:
• Remove deployment: uvx v8x app deployment slurm-multipass remove vantage-multipass-slurm
• Manual VM deletion: multipass delete vantage-multipass-slurm --purge
Note: The VM is now running with SLURM configured. Use 'multipass shell
vantage-multipass-slurm' to access the environment.
Tip: Files in ~/multipass-slurm/shared are automatically synced to /shared
in the VM.
Wait for provisioning to progress, then inspect the cluster:
uvx v8x cluster get slurm-multipass-demo
Output:
📋 Cluster (ID: slurm-multipass-demo)
╭─────────────────────────────┬──────────────────────────────────────╮
│ Field │ Value │
├─────────────────────────────┼──────────────────────────────────────┤
│ Name │ slurm-multipass-demo │
│ Status │ active │
│ Cluster Type │ slurm │
│ Cluster Type Display │ Slurm │
│ Cloud Account Name │ mydatacenter-west │
│ Client ID │ slurm-multipass-demo-client │
│ Client Secret │ ******** │
│ Description │ Cluster slurm-multipass-demo │
│ │ created via CLI │
│ Is Ready │ ✓ │
│ Owner Email │ user@example.com │
│ SSSD Binder Password │ ******** │
│ Settings │ {...} │
╰─────────────────────────────┴──────────────────────────────────────╯
List all clusters to confirm:
uvx v8x cluster list
Output:
Clusters List
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name ┃ Status ┃ Type ┃ Description ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ slurm-multipass-demo │ active │ slurm │ Cluster slurm-multipass-demo │
│ │ │ │ created via CLI │
└──────────────────────────┴──────────┴────────┴──────────────────────────────┘
Other provider values include aws, gcp, azure, lxd, and microk8s.