baseten volume sync

Materialize remote content into a volume (PRE-RELEASE)

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. For authentication formats and examples, see Sync volumes from remote sources.

start

baseten volume sync start [OPTIONS]

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

--auth-aws-assume-role-arn · TEXT

AWS IAM role ARN for an s3:// source. Requires —auth-aws-assume-role-region.

--auth-aws-assume-role-region · TEXT

AWS region for the AssumeRole session. Requires —auth-aws-assume-role-arn.

--auth-aws-oidc-region · TEXT

AWS region for the OIDC role session. Requires —auth-aws-oidc-role-arn.

--auth-aws-oidc-role-arn · TEXT

AWS IAM role ARN to assume through OIDC for an s3:// source. Requires —auth-aws-oidc-region.

--auth-gcp-oidc-service-account · TEXT

GCP service account to impersonate through OIDC for a gs:// source. Requires —auth-gcp-oidc-workload-identity-provider.

--auth-gcp-oidc-workload-identity-provider · TEXT

Full GCP workload identity provider resource name. Requires —auth-gcp-oidc-service-account.

--auth-secret-name · TEXT

Baseten secret containing source credentials. Supported by hf://, s3://, gs://, azure://, r2://, and cw:// sources.

--dest · TEXT · required

Destination ref as bdn:namespace/volume, with an optional :tag.

--exclude · TEXT (repeatable)

Glob selecting source-relative files to exclude. May be repeated.

--include · TEXT (repeatable)

Glob selecting source-relative files to include. May be repeated.

-q, --jq · TEXT

Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)

-o, --output · TEXT · default: "text"

Output format

One of: text, json, jsonl, none

--profile · TEXT

Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile

--source · TEXT · required

Remote source URI. Supported schemes: hf://, s3://, gs://, azure://, r2://, cw://, and bt://.

--wait · BOOL

Poll until the sync reaches READY, FAILED, or CANCELED. Does not cancel the server-side job if interrupted.

-v, --verbose · BOOL

Enable verbose logging

Examples

Start a sync from a public Hugging Face repository

baseten volume sync start --source hf://<organization>/<repository> --dest bdn:<namespace>/<volume>:<tag>

Start an S3 sync using AWS AssumeRole and wait for it to finish

baseten volume sync start --source s3://<bucket>/<prefix> --dest bdn:<namespace>/<volume>:<tag> --auth-aws-assume-role-arn <role-arn> --auth-aws-assume-role-region <region> --wait

Start an S3 sync using AWS OIDC

baseten volume sync start --source s3://<bucket>/<prefix> --dest bdn:<namespace>/<volume>:<tag> --auth-aws-oidc-role-arn <role-arn> --auth-aws-oidc-region <region>

Start a GCS sync using GCP OIDC

baseten volume sync start --source gs://<bucket>/<prefix> --dest bdn:<namespace>/<volume>:<tag> --auth-gcp-oidc-service-account <service-account> --auth-gcp-oidc-workload-identity-provider <provider-resource-name>

Filter output with --jq

Start a sync and print its operation ID

baseten volume sync start --source hf://<organization>/<repository> --dest bdn:<namespace>/<volume> --jq '.sync_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

baseten volume sync describe [OPTIONS]

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

-q, --jq · TEXT

Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)

-o, --output · TEXT · default: "text"

Output format

One of: text, json, jsonl, none

--profile · TEXT

Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile

--sync-id · TEXT · required

ID of the volume sync operation.

-v, --verbose · BOOL

Enable verbose logging

Examples

Inspect a sync

baseten volume sync describe --sync-id <sync-id>

Filter output with --jq

Print the sync status

baseten volume sync describe --sync-id <sync-id> --jq '.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

baseten volume sync list [OPTIONS]

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

--dest · TEXT

Only return syncs whose destination exactly matches this ref.

-q, --jq · TEXT

Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)

-o, --output · TEXT · default: "text"

Output format

One of: text, json, jsonl, none

--profile · TEXT

Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile

-v, --verbose · BOOL

Enable verbose logging

Examples

List visible syncs

baseten volume sync list

List syncs for one exact destination

baseten volume sync list --dest bdn:<namespace>/<volume>:<tag>

Filter output with --jq

Print the IDs of failed syncs

baseten volume sync list --jq '.items[] | select(.status == "FAILED") | .sync_id'

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

baseten volume sync cancel [OPTIONS]

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

-q, --jq · TEXT

Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)

-o, --output · TEXT · default: "text"

Output format

One of: text, json, jsonl, none

--profile · TEXT

Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile

--sync-id · TEXT · required

ID of the volume sync operation.

-v, --verbose · BOOL

Enable verbose logging

Examples

Request cancellation of a sync

baseten volume sync cancel --sync-id <sync-id>

Filter output with --jq

Request cancellation and print the resulting status

baseten volume sync cancel --sync-id <sync-id> --jq '.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.