Understand vesslctl

Install and configure the VESSL Cloud command-line tool.

vesslctl is the command-line interface for VESSL Cloud. Manage workspaces, batch jobs, storage, and team settings from your terminal.

Why vesslctl

• Develop and train in one tool: Launch interactive workspaces for development, then submit batch jobs for training, all with the same CLI
• Built for teams: Org and team scoping ensures workloads, volumes, and billing are isolated where they need to be
• Flexible storage: Choose Object storage for cross-cluster access or Cluster storage for high-performance local I/O, and mount volumes into any workload
• AI-native: Connect VESSL Cloud docs to Claude Code, Cursor, or any MCP-compatible tool so your AI assistant references accurate CLI documentation. See Use with AI tools
• Scriptable: Combine commands in shell scripts to build hyperparameter sweeps, data pipelines, or autonomous experiment loops

Installation

Supported platforms — macOS 15+, Ubuntu 20.04+, or Windows 10+. No other environment dependencies.

1. Install vesslctl

   curl -fsSL https://api.cloud.vessl.ai/cli/install.sh | bash
   
2. Log in

   vesslctl auth login
   

   This opens your browser for OAuth authentication. If no browser is available, the command falls back to email and password login.

3. Verify installation

   vesslctl auth status
   

Global Flags

Every command supports these flags:

Flag	Short	Description
--org		Override the default organization
--team	-t	Override the default team
--output	-o	Output format: table (default), json, or csv

Set Defaults

After logging in, vesslctl prompts you to select a default organization and team. You can change them anytime:

vesslctl config set default_org <your-org>
vesslctl config set default_team <your-team>

To view your current configuration:

vesslctl config show

Environment variables

vesslctl reads these environment variables. Flags take precedence over env vars, which take precedence over the config file:

Variable	Description
VESSLCTL_ORG	Default organization (overrides default_org from config)
VESSLCTL_TEAM	Default team (overrides default_team from config)
VESSLCTL_OUTPUT	Default output format: table, json, or csv
VESSLCTL_API_URL	Override the API endpoint (defaults to the production URL)
VESSLCTL_ACCESS_TOKEN	Long-lived access token. When set, vesslctl skips the interactive login flow.
SIDECAR_INITIAL_ACCESS_TOKEN	Auto-injected inside VESSL Cloud workspaces so you can run vesslctl without logging in. Used as a fallback when VESSLCTL_ACCESS_TOKEN is unset.

Inside a VESSL Cloud workspace, vesslctl is preconfigured with SIDECAR_INITIAL_ACCESS_TOKEN. Run vesslctl auth status to confirm — you do not need to run vesslctl auth login from a workspace terminal.

Shell Completion

The easiest way to enable tab completion is the install subcommand — it detects your shell automatically and writes the script to the right place:

vesslctl completion install

The command is idempotent, so you can safely re-run it after CLI updates. For zsh, it will let you know if your ~/.zshrc needs an fpath entry.

Manual setup

If you prefer to manage completion scripts yourself:

Bash

vesslctl completion bash > /etc/bash_completion.d/vesslctl

Update

Keep vesslctl up to date:

vesslctl update

Command Overview

Command	Description
workspace	Manage GPU workspaces (create, SSH, pause, terminate)
job	Submit and manage batch jobs
volume	Manage storage volumes
storage	List and inspect storage backends
org	Switch and manage organizations
team	Switch and manage teams
cluster	List available clusters
resource-spec	List GPU/CPU resource configurations (alias: rs)
tag	Create, list, and attach tags to jobs
skill	Install vesslctl skills for AI coding agents
config	Manage CLI configuration
auth	Log in, log out, check auth status
billing	View credit balance and burn rate
completion	Shell tab completion — install for auto-setup, or generate scripts manually for bash, zsh, fish, or PowerShell
update	Update vesslctl to the latest version
install	Install vesslctl to a directory in your PATH