> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```bash theme={null}
vesslctl workspace create \
  --name <name> \
  --cluster <cluster> \
  --resource-spec <spec> \
  --image <image> \
  --ssh-key <ssh-key-slug> \
  --port jupyter:8888:http
```

<Tip>
  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.
</Tip>

## 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:**

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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.