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

​
start

Starts one durable asynchronous transfer from --source into --dest. 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, or GCP 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
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

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