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

# baseten volume

> Manage volumes (PRE-RELEASE)

<Note>
  PRE-RELEASE: Volume commands are not GA yet. Their arguments, flags, and output may change.
</Note>

Manage volumes: file trees stored once and mounted into models, training jobs, and Loops.

A volume holds versions. A version is an immutable file tree addressed by digest. A tag is a mutable name pointing at a version.

These commands address volumes positionally, the way filesystem commands address paths, so 'ls', 'stat', 'cat', and 'rm' read at whatever level of the tree the ref names. A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

## ls

```sh theme={"system"}
baseten volume ls [OPTIONS] [REF]
```

Lists what a ref contains. With no ref, lists the namespaces holding volumes your API key can read. A namespace ref lists its volumes. A volume or version ref lists that version's file entries, and a trailing path narrows to the entries under it, matched on slash boundaries so 'config' does not also match 'configuration.json'.

Entry listings show immediate children, with directory names and no aggregate size. Pass --recursive for the flat list of everything beneath.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-R, --recursive" type="BOOL">
  List every entry beneath the ref instead of only its immediate children.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List every namespace holding volumes

```sh theme={"system"}
baseten volume ls
```

List the volumes in a namespace

```sh theme={"system"}
baseten volume ls bdn:<namespace>
```

List the files in the version head points at

```sh theme={"system"}
baseten volume ls bdn:<namespace>/<volume>
```

List everything under a directory of a tagged version

```sh theme={"system"}
baseten volume ls --recursive bdn:<namespace>/<volume>:<tag>/<path>
```

### Filter output with `--jq`

Print the path of every file in a version

```sh theme={"system"}
baseten volume ls bdn:<namespace>/<volume> --jq '.items[].path'
```

### Output

**Text mode (`--output text`):** For entries, a table with columns: NAME, KIND, MODE, SIZE, MODIFIED, where a directory's name ends in '/' and carries no size. For namespaces, one column: NAMESPACE. For volumes, a table with columns: NAME, TAGS, HEAD SIZE, VERSIONS, UPDATED. Prints what was empty to stderr when a listing has no rows.

**JSON mode (`--output json`):** payload type `cmd.VolumeEntryList`.

An object with version\_ref and items, one entry per row, when the ref names a volume or a version. The two inventory shapes follow.

## stat

```sh theme={"system"}
baseten volume stat [OPTIONS] REF
```

Describes what a ref names. A volume ref describes the volume: its tags, head, and version counts. A version ref describes that version: its digest, size, entry count, and when it was created. A ref with a trailing path describes that one entry.

A namespace ref is an error, since a namespace has nothing to describe beyond the volumes 'ls' already lists.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--full-ref" type="BOOL">
  Write refs with the whole digest instead of shortening it to 12 hex characters.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Describe a volume

```sh theme={"system"}
baseten volume stat bdn:<namespace>/<volume>
```

Describe one version

```sh theme={"system"}
baseten volume stat bdn:<namespace>/<volume>@b3:<digest>
```

Describe one file in the version head points at

```sh theme={"system"}
baseten volume stat bdn:<namespace>/<volume>/<path>
```

### Filter output with `--jq`

Print the digest of the version head points at, to pin a config.yaml to it

```sh theme={"system"}
baseten volume stat bdn:<namespace>/<volume> --jq '.head.digest'
```

### Output

**Text mode (`--output text`):** One field per line, describing the volume, the version, or the entry.

**JSON mode (`--output json`):** payload type `managementapi.Volume`.

The volume, when the ref names one with no selector. The two other shapes follow.

## cat

```sh theme={"system"}
baseten volume cat [OPTIONS] REF
```

Writes one file's bytes to stdout, so it can be piped or redirected. The ref must carry a path naming a file: a ref naming a volume or a version has no single file to write, and a path naming a directory is an error.

Chunks are verified against the digests the version records before they are written, so a truncated or corrupted read fails rather than producing partial output that looks complete.

A file's bytes have no JSON form, so '--output json' and '--jq' are rejected here.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Print a file from the version head points at

```sh theme={"system"}
baseten volume cat bdn:<namespace>/<volume>/<path>
```

Save a file from a tagged version under a different name

