Skip to main content
Manage volumes: file trees stored once and mounted into models, training jobs, and Loops. For concepts and end-to-end workflows, see Volumes. A volume holds versions. A version is an immutable file tree addressed by digest. A tag is a mutable name pointing at a version. Use bdn: references to identify namespaces, volumes, versions, or paths within the organization associated with your Baseten credentials. Use bdn: without //. A volume reference without a tag or digest names the volume: stat returns its metadata, while file-reading commands such as ls and pull use its head version.

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.

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, with refs such as bdn:weights. JSON keeps bare namespace names. For volumes, a table with columns: NAME, TAGS, HEAD SIZE, VERSIONS, EXPIRES, UPDATED. An expiring tag is annotated with its expiry. 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, version counts, and scheduled expiry. A version ref describes that version: its digest, size, entry count, lifecycle timestamps, and when it was created. A ref with a trailing path describes that one entry. For a namespace listing, use ls. stat accepts a volume, version, or path reference.

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. Use --chunk-operations and --max-in-flight-mib to control download concurrency and memory.

Options

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

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.

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

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 reference is an error because it would delete the version the tag points at. Use tag delete to delete only the tag. A path is an error because versions are immutable.

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, scheduled expiry, 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.

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, EXPIRES, 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.

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.

tag

Manage a volume’s tags. A tag is a mutable name that points to one version. Setting the tag again moves it, while the previous version remains reachable by digest. baseten volume stat and baseten volume versions show a volume’s tags. baseten volume ls shows the tags in a namespace. Use bdn: references to identify volumes in the organization associated with your Baseten credentials. Write the prefix without //.

set

Point the tag in --tag to the version selected by --volume-ref. The command creates a tag that doesn’t exist. A volume reference without a selector uses the head version. A :<tag> or @<digest> selector uses that version. Don’t include a path because a tag names an entire version. Setting a tag that already exists overwrites it. Pass --expires-at to make the tag expire at that time. Setting it again without --expires-at clears the tag’s expiration time. The tag is still removed if its version or volume expires. --tag can be head. Setting it changes the default version for file reads and new deployment mounts. head can’t use --expires-at or point to an expiring version. Setting head prompts for confirmation unless you pass --yes.

Options

TEXT
Time at which the tag expires, as an RFC 3339 date-time with a UTC offset, as in 2030-01-01T00:00:00Z. It must be in the future and at most ten years ahead. Omit it for a tag that does not expire. Omitting it on an existing tag clears its expiration time.
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
TEXT
required
Tag to point at the version. May be ‘head’.
TEXT
required
Ref of the version to tag, as bdn:namespace/volume for the version head points at, or with a :tag or @digest selector for that version.
BOOL
Skip confirmation for ‘head’. Required when stdin is not a terminal and --tag is ‘head’.
BOOL
Enable verbose logging

Examples

Point a tag at a version
Move a tag to the version head points at
Point a tag at the version another tag selects, with the tag expiring at the start of 2030
Change the default version for file reads and new deployment mounts

Filter output with --jq

Print the ref of the version the tag now points at, pinned to its digest

Output

Text mode (--output text): One field per line: the ref of the version the tag now points at, the tag, the digest, when the tag expires, and the volume’s sequence. JSON mode (--output json): Returns the tag, digest, pinned version reference, expiration, and volume sequence.

delete

Delete the tag in --tag from the volume named by --volume-ref. The version remains reachable by digest and by any other tag. Deleting a tag that doesn’t exist succeeds and reports that the command made no change. --volume-ref must name a volume without a selector or path because a tag belongs to the volume, not to one version. Deleting head prevents file reads and new deployment mounts from selecting a default version until you set head again. Deleting head prompts for confirmation unless you pass --yes.

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
TEXT
required
Name of the tag to delete.
TEXT
required
Ref of the volume the tag belongs to, as bdn:namespace/volume, with no selector and no path.
BOOL
Skip confirmation for ‘head’. Required when stdin is not a terminal and --tag is ‘head’.
BOOL
Enable verbose logging

Examples

Delete a tag

Filter output with --jq

Print whether the tag existed

Output

Text mode (--output text): One field per line: the tag, whether the command deleted it, and the volume’s sequence. JSON mode (--output json): Returns the tag, whether the command deleted it, and the volume sequence.

update

Set or clear the expiration time for an entire volume. When it expires, every live version is deleted, every tag is removed, and the volume disappears from listings. Clearing expiration afterward doesn’t restore deleted versions. Each version remains restorable until its recovery deadline.
To cancel scheduled expiration, run:
The reference must name a volume without a selector or path. Exactly one expiration option is required. Both operations prompt for confirmation unless you pass --yes.
BOOL
Clear the volume’s expiration time.Mutually exclusive with other flags in group expiration.
TEXT
Time at which the volume expires, as an RFC 3339 date-time with a UTC offset, as in 2030-01-01T00:00:00Z. It must be in the future and at most ten years ahead.Mutually exclusive with other flags in group expiration.
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
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
BOOL
Enable verbose logging
The result includes the namespace, volume, expiration time, and volume sequence. For workflows and verification commands, see Manage volumes.

