Skip to main content
PRE-RELEASE: Volume commands are not GA yet. Their arguments, flags, and output may change.
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

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

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
List every entry beneath the ref instead of only its immediate children.
​
BOOL
Enable verbose logging

​
Examples

List every namespace holding volumes
List the volumes in a namespace
List the files in the version head points at
List everything under a directory of a tagged version

​
Filter output with --jq

Print the path of every file in a version

​
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

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

​
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

Describe a volume
Describe one version
Describe one file in the version head points at

​
Filter output with --jq

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

​
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

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

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

Print a file from the version head points at
Save a file from a tagged version under a different name

​
Output

Text mode (--output text): The file’s bytes, exactly as the volume holds them. JSON mode (--output json): payload type cmd.JSONUndefined.

​
push

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

​
INTEGER
Number of files processed concurrently. Defaults to 16.
​
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
INTEGER
Cap on the chunk data held in memory, in MiB. Defaults to 2048.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
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.
​
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.
​
INTEGER
Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
​
BOOL
Enable verbose logging

​
Examples

Publish a directory as a new version
Publish and tag the new version

​
Filter output with --jq

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

​
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

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

​
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
​
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.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
INTEGER
Cap on the chunk data held in memory, in MiB. Defaults to 2048.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
BOOL
Allow writing into a non-empty directory. Files already there that the version does not describe are left alone.
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Discard a partly downloaded tree from an earlier attempt instead of continuing it.
​
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.
​
INTEGER
Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
​
BOOL
Enable verbose logging

​
Examples

Download the version head points at
Download one directory of a tagged version, without its leading path

​
Filter output with --jq

Print how many files were written

​
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

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

​
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Delete every live version of the volume. Required for a ref that names a volume rather than one version.
​
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
​
BOOL
Enable verbose logging

​
Examples

Delete one version
Delete every live version of a volume, without prompting

​
Filter output with --jq

Print when the deleted version stops being restorable

​
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

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

​
BOOL
Include deleted versions that are still inside their recovery window.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

List a volume’s versions
Include the deleted versions still inside their recovery window

​
Filter output with --jq

Print the digest of every tagged version

​
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

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

​
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

Restore a deleted version

​
Filter output with --jq

Print the lifecycle state the version came back in

​
Output

Text mode (--output text): One field per line, describing the restored version. JSON mode (--output json): payload type managementapi.RestoreVolumeVersionResponse.