CLI Cheat Sheet

Every vesslctl command at a glance with quick copy-paste examples.

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

Common create flags:

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

Common create flags:

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 /

If you need to integrate with an S3-compatible tool (DVC, aws s3 cp, custom pipelines), use vesslctl volume token <volume-slug> to get temporary S3 credentials and an endpoint URL.