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

> Workspace와 Job에서 사용할 수 있는 영구 Storage 데이터 Volume을 관리하는 방법을 알아봐요.

`volume` 명령어(별칭: `vol`)를 사용하면 VESSL Cloud에서 데이터 Volume을 생성하고 관리할 수 있어요. Volume은 Workspace와 Job에 마운트할 수 있는 영구 Storage를 제공해요.

## list

현재 팀의 모든 Volume을 조회해요.

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

| 플래그          | 약어 | 설명                                  |
| ------------ | -- | ----------------------------------- |
| `--storage`  |    | Storage 슬러그로 Volume 필터링             |
| `--type`     |    | Volume 종류 제한: `object` 또는 `cluster` |
| `--page`     |    | 페이지 번호(1부터 시작)                      |
| `--per-page` |    | 페이지당 항목 수                           |

## show

Volume의 상세 정보를 표시해요.

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

| 인자     | 설명           |
| ------ | ------------ |
| `slug` | Volume의 slug |

## create

지정된 저장소(storage)에 새 Volume을 생성해요.

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

| 플래그             | 약어 | 필수  | 설명                      |
| --------------- | -- | --- | ----------------------- |
| `--name`        |    | 예   | Volume 이름               |
| `--storage`     |    | 예   | Volume을 생성할 Storage 슬러그 |
| `--teams`       |    | 예   | Volume에 접근할 팀의 쉼표 구분 목록 |
| `--description` |    | 아니오 | 사람이 읽을 수 있는 설명          |

**예시:**

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

## ls

Object volume 내의 파일 목록을 조회해요. Cluster volume은 지원되지 않아요.

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

| 플래그        | 약어 | 설명                                  |
| ---------- | -- | ----------------------------------- |
| `--prefix` |    | 조회할 경로 프리픽스. 루트 전체를 보려면 `/`를 지정하세요. |

**예시:**

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

## token

Object volume에 직접 접근하기 위한 임시 S3 호환 자격 증명을 가져와요. 엔드포인트, 버킷 이름, 액세스 키, 시크릿 키가 반환돼요. Cluster volume은 지원되지 않아요.

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

**예시:**

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

S3를 지원하는 도구(`aws s3 cp`, DVC, 커스텀 데이터 파이프라인 등)와 연동할 때 유용해요.

## update

기존 Volume의 메타데이터를 업데이트해요. 아래 플래그 중 최소 하나는 지정해야 해요.

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

| 플래그             | 약어 | 설명                |
| --------------- | -- | ----------------- |
| `--name`        |    | 새 Volume 이름       |
| `--description` |    | 업데이트할 설명          |
| `--teams`       |    | 업데이트할 팀의 쉼표 구분 목록 |

**예시:**

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

## delete

Volume과 데이터를 영구적으로 삭제해요.

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

| 플래그     | 약어   | 설명           |
| ------- | ---- | ------------ |
| `--yes` | `-y` | 확인 프롬프트 건너뛰기 |

**예시:**

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

## upload

로컬 파일을 Object volume에 업로드해요. Cluster volume은 지원되지 않아요.

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

| 플래그               | 약어 | 필수  | 설명                                        |
| ----------------- | -- | --- | ----------------------------------------- |
| `--remote-prefix` |    | 아니오 | Volume 내 경로 프리픽스(예: `datasets/training/`) |
| `--exclude`       |    | 아니오 | 제외할 글로브 패턴(예: `*.pyc`). 반복 사용 가능.         |
| `--dry-run`       |    | 아니오 | 업로드하지 않고 파일 목록만 출력                        |
| `--overwrite`     |    | 아니오 | 기존 리모트 파일 덮어쓰기                            |

**예시:**

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

## download

Object volume의 파일을 로컬 디렉터리에 다운로드해요. Cluster volume은 지원되지 않아요.

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

| 플래그               | 약어 | 필수  | 설명                     |
| ----------------- | -- | --- | ---------------------- |
| `--remote-prefix` |    | 아니오 | 다운로드할 Volume 내 경로 프리픽스 |
| `--exclude`       |    | 아니오 | 제외할 글로브 패턴. 반복 사용 가능.  |
| `--dry-run`       |    | 아니오 | 다운로드하지 않고 파일 목록만 출력    |
| `--overwrite`     |    | 아니오 | 기존 로컬 파일 덮어쓰기          |

**예시:**

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