```sh theme={"system"}
baseten volume cat bdn:<namespace>/<volume>:<tag>/<path> > local.json
```

### Output

**Text mode (`--output text`):** The file's bytes, exactly as the volume holds them.

**JSON mode (`--output json`):** payload type `cmd.JSONUndefined`.

## push

```sh theme={"system"}
baseten volume push [OPTIONS] DIR REF
```

Publishes DIR as a new version of the volume REF names, creating the volume if it does not exist. Only content the volume does not already hold is uploaded, so pushing a tree that mostly matches an existing version transfers only what differs.

Nothing is visible until the whole tree has been uploaded, so an interrupted push publishes nothing, and what it did upload is not wasted.

The ref may name a volume or a tag to apply to the new version, which is the same as passing that tag to --tag. A digest or a path is an error.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--file-jobs" type="INTEGER">
  Number of files processed concurrently. Defaults to 16.
</ParamField>

<ParamField body="--full-ref" type="BOOL">
  Write refs with the whole digest instead of shortening it to 12 hex characters.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--max-in-flight-mib" type="INTEGER">
  Cap on the chunk data held in memory, in MiB. Defaults to 2048.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--source-uri" type="TEXT">
  Where the tree came from, for example 'hf://`repo`@`revision`'. Defaults to a file URI for DIR and is part of the version's digest, so a fixed value keeps the same tree at one version across directories.
</ParamField>

<ParamField body="--tag" type="TEXT (repeatable)">
  Tag to apply to the new version at commit. May be repeated, and adds to a tag written on REF. Push is the only command where a tag is written rather than read.
</ParamField>

<ParamField body="--chunk-operations" type="INTEGER">
  Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Publish a directory as a new version

```sh theme={"system"}
baseten volume push ./weights bdn:<namespace>/<volume>
```

Publish and tag the new version

```sh theme={"system"}
baseten volume push ./weights bdn:<namespace>/<volume> --tag prod
```

### Filter output with `--jq`

Print the ref of the published version, which is what config.yaml takes

```sh theme={"system"}
baseten volume push ./weights bdn:<namespace>/<volume> --jq '.version_ref'
```

### Output

**Text mode (`--output text`):** A summary of what was published: the version ref and digest, the file and byte counts, how many chunks were uploaded, and any tags applied. Transfer progress goes to stderr.

**JSON mode (`--output json`):** payload type `cmd.VolumePushResult`.

## pull

```sh theme={"system"}
baseten volume pull [OPTIONS] REF DIR
```

Downloads what REF names into DIR. A volume or version ref pulls the whole tree; a trailing path pulls that subtree or that one file.

DIR is always a directory, and entries land at their volume-relative path under it, so pulling 'bdn:weights/llama/config/model.json' into './out' writes './out/config/model.json'. Pass --strip-prefix to drop the path the ref named, writing './out/model.json' instead.

Every chunk is verified against the digest the version records before it is written, and an interrupted download picks up where it stopped.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--full-ref" type="BOOL">
  Write refs with the whole digest instead of shortening it to 12 hex characters.
</ParamField>

<ParamField body="--include" type="TEXT (repeatable)">
  Restrict the download to this path in the volume, either a file or a directory whose contents are wanted, matched on slash boundaries. May be repeated, and is relative to the version's root whatever path the ref carries. One that matches nothing fails the download.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--max-in-flight-mib" type="INTEGER">
  Cap on the chunk data held in memory, in MiB. Defaults to 2048.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--overwrite" type="BOOL">
  Allow writing into a non-empty directory. Files already there that the version does not describe are left alone.
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--restart" type="BOOL">
  Discard a partly downloaded tree from an earlier attempt instead of continuing it.
</ParamField>

<ParamField body="--strip-prefix" type="BOOL">
  Write the contents of the directory the ref names directly into DIR, instead of under the path that led to them. Requires a path on the ref.
</ParamField>

<ParamField body="--chunk-operations" type="INTEGER">
  Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Download the version head points at

```sh theme={"system"}
baseten volume pull bdn:<namespace>/<volume> ./out
```

Download one directory of a tagged version, without its leading path

```sh theme={"system"}
baseten volume pull bdn:<namespace>/<volume>:<tag>/<path> ./out --strip-prefix
```

### Filter output with `--jq`

Print how many files were written