sync

Manage durable asynchronous jobs that copy one supported remote source into one BDN volume. A successful sync publishes an immutable volume version only after transfer and verification complete. For authentication formats and examples, see Sync volumes from remote sources.

start

Starts one durable asynchronous transfer from --source into --dest. Use a bdn: reference, without //, for the destination volume in your organization. The source URI scheme selects the provider: hf://, s3://, gs://, azure://, r2://, cw://, or bt://. Repeat --include and --exclude to filter source-relative paths. Remote credentials must already be stored as a Baseten secret or made available through AWS AssumeRole, AWS OIDC, GCP OIDC, or Hugging Face OIDC. The CLI infers the authentication method from the --auth-* flags and never accepts plaintext credentials. Omit every authentication flag for a public source. By default the command returns as soon as the server creates the job. Pass --wait to poll until it is READY, FAILED, or CANCELED. Progress is written to stderr and the final result to stdout. Pressing Ctrl+C while waiting stops the wait without cancelling the sync and prints the describe and cancel commands for it.

Options

TEXT
AWS IAM role ARN for an s3:// source. Requires --auth-aws-assume-role-region.
TEXT
AWS region for the AssumeRole session. Requires --auth-aws-assume-role-arn.
TEXT
AWS region for the OIDC role session. Requires --auth-aws-oidc-role-arn.
TEXT
AWS IAM role ARN to assume through OIDC for an s3:// source. Requires --auth-aws-oidc-region.
TEXT
GCP service account to impersonate through OIDC for a gs:// source. Requires --auth-gcp-oidc-workload-identity-provider.
TEXT
Full GCP workload identity provider resource name. Requires --auth-gcp-oidc-service-account.
TEXT
Hugging Face username for an account CI/CD identity, or namespace/repository for a repository trusted publisher. Only for hf:// sources; configure trust in Hugging Face first.
TEXT
Baseten secret containing source credentials. Supported by hf://, s3://, gs://, azure://, r2://, and cw:// sources.
TEXT
required
Destination ref as bdn:namespace/volume, with an optional :tag.
TEXT (repeatable)
Glob selecting source-relative files to exclude. May be repeated.
TEXT (repeatable)
Glob selecting source-relative files to include. May be repeated.
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
TEXT
required
Remote source URI. Supported schemes: hf://, s3://, gs://, azure://, r2://, cw://, and bt://.
BOOL
Poll until the sync reaches READY, FAILED, or CANCELED. Does not cancel the server-side job if interrupted.
BOOL
Enable verbose logging

Examples

Start a sync from a public Hugging Face repository
Start an S3 sync using AWS AssumeRole and wait for it to finish
Start an S3 sync using AWS OIDC
Start a GCS sync using GCP OIDC
Start a Hugging Face sync using OIDC with a configured trusted publisher

Filter output with --jq

Start a sync and print its operation ID

Output

Text mode (--output text): One field per line describing the sync. With --wait, the result is the terminal state and a successful result includes its immutable version ref. JSON mode (--output json): payload type managementapi.VolumeSync.

describe

Retrieves the current state of one sync. A READY sync includes the immutable version ref produced by the job; a FAILED sync includes a stable error code and redacted message.

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
TEXT
required
ID of the volume sync operation.
BOOL
Enable verbose logging

Examples

Inspect a sync

Filter output with --jq

Print the sync status

Output

Text mode (--output text): One field per line describing the sync and, when available, its result or error. JSON mode (--output json): payload type managementapi.VolumeSync.

list

Lists every sync visible in the active workspace, newest first. Pass --dest to match one exact destination ref. The CLI follows every server page.

Options

TEXT
Only return syncs whose destination exactly matches this ref.
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 visible syncs
List syncs for one exact destination

Filter output with --jq

Print the IDs of failed syncs

Output

Text mode (--output text): Table with columns: ID, STATUS, SOURCE, DESTINATION, SIZE, CREATED, COMPLETED. Prints “No volume syncs found.” to stderr when the list is empty. JSON mode (--output json): payload type cmd.VolumeSyncList.

cancel

Requests cancellation of one pending or syncing job. Cancellation is idempotent: a terminal sync is returned unchanged, and an artifact already published by a READY sync is not removed.

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
TEXT
required
ID of the volume sync operation.
BOOL
Enable verbose logging

Examples

Request cancellation of a sync

Filter output with --jq

Request cancellation and print the resulting status

Output

Text mode (--output text): One field per line describing the sync after the cancellation request. JSON mode (--output json): payload type managementapi.VolumeSync.