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
--recursive for the flat list of everything beneath.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List every namespace holding volumesFilter 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
ls. stat accepts a volume, version, or path reference.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Describe a volumeFilter 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
--output json’ and ‘--jq’ are rejected here.
Use --chunk-operations and --max-in-flight-mib to control download concurrency and memory.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
Examples
Print a file from the version head points atOutput
Text mode (--output text): The file’s bytes, exactly as the volume holds them.
JSON mode (--output json): payload type cmd.JSONUndefined.
push
--tag. A digest or a path is an error.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.Tag to apply to the new version at commit. May be repeated, and adds to a tag written on REF.
Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
Examples
Publish a directory as a new versionFilter 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
--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
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.
Allow writing into a non-empty directory. Files already there that the version does not describe are left alone.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.
Maximum object operations in flight, honored exactly. Defaults to a count the transfer adapts to what the service will bear.
Examples
Download the version head points atFilter 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
--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
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Delete every live version of the volume. Required for a ref that names a volume rather than one version.
Examples
Delete one versionFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List a volume’s versionsFilter 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
--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
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Restore a deleted versionFilter 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
--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
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.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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.Examples
Point a tag at a versionFilter 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
--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
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Ref of the volume the tag belongs to, as bdn:
namespace/volume, with no selector and no path.Examples
Delete a tagFilter 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.--yes.
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.Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
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
--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
GCP service account to impersonate through OIDC for a gs:// source. Requires
--auth-gcp-oidc-workload-identity-provider.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.
Baseten secret containing source credentials. Supported by hf://, s3://, gs://, azure://, r2://, and cw:// sources.
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Remote source URI. Supported schemes: hf://, s3://, gs://, azure://, r2://, cw://, and bt://.
Poll until the sync reaches READY, FAILED, or CANCELED. Does not cancel the server-side job if interrupted.
Examples
Start a sync from a public Hugging Face repositoryFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Inspect a syncFilter 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
--dest to match one exact destination ref. The CLI follows every server page.
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
List visible syncsFilter 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
Options
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
Examples
Request cancellation of a syncFilter 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.