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

# Volume Commands

> Create and manage volumes from the command line — copy-mode archives, file-granular file operations, advisory locks, and snapshots with declaw volume.

`declaw volume` (alias `declaw vol`) manages [volumes](/features/volumes): persistent, owner-owned file stores you attach to sandboxes. The CLI covers copy-mode volumes, file-granular file operations, advisory locks, and capturing sandbox state into a new volume.

Attach a volume to a sandbox with `declaw sandbox create --volume <id>:<mount-path>[:mode[:subpath]]`.

## Lifecycle

```bash theme={null}
declaw volume create training-data --from-tar ./data.tar.gz   # named copy-mode volume
declaw volume empty --name workspace                          # empty file-granular volume
declaw volume ingest --name dataset --file ./data.tar.gz      # file-granular from a .tar.gz
declaw volume list                                            # alias: ls
declaw volume get vol-abc123
declaw volume delete vol-abc123
```

| Command                     | Args   | Flags                                               |
| --------------------------- | ------ | --------------------------------------------------- |
| `volume create <name>`      | name   | `--from-tar` (gzipped tar for initial contents)     |
| `volume empty`              |        | `--name` (required)                                 |
| `volume ingest`             |        | `--name` (required), `--file` (required, `.tar.gz`) |
| `volume list`               |        |                                                     |
| `volume get <volume-id>`    | volume |                                                     |
| `volume delete <volume-id>` | volume |                                                     |

## snapshot

Capture an absolute in-sandbox path into a **new** volume. The source sandbox is unchanged.

```bash theme={null}
declaw volume snapshot sbx-abc123 --path /workspace/out --name run-42
```

| Flag     | Default    | Description                                    |
| -------- | ---------- | ---------------------------------------------- |
| `--path` |            | Absolute in-sandbox path to capture (required) |
| `--name` | `snapshot` | Name for the new volume                        |

## files

Read and write files inside a **file-granular** volume directly — no sandbox required. Each subcommand takes the volume ID; paths are passed as flags.

```bash theme={null}
declaw volume files write vol-abc123 --path /notes.txt --content "hello"
declaw volume files write vol-abc123 --path /data.csv --file ./local.csv
declaw volume files list vol-abc123 --path /            # alias: ls
declaw volume files read vol-abc123 --path /notes.txt --output ./notes.txt
```

| Subcommand                 | Key flags                                                                       |
| -------------------------- | ------------------------------------------------------------------------------- |
| `files read <volume-id>`   | `--path` (required), `--output`/`-o`                                            |
| `files write <volume-id>`  | `--path` (required), `--file` or `--content`, `--if-version` (compare-and-swap) |
| `files list <volume-id>`   | `--path` (default `/`)                                                          |
| `files info <volume-id>`   | `--path` (required) — includes the version for CAS writes                       |
| `files exists <volume-id>` | `--path` (required)                                                             |
| `files rm <volume-id>`     | `--path` (required), `--recursive`/`-r`                                         |
| `files mv <volume-id>`     | `--old-path` (required), `--new-path` (required)                                |
| `files mkdir <volume-id>`  | `--path` (required)                                                             |

Pass the version from `files info` to `files write --if-version` for an atomic compare-and-swap (a mismatch is rejected).

## lock

Coordinate concurrent writers to a shared volume with advisory leases over a `(volume, path)` pair (alias `locks`). Locks are advisory — they coordinate cooperating writers, they don't block I/O.

```bash theme={null}
declaw volume lock acquire vol-abc123 --path /data/model.bin --ttl 60
declaw volume lock renew   vol-abc123 --path /data/model.bin --token <token> --ttl 60
declaw volume lock status  vol-abc123 --path /data/model.bin
declaw volume lock release vol-abc123 --path /data/model.bin --token <token>
```

| Subcommand                 | Key flags                                                                      |
| -------------------------- | ------------------------------------------------------------------------------ |
| `lock acquire <volume-id>` | `--path` (required), `--ttl` (seconds, `0` = server default) — returns a token |
| `lock renew <volume-id>`   | `--path`, `--token`, `--ttl`                                                   |
| `lock status <volume-id>`  | `--path` (required)                                                            |
| `lock release <volume-id>` | `--path`, `--token`                                                            |

## Next steps

* [Volumes](/features/volumes) — copy-mode vs file-granular, attach modes, limits
* [Sandbox commands](/cli/sandbox) — attach a volume at create time