> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# baseten volume sync

> Materialize remote content into a volume (PRE-RELEASE)

<Note>
  PRE-RELEASE: Volume commands are not GA yet. Their arguments, flags, and output may change.
</Note>

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

```sh theme={"system"}
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

<ParamField body="--auth-aws-assume-role-arn" type="TEXT">
  AWS IAM role ARN for an s3:// source. Requires --auth-aws-assume-role-region.
</ParamField>

<ParamField body="--auth-aws-assume-role-region" type="TEXT">
  AWS region for the AssumeRole session. Requires --auth-aws-assume-role-arn.
</ParamField>

<ParamField body="--auth-aws-oidc-region" type="TEXT">
  AWS region for the OIDC role session. Requires --auth-aws-oidc-role-arn.
</ParamField>

<ParamField body="--auth-aws-oidc-role-arn" type="TEXT">
  AWS IAM role ARN to assume through OIDC for an s3:// source. Requires --auth-aws-oidc-region.
</ParamField>

<ParamField body="--auth-gcp-oidc-service-account" type="TEXT">
  GCP service account to impersonate through OIDC for a gs\:// source. Requires --auth-gcp-oidc-workload-identity-provider.
</ParamField>

<ParamField body="--auth-gcp-oidc-workload-identity-provider" type="TEXT">
  Full GCP workload identity provider resource name. Requires --auth-gcp-oidc-service-account.
</ParamField>

<ParamField body="--auth-secret-name" type="TEXT">
  Baseten secret containing source credentials. Supported by hf://, s3://, gs\://, azure://, r2://, and cw:// sources.
</ParamField>

<ParamField body="--dest" type="TEXT" required>
  Destination ref as bdn:`namespace`/`volume`, with an optional :`tag`.
</ParamField>

<ParamField body="--exclude" type="TEXT (repeatable)">
  Glob selecting source-relative files to exclude. May be repeated.
</ParamField>

<ParamField body="--include" type="TEXT (repeatable)">
  Glob selecting source-relative files to include. May be repeated.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--source" type="TEXT" required>
  Remote source URI. Supported schemes: hf://, s3://, gs\://, azure://, r2://, cw://, and bt://.
</ParamField>

<ParamField body="--wait" type="BOOL">
  Poll until the sync reaches READY, FAILED, or CANCELED. Does not cancel the server-side job if interrupted.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Start a sync from a public Hugging Face repository

```sh theme={"system"}
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

```sh theme={"system"}
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

```sh theme={"system"}
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

```sh theme={"system"}
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

```sh theme={"system"}
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

```sh theme={"system"}
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

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--sync-id" type="TEXT" required>
  ID of the volume sync operation.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Inspect a sync

```sh theme={"system"}
baseten volume sync describe --sync-id <sync-id>
```

### Filter output with `--jq`

Print the sync status

```sh theme={"system"}
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

```sh theme={"system"}
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

<ParamField body="--dest" type="TEXT">
  Only return syncs whose destination exactly matches this ref.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List visible syncs

```sh theme={"system"}
baseten volume sync list
```

List syncs for one exact destination

```sh theme={"system"}
baseten volume sync list --dest bdn:<namespace>/<volume>:<tag>
```

### Filter output with `--jq`

Print the IDs of failed syncs

```sh theme={"system"}
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

```sh theme={"system"}
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

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--sync-id" type="TEXT" required>
  ID of the volume sync operation.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Request cancellation of a sync

```sh theme={"system"}
baseten volume sync cancel --sync-id <sync-id>
```

### Filter output with `--jq`

Request cancellation and print the resulting status

```sh theme={"system"}
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`.