> ## 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 Quickstart

> Three common workflows to get productive with vesslctl in minutes.

<div>
  <Frame>
    <img style={{ borderRadius: '0.5rem' }} src="https://mintcdn.com/dora/7JB7El29TavR1keb/images/vesslctl-quickstart-banner.png?fit=max&auto=format&n=7JB7El29TavR1keb&q=85&s=45bce711e33f908fb236d08f6cf41441" alt="Welcome banner for VESSL Cloud CLI showing a VESSL ASCII wordmark, the supported GPU lineup (A100, H100, H200, B200, GB200, B300, Ada), and three starter commands: vesslctl auth login, vesslctl workspace create, vesslctl --help" width="2440" height="2048" data-path="images/vesslctl-quickstart-banner.png" />
  </Frame>
</div>

This page walks through three real scenarios you will encounter when working with VESSL Cloud from the terminal.

## Prerequisites

* **VESSL Cloud account**: [Sign up](https://cloud.vessl.ai/~/signup) if you do not have one.
* **`vesslctl` installed**: One-line install from the [CLI overview](/cli/overview#installation).
* **Authenticated**: Run `vesslctl auth login` to complete the browser OAuth flow.
* **SSH key** (optional, for workspace access): Register a key with `vesslctl ssh-key add`, or manage them via [SSH key commands](/cli/commands/ssh-key).
* **Credit balance**: Add a payment method and top up from [Billing](/admin/billing/credits). Workspace and job creation are blocked when the balance is zero or negative.

## Launch a GPU instance

Launch an interactive GPU workspace, connect over SSH, and pause it when you are done.

<Steps>
  <Step title="Create the workspace">
    ```bash theme={null}
    vesslctl workspace create \
      --name my-dev-box \
      --cluster <cluster-name> \
      --resource-spec <spec-name> \
      --image pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel
    ```

    Replace `<cluster-name>` and `<spec-name>` with values from `vesslctl cluster list` and `vesslctl resource-spec list`. After creation, copy the workspace slug from `vesslctl workspace list` (for example, `my-dev-box-abc123`) — you will use it in the next steps.
  </Step>

  <Step title="Check workspace status">
    ```bash theme={null}
    vesslctl workspace show <workspace-slug>
    ```

    Wait until the status shows **running**.
  </Step>

  <Step title="Connect using SSH">
    ```bash theme={null}
    vesslctl workspace ssh <workspace-slug>
    ```
  </Step>

  <Step title="Pause to save cost">
    When you are finished for the day, pause the workspace. Your files and environment are preserved at a lower cost.

    ```bash theme={null}
    vesslctl workspace pause <workspace-slug>
    ```
  </Step>

  <Step title="Resume later">
    Pick up where you left off:

    ```bash theme={null}
    vesslctl workspace start <workspace-slug>
    ```
  </Step>
</Steps>

***

## Upload a dataset

Create a volume, upload data from the CLI, and verify the contents.

<Steps>
  <Step title="Create a volume">
    ```bash theme={null}
    vesslctl volume create \
      --name training-data \
      --storage <storage-name> \
      --teams <team-name> \
      --description "ImageNet subset for fine-tuning"
    ```

    Replace `<storage-name>` with a storage backend from `vesslctl storage list` and `<team-name>` with a team from `vesslctl team list`. `--name`, `--storage`, and `--teams` are all required. After creation, copy the volume slug from `vesslctl volume list` (for example, `training-data-abc123`).
  </Step>

  <Step title="Upload your dataset">
    ```bash theme={null}
    vesslctl volume upload <volume-slug> ./dataset/
    ```

    Upload individual files or entire directories in one command. Use `--remote-prefix datasets/v1/` to place files under a specific path, or `--exclude "*.pyc"` to skip patterns.
  </Step>

  <Step title="Verify the upload">
    ```bash theme={null}
    vesslctl volume ls <volume-slug> --prefix /
    ```
  </Step>
</Steps>

<Info>
  Need S3-compatible access for DVC, `aws s3 cp`, or a custom pipeline? Run `vesslctl volume token <volume-slug>` to get temporary S3 credentials and an endpoint URL.
</Info>

***

## Submit a batch job

Submit a batch job, watch its progress, and pull the logs.

<Steps>
  <Step title="Submit the job">
    ```bash theme={null}
    vesslctl job create \
      --name nightly-train \
      --resource-spec <spec-name> \
      --image pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel \
      --cmd "python train.py --epochs 10 --lr 3e-4"
    ```
  </Step>

  <Step title="Check job status">
    ```bash theme={null}
    vesslctl job list
    ```
  </Step>

  <Step title="Stream the logs">
    ```bash theme={null}
    vesslctl job logs <job-slug> --follow
    ```

    Copy the job slug from `vesslctl job list` (such as `nightly-train-abc123`). The `--follow` flag streams logs in real time until the job completes.
  </Step>
</Steps>