```sh theme={"system"}
baseten volume pull bdn:<namespace>/<volume> ./out --jq '.files'
```

### Output

**Text mode (`--output text`):** A summary of what was written: the version ref and digest, the destination, and the file and byte counts. Transfer progress goes to stderr.

**JSON mode (`--output json`):** payload type `cmd.VolumePullResult`.

## rm

```sh theme={"system"}
baseten volume rm [OPTIONS] REF
```

Deletes what REF names. A ref carrying a digest deletes that version. A volume ref deletes every live version of the volume and requires --recursive, so a ref that meant to name one version cannot take the whole volume with it.

A deleted version is recoverable with 'volume restore' for a limited window, which the output reports.

A tag ref is an error while tags cannot be mutated, and a path is an error because versions are immutable.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--full-ref" type="BOOL">
  Write refs with the whole digest instead of shortening it to 12 hex characters.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-r, --recursive" type="BOOL">
  Delete every live version of the volume. Required for a ref that names a volume rather than one version.
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Delete one version

```sh theme={"system"}
baseten volume rm bdn:<namespace>/<volume>@b3:<digest>
```

Delete every live version of a volume, without prompting

```sh theme={"system"}
baseten volume rm --recursive --yes bdn:<namespace>/<volume>
```

### Filter output with `--jq`

Print when the deleted version stops being restorable

```sh theme={"system"}
baseten volume rm --yes bdn:<namespace>/<volume>@b3:<digest> --jq '.delete_after'
```

### Output

**Text mode (`--output text`):** One field per line: what was deleted and until when it can be restored. Prompts for confirmation first unless --yes is passed.

**JSON mode (`--output json`):** payload type `managementapi.DeleteVolumeVersionResponse`.

The deleted version, when the ref names one. The whole-volume shape follows.

## versions

```sh theme={"system"}
baseten volume versions [OPTIONS] REF
```

Lists a volume's versions, newest first, with the digest, sequence, size, lifecycle, tags, and which one head points at.

The ref must name a volume: a selector or a path names one point in the history rather than the history itself.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--include-tombstoned" type="BOOL">
  Include deleted versions that are still inside their recovery window.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List a volume's versions

```sh theme={"system"}
baseten volume versions bdn:<namespace>/<volume>
```

Include the deleted versions still inside their recovery window

```sh theme={"system"}
baseten volume versions bdn:<namespace>/<volume> --include-tombstoned
```

### Filter output with `--jq`

Print the digest of every tagged version

```sh theme={"system"}
baseten volume versions bdn:<namespace>/<volume> --jq '.versions[] | select(.tags | length > 0) | .digest'
```

### Output

**Text mode (`--output text`):** Table with columns: SEQUENCE, DIGEST, SIZE, LIFECYCLE, HEAD, TAGS, CREATED. When the volume has no versions, prints "No volume versions found." to stderr.

**JSON mode (`--output json`):** payload type `managementapi.ListVolumeVersionsResponse`.

## restore

```sh theme={"system"}
baseten volume restore [OPTIONS] REF
```

Restores a deleted version during its recovery window, which 'volume rm' reports and 'volume versions --include-tombstoned' lists.

The ref must carry a digest, since deleting a version drops the tags that pointed at it, so a tag no longer names one.

A ref is 'bdn:`namespace`/`volume`', with an optional ':`tag`' or '@`digest`' selector and trailing path, as in 'bdn:weights/llama:prod/config/model.json'. The 'bdn:' is required; with no selector, the volume's head is used. A digest may be written with or without its 'b3:' prefix, and shortened to 12 or more hex characters.

### Options

<ParamField body="--full-ref" type="BOOL">
  Write refs with the whole digest instead of shortening it to 12 hex characters.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Restore a deleted version

```sh theme={"system"}
baseten volume restore bdn:<namespace>/<volume>@b3:<digest>
```

### Filter output with `--jq`

Print the lifecycle state the version came back in

```sh theme={"system"}
baseten volume restore bdn:<namespace>/<volume>@b3:<digest> --jq '.lifecycle'
```

### Output

**Text mode (`--output text`):** One field per line, describing the restored version.

**JSON mode (`--output json`):** payload type `managementapi.RestoreVolumeVersionResponse`.