Authentication
| Command | Description |
|---|---|
vesslctl auth login | Log in using browser OAuth (falls back to email/password) |
vesslctl auth logout | Log out and clear stored credentials |
vesslctl auth status | Show the currently authenticated user |
Organization & Team
| Command | Description |
|---|---|
vesslctl org list | List organizations you belong to |
vesslctl org show | Show details of the current organization |
vesslctl org switch <name> | Switch default organization |
vesslctl org create --name <name> | Create a new organization |
vesslctl team list | List teams in the current organization |
vesslctl team show | Show details of the current team |
vesslctl team switch <name> | Switch default team |
vesslctl team create --name <name> | Create a new team |
Configuration
| Command | Description |
|---|---|
vesslctl config show | Display current CLI configuration |
vesslctl config set default_org <name> | Set the default organization |
vesslctl config set default_team <name> | Set the default team |
vesslctl config set output_format <fmt> | Set default output format (table, json, csv) |
Workspace
Alias:vesslctl ws
| Command | Description |
|---|---|
vesslctl workspace list | List workspaces in the current team |
vesslctl workspace show <slug> | Show workspace details and status |
vesslctl workspace create | Create a new workspace (see flags below) |
vesslctl workspace ssh <slug> | SSH into a running workspace |
vesslctl workspace logs <slug> | View workspace logs |
vesslctl workspace pause <slug> | Pause a workspace (preserves environment) |
vesslctl workspace start <slug> | Resume a paused workspace |
vesslctl workspace terminate <slug> | Terminate and delete a workspace |
vesslctl workspace create \
--name <name> \
--cluster <cluster> \
--resource-spec <spec> \
--image <image> \
--ssh-key <ssh-key-slug> \
--port jupyter:8888:http
Inside a running workspace,
vesslctl is pre-authenticated with a workload token (VESSLCTL_ACCESS_TOKEN/ORG/TEAM), so commands like vesslctl workspace list or vesslctl job create work straight from the JupyterLab terminal.SSH keys
| Command | Description |
|---|---|
vesslctl ssh-key list | List SSH keys registered to your account |
vesslctl ssh-key add --name <name> --public-key-file <path> | Register a public key from a file |
vesslctl ssh-key add --name <name> --generate | Generate a keypair on the server (private key printed once) |
vesslctl ssh-key delete <ssh-key-slug> | Delete an SSH key by slug (use -y to skip confirmation) |
Job
| Command | Description |
|---|---|
vesslctl job list | List jobs in the current team |
vesslctl job show <slug> | Show job details and status |
vesslctl job create | Submit a new batch job (see flags below) |
vesslctl job logs <slug> | View job output logs |
vesslctl job export <slug> | Export job configuration as JSON |
vesslctl job terminate <slug> | Cancel a running job |
vesslctl job tag attach <slug> <tag> | Attach a tag to a job |
vesslctl job tag detach <slug> <tag> | Detach a tag from a job |
vesslctl job create \
--name <name> \
--resource-spec <spec> \
--image <image> \
--cmd "<command>"
Cluster & Resources
| Command | Description |
|---|---|
vesslctl cluster list | List available clusters |
vesslctl resource-spec list | List resource specs (GPU/CPU configurations) |
vesslctl resource-spec list --cluster <slug> | List specs for a specific cluster |
Storage & Volumes
Alias:vesslctl vol
| Command | Description |
|---|---|
vesslctl storage list | List storage backends |
vesslctl storage show <slug> | Show storage backend details |
vesslctl storage create | Create a cluster storage (requires --name, --cluster, --capacity) |
vesslctl storage delete <slug> | Delete a storage backend |
vesslctl volume list | List volumes |
vesslctl volume show <slug> | Show volume details |
vesslctl volume create --name <n> --storage <slug> --teams <team> | Create a new volume (--name, --storage, --teams are required) |
vesslctl volume ls <slug> --prefix / | List files in a volume (use / for root) |
vesslctl volume token <slug> | Get temporary S3 credentials for a volume |
vesslctl volume upload <slug> <local_path> | Upload local files to a volume |
vesslctl volume download <slug> <local_path> | Download files from a volume |
vesslctl volume update <slug> | Update volume metadata (pass --name, --description, or --teams) |
vesslctl volume delete <slug> | Delete a volume |
Tags
| Command | Description |
|---|---|
vesslctl tag list | List tags in the current organization |
vesslctl tag create <value> | Create a tag (optional: --color "#ff0000") |
vesslctl tag delete <value> | Delete a tag by value (or -s <slug>) |
AI Skills
| Command | Description |
|---|---|
vesslctl skill install | Install skills for AI coding agents |
vesslctl skill show | Display the bundled skill content |
Utility
| Command | Description |
|---|---|
vesslctl update | Update vesslctl to the latest version (-y to skip the confirmation prompt) |
vesslctl version | Print vesslctl version |
vesslctl install | Install vesslctl to a directory in your PATH |
vesslctl completion install | Auto-detect shell and install completion script |
vesslctl completion bash|zsh|fish|powershell | Generate shell completion script manually |
Common Workflows
First-time setup
# Install
curl -fsSL https://api.cloud.vessl.ai/cli/install.sh | bash
# Authenticate
vesslctl auth login
# Set defaults
vesslctl config set default_org <your-org>
vesslctl config set default_team <your-team>
# Verify
vesslctl auth status
vesslctl config show
Launch and connect to a workspace
vesslctl workspace create \
--name dev-box \
--cluster <cluster-name> \
--resource-spec <spec-name> \
--image pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel
# Copy the workspace slug from `vesslctl workspace list` (for example, dev-box-abc123).
vesslctl workspace show <workspace-slug> # wait for "running"
vesslctl workspace ssh <workspace-slug> # connect
vesslctl workspace pause <workspace-slug> # done for now
Submit a batch job
vesslctl job create \
--name train-v2 \
--resource-spec <spec-name> \
--image pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel \
--cmd "python train.py --epochs 50"
vesslctl job logs train-v2 --follow
Upload data to object storage
# Create a volume (--name, --storage, --teams are required)
vesslctl volume create --name my-dataset --storage <storage-name> --teams <team>
# Copy the volume slug from `vesslctl volume list` (for example, my-dataset-abc123).
vesslctl volume upload <volume-slug> ./data/
# Verify
vesslctl volume ls <volume-slug> --prefix /
aws s3 cp, custom pipelines), use vesslctl volume token <volume-slug> to get temporary S3 credentials and an endpoint URL.