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

# vesslctl volume

> Manage data volumes for persistent storage across workspaces and jobs.

The `volume` command (alias: `vol`) lets you create and manage data volumes on VESSL Cloud. Volumes provide persistent storage that can be mounted into workspaces and jobs.

## list

List all volumes in the current team.

```bash theme={null}
vesslctl volume list
```

| Flag         | Short | Description                                             |
| ------------ | ----- | ------------------------------------------------------- |
| `--storage`  |       | Filter volumes by storage slug                          |
| `--type`     |       | Restrict to a single volume kind: `object` or `cluster` |
| `--page`     |       | Page number (1-based)                                   |
| `--per-page` |       | Items per page                                          |

## show

Display detailed information about a volume.

```bash theme={null}
vesslctl volume show <slug>
```

| Argument | Description        |
| -------- | ------------------ |
| `slug`   | Slug of the volume |

## create

Create a new volume on a specified storage backend.

```bash theme={null}
vesslctl volume create --name my-volume --storage <slug> --teams <team>
```

| Flag            | Short | Required | Description                                                       |
| --------------- | ----- | -------- | ----------------------------------------------------------------- |
| `--name`        |       | Yes      | Name for the volume                                               |
| `--storage`     |       | Yes      | Storage slug to create the volume on                              |
| `--teams`       |       | Yes      | Comma-separated list of teams that will have access to the volume |
| `--description` |       | No       | Human-readable description                                        |

**Example:**

```bash theme={null}
vesslctl volume create \
  --name training-data \
  --storage gcs-us-central1 \
  --teams ml-team,data-team \
  --description "ImageNet training dataset"
```

## ls

List file contents within an object volume. Cluster volumes are not supported.

```bash theme={null}
vesslctl volume ls <slug> --prefix /
```

| Flag       | Short | Description                                                |
| ---------- | ----- | ---------------------------------------------------------- |
| `--prefix` |       | Path prefix to list. Use `/` to list from the volume root. |

**Example:**

```bash theme={null}
vesslctl volume ls training-data-abc123 --prefix checkpoints/
```

## token

Get temporary S3-compatible credentials for direct access to an object volume. Returns the endpoint, bucket name, access key, and secret key. Cluster volumes are not supported.

```bash theme={null}
vesslctl volume token <slug>
```

**Example:**

```bash theme={null}
vesslctl volume token training-data-abc123
```

This is useful for integrating with tools that support S3 (for example, `aws s3 cp`, DVC, or custom data pipelines).

## update

Update an existing volume's metadata. Pass at least one of the flags below to apply a change.

```bash theme={null}
vesslctl volume update <slug> [flags]
```

| Flag            | Short | Description                           |
| --------------- | ----- | ------------------------------------- |
| `--name`        |       | New name for the volume               |
| `--description` |       | Updated description                   |
| `--teams`       |       | Updated comma-separated list of teams |

**Example:**

```bash theme={null}
vesslctl volume update training-data-abc123 \
  --description "ImageNet + COCO combined dataset" \
  --teams ml-team,data-team,research
```

## delete

Permanently delete a volume and its data.

```bash theme={null}
vesslctl volume delete <slug>
```

| Flag    | Short | Description              |
| ------- | ----- | ------------------------ |
| `--yes` | `-y`  | Skip confirmation prompt |

**Example:**

```bash theme={null}
vesslctl volume delete training-data-abc123 --yes
```

## upload

Upload local files to an object volume. Cluster volumes are not supported.

```bash theme={null}
vesslctl volume upload <slug> <local_path>
```

| Flag              | Short | Required | Description                                                       |
| ----------------- | ----- | -------- | ----------------------------------------------------------------- |
| `--remote-prefix` |       | No       | Path prefix within the volume (for example, `datasets/training/`) |
| `--exclude`       |       | No       | Glob patterns to exclude (for example, `*.pyc`). Repeatable.      |
| `--dry-run`       |       | No       | Print list of files without uploading                             |
| `--overwrite`     |       | No       | Overwrite existing remote files                                   |

**Example:**

```bash theme={null}
vesslctl volume upload training-data-abc123 ./local-dataset \
  --remote-prefix datasets/v1/ \
  --exclude "*.pyc" \
  --exclude "__pycache__"
```

## download

Download files from an object volume to a local directory. Cluster volumes are not supported.

```bash theme={null}
vesslctl volume download <slug> <local_path>
```

| Flag              | Short | Required | Description                                    |
| ----------------- | ----- | -------- | ---------------------------------------------- |
| `--remote-prefix` |       | No       | Path prefix within the volume to download from |
| `--exclude`       |       | No       | Glob patterns to exclude. Repeatable.          |
| `--dry-run`       |       | No       | Print list of files without downloading        |
| `--overwrite`     |       | No       | Overwrite existing local files                 |

**Example:**

```bash theme={null}
vesslctl volume download training-data-abc123 ./local-copy \
  --remote-prefix checkpoints/ \
  --overwrite
```