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

# cowboy cbfs

> Create volumes and read and write their files

`cowboy cbfs` is the full client for Cowboy's encrypted file storage: it creates volumes, uploads and downloads files, and commits changes. A volume pays rent from its escrow, so one with too little escrow can stop being served; `--initial-escrow` sets it at creation.

```bash theme={"system"}
cowboy cbfs volume create --name site
cowboy cbfs put site ./index.html
```

To browse what already exists, [`cowboy volume`](https://docs.cowboy.inc/cli-specs/cowboy-volume) is simpler.

```text theme={"system"}
cowboy cbfs [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`capabilities`](#cowboy-cbfs-capabilities) | Report offline executable capabilities as JSON |
| [`login`](#cowboy-cbfs-login) | Log in to Cowboy via browser wallet (wallet key never touches this machine) |
| [`auth`](#cowboy-cbfs-auth) | Configure CBFS auth and delegation (advanced — prefer `cbfs login`) |
| [`whoami`](#cowboy-cbfs-whoami) | Show authenticated account identity and storage summary |
| [`balance`](#cowboy-cbfs-balance) | Show account storage reserve and usage |
| [`volume`](#cowboy-cbfs-volume) | Manage volumes |
| `public-review` | Copy and verify a pinned Public volume for Store review Run `cowboy cbfs public-review --help`. |
| [`put`](#cowboy-cbfs-put) | Upload a file to a volume |
| [`put-many`](#cowboy-cbfs-put-many) | Bulk-upload many files to a volume in a single open/commit cycle |
| [`courier`](#cowboy-cbfs-courier) | Place shards a browser encrypted and sealed (ciphertext only) |
| [`get`](#cowboy-cbfs-get) | Download a file from a volume |
| [`ls`](#cowboy-cbfs-ls) | List objects in a volume |
| [`rm`](#cowboy-cbfs-rm) | Remove an object from a volume |
| [`cat`](#cowboy-cbfs-cat) | Stream an object's contents to stdout |
| [`commit`](#cowboy-cbfs-commit) | Commit the current manifest |
| [`root`](#cowboy-cbfs-root) | Print the volume's current manifest root (hex) |
| [`tx`](#cowboy-cbfs-tx) | Compare-and-swap batch: refuse (exit 3) unless the manifest root equals `--expect-root`, then stage the JSON batch of puts/removes and commit once |
| [`status`](#cowboy-cbfs-status) | Check storage node reachability |
| [`salvage`](#cowboy-cbfs-salvage) | Recover a standalone/embedded volume left dangling by a torn commit |
| [`reset-state`](#cowboy-cbfs-reset-state) | Archive the entire CLI state root to a sibling path, then exit |
| `relay` | Operator tooling: register relays on chain and update their capacity Run `cowboy cbfs relay --help`. |
| [`rebalance`](#cowboy-cbfs-rebalance) | Move shards off a specified relay while it stays online |

| Option | Description |
| - | - |
| `--env <ENV>` | Cowboy environment whose RPC managed auth uses (cowboy cbfs only); `--rpc-url` overrides its endpoint |

`cowboy cbfs` commands share these options, unless a command's `--help` leaves one out:

| Option | Description |
| - | - |
| `--json` | Output JSON instead of human-readable text |
| `--dev` | Force standalone/dev mode (incompatible with public-review) |
| `--state-dir <STATE_DIR>` | State directory (default: \~/.cbfs/) |
| `--rpc-url <RPC_URL>` | Override the Cowboy RPC base URL. Anonymous reads otherwise use CBFS\_RPC\_URL, then config.toml in the state directory; cowboy cbfs managed auth needs this or a named Cowboy environment |
| `--wallet-key <WALLET_KEY>` | Use this wallet to prepare CBFS publication access |
| `--wallet-key-stdin` | Read exactly 32 raw wallet-key bytes from piped stdin |
| `--require-ready-auth` | Require an already prepared and registered publication credential. Never enroll or renew during this command |
| `--spend-ledger <FILE>` | Reserve every wallet-paid transaction's worst-case gas in this JSON file before signing it, and refuse one that would take the file's total past `--spend-limit-wei`. The file is the evidence of what was reserved; it accumulates across runs |
| `--spend-limit-wei <WEI>` | The most the `--spend-ledger` file may reserve in total, in wei |
| `--trusted-checkpoint <FILE>` | Independently pinned checkpoint file, or `-` for stdin; required for public-review. Required for public-review to authenticate volume roots and storage rent. Also required to create or rewrap a PRIVATE volume: those operations seal the volume DEK to a committee key read from the chain, and without an anchor the CLI cannot tell a real key from one a malicious RPC made up. The anchor deliberately cannot come from the RPC being verified. V2 finality proofs keep the same checkpoint usable across long block distances while its consensus identity and epoch remain unchanged. A committee transition currently fails closed until a transition proof is implemented. A new checkpoint alone does not authorize a transition; never adopt a candidate from the RPC being verified. For re-genesis, stop the CLI and run `--state-dir <DIR> reset-state` to archive the complete state root. |

## cowboy cbfs capabilities

Report offline executable capabilities as JSON

```text theme={"system"}
cowboy cbfs capabilities [OPTIONS]
```

## cowboy cbfs login

Log in to Cowboy via browser wallet (wallet key never touches this machine)

```text theme={"system"}
cowboy cbfs login [OPTIONS] <RPC_URL>
```

| Argument | Description |
| - | - |
| `<RPC_URL>` | Cowboy RPC URL (e.g. [http://localhost:4000](http://localhost:4000)) |

| Option | Description |
| - | - |
| `--network <NETWORK>` | Override the chain network name discovered from Cowboy RPC |
| `--chain-id <CHAIN_ID>` | Override the chain ID discovered from Cowboy RPC |
| `--no-passphrase` | Skip passphrase encryption for cbfs key |

## cowboy cbfs auth

Configure CBFS auth and delegation (advanced — prefer `cbfs login`)

```text theme={"system"}
cowboy cbfs auth [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`ensure-deploy`](#cowboy-cbfs-auth-ensure-deploy) | Prepare or reuse narrow CBFS publication access and report registration readiness |
| [`drive-delegation-verify`](#cowboy-cbfs-auth-drive-delegation-verify) | Verify a signed native Drive delegation offline and print \{"valid":bool} |
| [`setup`](#cowboy-cbfs-auth-setup) | Generate a delegated cbfs key and store local Cowboy config |
| [`status`](#cowboy-cbfs-auth-status) | Show local delegation status |
| [`renew`](#cowboy-cbfs-auth-renew) | Extend the existing certificate by 30 days while keeping its signing key |
| [`register`](#cowboy-cbfs-auth-register) | Register the stored delegated key on the current chain if it is not registered there (after a re-genesis, or a setup whose registration failed). |
| [`rotate`](#cowboy-cbfs-auth-rotate) | Rotate the delegated cbfs keypair |
| [`revoke`](#cowboy-cbfs-auth-revoke) | Revoke the delegated cbfs key and remove it locally |
| [`grant-key`](#cowboy-cbfs-auth-grant-key) | Show (or create) the X25519 grant-encryption key a volume owner seals a DEK to when granting this identity direct access (CIP-9 §9.2.1). |
| `delegation-prepare` | Non-interactive step 1: generate a cbfs key and emit the unsigned delegation cert + RAS delegation (plus hashes) as JSON for a remote wallet to sign. Run `cowboy cbfs auth delegation-prepare --help`. |
| `delegation-complete` | Non-interactive step 2: attach wallet signatures to the prepared cert + RAS delegation, persist them, save config, and confirm the signing wallet registered the RAS delegation on chain (a wallet-paid transaction this command cannot send) Run `cowboy cbfs auth delegation-complete --help`. |
| `delegation-register-tx` | Print the registration of a `delegation-prepare` RAS delegation, once its wallet signed it, as an unsigned transaction for that wallet to sign and send. Run `cowboy cbfs auth delegation-register-tx --help`. |

### cowboy cbfs auth ensure-deploy

Prepare or reuse narrow CBFS publication access and report registration readiness

```text theme={"system"}
cowboy cbfs auth ensure-deploy [OPTIONS]
```

### cowboy cbfs auth drive-delegation-verify

Verify a signed native Drive delegation offline and print \{"valid":bool}

```text theme={"system"}
cowboy cbfs auth drive-delegation-verify [OPTIONS] --ras <RAS> --wallet <WALLET>
```

| Option | Description |
| - | - |
| `--ras <RAS>` | |
| `--chain-identity <CHAIN_IDENTITY>` | |
| `--wallet <WALLET>` | |
| `--current-epoch <CURRENT_EPOCH>` | The chain's current storage epoch. Required for bounded delegations; without it only the legacy unbounded shape passes |

### cowboy cbfs auth setup

Generate a delegated cbfs key and store local Cowboy config

Missing `--rpc-url` / `--wallet-key` use \~/.cowboy/config.json: shell COWBOY\_ENV, then the canonical project's saved selection, then the global active profile. Repository profiles are never trusted.

`--network` and `--chain-id` are discovered from Cowboy RPC by default. Pass explicit values only to override the chain's advertised identity.

```text theme={"system"}
cowboy cbfs auth setup [OPTIONS]
```

| Option | Description |
| - | - |
| `--rpc-url <RPC_URL>` | |
| `--wallet-key <WALLET_KEY>` | |
| `--network <NETWORK>` | Chain network name — must match the validator's RAS\_NETWORK constant |
| `--chain-id <CHAIN_ID>` | Chain ID — must match validator's genesis.chain\_id |
| `--no-passphrase` | |

### cowboy cbfs auth status

Show local delegation status

```text theme={"system"}
cowboy cbfs auth status [OPTIONS]
```

### cowboy cbfs auth renew

Extend the existing certificate by 30 days while keeping its signing key

```text theme={"system"}
cowboy cbfs auth renew [OPTIONS]
```

| Option | Description |
| - | - |
| `--wallet-key <WALLET_KEY>` | Wallet key file; defaults to the active .cowboy/config.json wallet |
| `--if-expiring-within <IF_EXPIRING_WITHIN>` | Renew only when at most this many days remain (expired certs are due) |

### cowboy cbfs auth register

Register the stored delegated key on the current chain if it is not registered there (after a re-genesis, or a setup whose registration failed). Keeps the key; wallet-paid

```text theme={"system"}
cowboy cbfs auth register [OPTIONS]
```

| Option | Description |
| - | - |
| `--wallet-key <WALLET_KEY>` | Wallet key file; defaults to the active .cowboy/config.json wallet |

### cowboy cbfs auth rotate

Rotate the delegated cbfs keypair

```text theme={"system"}
cowboy cbfs auth rotate [OPTIONS]
```

| Option | Description |
| - | - |
| `--wallet-key <WALLET_KEY>` | |
| `--no-passphrase` | |

### cowboy cbfs auth revoke

Revoke the delegated cbfs key and remove it locally

```text theme={"system"}
cowboy cbfs auth revoke [OPTIONS]
```

### cowboy cbfs auth grant-key

Show (or create) the X25519 grant-encryption key a volume owner seals a DEK to when granting this identity direct access (CIP-9 §9.2.1). Prints the codec key string to pass verbatim to the owner's `volume allow --encryption-key` flag

```text theme={"system"}
cowboy cbfs auth grant-key [OPTIONS]
```

| Option | Description |
| - | - |
| `--no-passphrase` | Store the new key unencrypted (only if creating one) |

## cowboy cbfs whoami

Show authenticated account identity and storage summary

```text theme={"system"}
cowboy cbfs whoami [OPTIONS]
```

## cowboy cbfs balance

Show account storage reserve and usage

```text theme={"system"}
cowboy cbfs balance [OPTIONS]
```

## cowboy cbfs volume

Manage volumes

```text theme={"system"}
cowboy cbfs volume [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`create`](#cowboy-cbfs-volume-create) | Create a new volume |
| [`commitment`](#cowboy-cbfs-volume-commitment) | Read a volume commitment from chain state without local volume metadata |
| [`link`](#cowboy-cbfs-volume-link) | Link a volume ANOTHER account owns, on which this identity holds a direct-client grant (CIP-9 §7.7.1), under a local name. |
| [`list`](#cowboy-cbfs-volume-list) | List known volumes |
| [`info`](#cowboy-cbfs-volume-info) | Show volume details |
| [`deposit`](#cowboy-cbfs-volume-deposit) | Top up the rent escrow on an existing volume |
| [`allow`](#cowboy-cbfs-volume-allow) | Grant or revoke another principal's right to mount this volume (CIP-9 §7.7). |
| [`transfer`](#cowboy-cbfs-volume-transfer) | Transfer ownership of a volume to another account (CIP-9 §13.4). |
| [`rewrap`](#cowboy-cbfs-volume-rewrap) | Re-wrap a private volume DEK to the current CBSS account release key |
| [`attachment`](#cowboy-cbfs-volume-attachment) | Emit a VolumeRuntimeAttachment (JSON) for an existing volume so an off-chain relay/runner can open it directly with an owner CapToken — no dispatcher-issued runner token required. |
| [`migrate-placements`](#cowboy-cbfs-volume-migrate-placements) | Backfill durable placement records for pre-placement-era manifests (volumes with inactive owners): objects whose PlacementRecord is missing from every node get their assumed record published, so autonomous repair has a durable starting point |

### cowboy cbfs volume create

Create a new volume.

In Cowboy mode, an `(owner, name)` remains retired after its volume is transferred, garbage-collected, or reaped. Reusing it fails with `E_VOLUME_ID_OCCUPIED`; choose a new name.

```text theme={"system"}
cowboy cbfs volume create [OPTIONS] --name <NAME>
```

| Option | Description |
| - | - |
| `--name <NAME>` | Volume name (used as directory name under \~/.cbfs/) |
| `--nodes <NODES>` | Storage node addresses — required in dev mode, optional in cowboy mode |
| `--k <K>` | Number of data shards. Default: `3`. |
| `--m <M>` | Number of parity shards. Default: `2`. |
| `--public` | Create a public (unencrypted) volume |
| `--owner-key` | Also store an owner-wallet-derived DEK wrap so the owner CLI can read/write this private volume directly |
| `--initial-escrow <CBY>` | Initial rent escrow to deposit at create time, in CBY (decimal, up to 9 fractional digits). Defaults in cowboy mode to 30 epochs' rent, at least 0.01 CBY, plus about four ordinary escrow-paid writes' holds at the node's current fee caps, so the first writes can be admitted. An amount below one write's hold is warned about |
| `--private-sealed <PRIVATE_SEALED>` | Browser-sealed private create JSON: file path or @JSON |
| `--build-tx` | Print the create as an unsigned transaction for the owner's wallet to sign and send, instead of sending it. Only `--public` and `--private-sealed` creates; nothing is written locally |
| `--from <FROM>` | The wallet (0x address) that signs and sends the `--build-tx` transaction |

### cowboy cbfs volume commitment

Read a volume commitment from chain state without local volume metadata

```text theme={"system"}
cowboy cbfs volume commitment [OPTIONS] --name <NAME>
```

| Option | Description |
| - | - |
| `--name <NAME>` | |

### cowboy cbfs volume link

Link a volume ANOTHER account owns, on which this identity holds a direct-client grant (CIP-9 §7.7.1), under a local name. Reads then use this identity's own delegation and grant key; nothing of the owner's

```text theme={"system"}
cowboy cbfs volume link [OPTIONS] --owner <OWNER> --name <NAME>
```

| Option | Description |
| - | - |
| `--owner <OWNER>` | Owner's account address (0x-prefixed) |
| `--name <NAME>` | Volume name in the owner's namespace |
| `--as <LOCAL_NAME>` | Local name (default: the owner's name) |

### cowboy cbfs volume list

List known volumes

```text theme={"system"}
cowboy cbfs volume list [OPTIONS]
```

### cowboy cbfs volume info

Show volume details

```text theme={"system"}
cowboy cbfs volume info [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

### cowboy cbfs volume deposit

Top up the rent escrow on an existing volume.

The chain refuses deposits to `Deleted` or `GarbageCollecting` volumes before debiting the payer.

```text theme={"system"}
cowboy cbfs volume deposit [OPTIONS] --amount <CBY> <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

| Option | Description |
| - | - |
| `--amount <CBY>` | Amount to deposit, in CBY (decimal, up to 9 fractional digits) |
| `--build-tx` | Print the deposit as an unsigned transaction for `--from` to sign and send, instead of sending it |
| `--from <FROM>` | The wallet (0x address) that signs, sends and pays the `--build-tx` deposit |
| `--volume-id <HEX>` | The 32-byte volume id (hex) a `--build-tx` or `--owner` deposit must fund, known independently of the RPC; its resolution of the name must agree |
| `--owner <ADDRESS>` | Fund another owner's volume: `name` is that owner's (0x address), not yours. Needs `--volume-id` |

### cowboy cbfs volume allow

Grant or revoke another principal's right to mount this volume (CIP-9 §7.7). Needed whenever an actor must read a PRIVATE volume the caller owns.

Against the deployed chain a PUBLIC volume mounts with no grant at all — the dispatcher's gate is `visibility == Private && owner != submitter && !authorizes_mount(..)`, so a public volume never reaches the allowlist check. Do not rely on the allowlist to gate a public volume.

That is not a reason to publish a volume instead of granting: a document corpus belongs in a private volume, and making it public to skip this step exposes it to everyone.

The chain keys grants and removals by bare grantee address, regardless of whether `--actor` or `--account` supplied it.

```text theme={"system"}
cowboy cbfs volume allow [OPTIONS] [NAME]
```

| Argument | Description |
| - | - |
| `[NAME]` | Volume name (positional form retained for local grants) |

| Option | Description |
| - | - |
| `--name <NAME_FLAG>` | Volume name for sealed-grant provisioning |
| `--sealed-grant <SEALED_GRANT>` | Browser-sealed grant JSON: one object or an array of 1–64 grants; file path or @JSON. Submits one atomic allowlist update |
| `--actor <ACTOR>` | Actor-principal address to grant (0x-prefixed). Use this when the job submitter is an actor — whether or not it was deployed with a manifest. Repeat `--actor` with `--remove` for batch removal |
| `--account <ACCOUNT>` | Account-principal address to grant (0x-prefixed). Use this when the job submitter is a plain EOA. Repeat `--account` with `--remove` for batch removal. The allowlist is keyed by bare address regardless of the principal type. |
| `--mode <MODE>` | Access mode granted: ro \| rw. Default: `ro`. |
| `--prefix <PREFIX>` | Restrict the grant to paths under this prefix, RELATIVE to the volume root and with no leading slash (`docs`, not `/docs`). Default: the whole volume. Only a CIP-9 job attachment honours a scoped grant. Registering a CIP-10 workload asks the allowlist for the EMPTY prefix, which no scoped grant covers, so a scoped grant authorizes no workload mount at all. Leave this unset for that case. Default: `""`. |
| `--until <UNTIL>` | Expire the grant at this block height (default: no expiry) |
| `--signing-key <SIGNING_KEY>` | Make this a DIRECT-CLIENT grant (CIP-9 §7.7.1): the grantee's cbfs Ed25519 delegated public key (codec key string) — the key its `cbfs auth setup` registered on chain. The grantee may then open this volume with its own delegation. Requires an empty `--prefix` |
| `--encryption-key <ENCRYPTION_KEY>` | The grantee's codec key string (0x0120 followed by 64 lowercase hex characters), exactly as printed by `cbfs auth grant-key`. Required with `--signing-key` on a PRIVATE volume: the volume DEK is sealed to it (CIP-9 §9.2.1) |
| `--remove` | Remove 1–64 principals in one atomic allowlist update. Repeat `--account` and/or `--actor` for each address |

### cowboy cbfs volume transfer

Transfer ownership of a volume to another account (CIP-9 §13.4). Public volumes only for now

```text theme={"system"}
cowboy cbfs volume transfer [OPTIONS] --to <TO> <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

| Option | Description |
| - | - |
| `--to <TO>` | New owner's account address (hex) |

### cowboy cbfs volume rewrap

Re-wrap a private volume DEK to the current CBSS account release key

```text theme={"system"}
cowboy cbfs volume rewrap [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

### cowboy cbfs volume attachment

Emit a VolumeRuntimeAttachment (JSON) for an existing volume so an off-chain relay/runner can open it directly with an owner CapToken — no dispatcher-issued runner token required. Public volumes only need the token + relay endpoints; private volumes additionally require dispatcher-issued CBSS key-release material (not minted here)

```text theme={"system"}
cowboy cbfs volume attachment [OPTIONS] --name <NAME>
```

| Option | Description |
| - | - |
| `--name <NAME>` | Volume name |
| `--access-mode <ACCESS_MODE>` | Access mode for the minted owner token. Default: `read-write`. Values: `read-only, read-write, write-only`. |
| `--emit-json` | Print the attachment as compact JSON on stdout (for piping to a file) |

### cowboy cbfs volume migrate-placements

Backfill durable placement records for pre-placement-era manifests (volumes with inactive owners): objects whose PlacementRecord is missing from every node get their assumed record published, so autonomous repair has a durable starting point

```text theme={"system"}
cowboy cbfs volume migrate-placements [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

## cowboy cbfs put

Upload a file to a volume

```text theme={"system"}
cowboy cbfs put [OPTIONS] <NAME> <LOCAL_PATH> [REMOTE_PATH]
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |
| `<LOCAL_PATH>` | Local file path |
| `[REMOTE_PATH]` | Remote object path (defaults to filename) |

| Option | Description |
| - | - |
| `--content-type <MIME>` | Override manifest content\_type for this object |

## cowboy cbfs put-many

Bulk-upload many files to a volume in a single open/commit cycle.

`cbfs put` is open + put + commit per call, which makes batch ingest O(N²) — each subsequent put refetches and reuploads a manifest that grows with every file. `put-many` opens once, puts every entry, and commits once at the end. Input is a JSON array of `{"local": "...", "remote": "..."}` from a file or `-` for stdin.

```text theme={"system"}
cowboy cbfs put-many [OPTIONS] --from-json <PATH> <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

| Option | Description |
| - | - |
| `--from-json <PATH>` | Path to a JSON file with `[{"local": "...", "remote": "..."}, ...]` entries. Use `-` to read from stdin |

## cowboy cbfs courier

Place shards a browser encrypted and sealed (ciphertext only)

```text theme={"system"}
cowboy cbfs courier [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`put`](#cowboy-cbfs-courier-put) | Place prebuilt ciphertext shards and sealed manifest nodes on relays |
| [`manifest-nodes`](#cowboy-cbfs-courier-manifest-nodes) | Fetch the prior manifest's sealed nodes (ciphertext) and object placement records, for a write after the first (contract endpoint B) |

### cowboy cbfs courier put

Place prebuilt ciphertext shards and sealed manifest nodes on relays.

Reads a courier-contract-v1 request (JSON) and prints the placements the commit needs. A refusal prints `{"error": ...}` and exits 3.

```text theme={"system"}
cowboy cbfs courier put [OPTIONS] --from-json <PATH>
```

| Option | Description |
| - | - |
| `--from-json <PATH>` | Request JSON file, or `-` for stdin |

### cowboy cbfs courier manifest-nodes

Fetch the prior manifest's sealed nodes (ciphertext) and object placement records, for a write after the first (contract endpoint B)

```text theme={"system"}
cowboy cbfs courier manifest-nodes [OPTIONS] --from-json <PATH>
```

| Option | Description |
| - | - |
| `--from-json <PATH>` | Request JSON file, or `-` for stdin |

## cowboy cbfs get

Download a file from a volume

```text theme={"system"}
cowboy cbfs get [OPTIONS] <NAME> <REMOTE_PATH> [LOCAL_PATH]
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name (or a raw volume id with `--id`) |
| `<REMOTE_PATH>` | Remote object path |
| `[LOCAL_PATH]` | Local file path (defaults to filename) |

| Option | Description |
| - | - |
| `--id` | Interpret NAME as a raw volume id (64 hex chars) and read the PUBLIC volume anonymously — no wallet, delegation, or CapToken (CIP-9 open public reads) |

## cowboy cbfs ls

List objects in a volume

```text theme={"system"}
cowboy cbfs ls [OPTIONS] <NAME> [PREFIX]
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name (or a raw volume id with `--id`) |
| `[PREFIX]` | Path prefix filter |

| Option | Description |
| - | - |
| `--id` | Interpret NAME as a raw volume id (64 hex chars) and read the PUBLIC volume anonymously — no wallet, delegation, or CapToken (CIP-9 open public reads) |
| `--full-hashes` | Report the complete 32-byte content hash instead of its short prefix |

## cowboy cbfs rm

Remove an object from a volume

```text theme={"system"}
cowboy cbfs rm [OPTIONS] <NAME> <REMOTE_PATH>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |
| `<REMOTE_PATH>` | Remote object path |

## cowboy cbfs cat

Stream an object's contents to stdout

```text theme={"system"}
cowboy cbfs cat [OPTIONS] <NAME> <REMOTE_PATH>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name (or a raw volume id with `--id`) |
| `<REMOTE_PATH>` | Remote object path |

| Option | Description |
| - | - |
| `--id` | Interpret NAME as a raw volume id (64 hex chars) and read the PUBLIC volume anonymously — no wallet, delegation, or CapToken (CIP-9 open public reads) |
| `--max-bytes <BYTES>` | Refuse objects larger than this many bytes before downloading them |

## cowboy cbfs commit

Commit the current manifest

```text theme={"system"}
cowboy cbfs commit [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

## cowboy cbfs root

Print the volume's current manifest root (hex)

```text theme={"system"}
cowboy cbfs root [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

## cowboy cbfs tx

Compare-and-swap batch: refuse (exit 3) unless the manifest root equals `--expect-root`, then stage the JSON batch of puts/removes and commit once.

Batch shape: `{"puts":[{"remote":"path","data_b64":"...","content_type":null}], "removes":["path"]}` from a file or `-` for stdin.

```text theme={"system"}
cowboy cbfs tx [OPTIONS] --expect-root <HEX> --from-json <PATH> <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | Volume name |

| Option | Description |
| - | - |
| `--expect-root <HEX>` | Manifest root (hex) the batch was computed against |
| `--from-json <PATH>` | Batch JSON path, or `-` for stdin |
| `--split` | Land a batch too large for one fundable commit as ordered sub-commits instead of refusing it. Gives up all-or-nothing: a failure can leave the earlier sub-commits landed |

## cowboy cbfs status

Check storage node reachability

```text theme={"system"}
cowboy cbfs status [OPTIONS]
```

| Option | Description |
| - | - |
| `--nodes <NODES>` | Node addresses (comma-separated) |
| `--name <NAME>` | Or: use nodes from a named volume |

## cowboy cbfs salvage

Recover a standalone/embedded volume left dangling by a torn commit.

When a standalone relay dies after recording a manifest root but before its manifest-node shards are flushed, the volume re-opens against a root that references shards on no node ("only got 0/K manifest shards"). This rebuilds every complete manifest DAG still recoverable from the surviving shards and, with `--apply`, repoints the authoritative root at the newest intact one. Offline and read-only unless `--apply` is given.

Point it at the store's data directory (the one holding `chain/`, `volume.json`, and the node blob-store dirs).

Run a `cbfs` built at the SAME cbfs revision as the relay that wrote the store: the manifest-node wire format is not forward-compatible, so a newer binary silently reconstructs nothing from an older store.

```text theme={"system"}
cowboy cbfs salvage [OPTIONS] <DATA_DIR>
```

| Argument | Description |
| - | - |
| `<DATA_DIR>` | Path to the standalone CBFS data directory |

| Option | Description |
| - | - |
| `--apply <ROOT_HEX>` | Repoint the authoritative root at this 32-byte manifest root (hex), as reported by a prior scan. Without it, only scans and reports |

## cowboy cbfs reset-state

Archive the entire CLI state root to a sibling path, then exit.

Use only for re-genesis after stopping all CBFS CLI processes; credentials, volume state, TLS pins, journals, and the finality floor move together. Requires an explicit `--state-dir`, so the default \~/.cbfs is never archived by omission. Re-enroll with an independently pinned checkpoint before using the CLI.

```text theme={"system"}
cowboy cbfs reset-state [OPTIONS]
```

## cowboy cbfs rebalance

Move shards off a specified relay while it stays online.

Iterates every locally-known volume in the state dir, and for each placement that includes the source relay, copies the shard to an Active+fresh destination, CAS-bumps the PlacementRecord, and deletes the original shard. Use for planned evictions (decommissioning, scaling down) — for crashed relays the CBFS repair loop already handles it automatically.

Supply exactly one of `--source-node-id` or `--drain-all`.

```text theme={"system"}
cowboy cbfs rebalance [OPTIONS]
```

| Option | Description |
| - | - |
| `--source-node-id <SOURCE_NODE_ID>` | Hex-encoded 32-byte node\_id of the relay to drain shards off. Mutually exclusive with `--drain-all` |
| `--drain-all` | Read `/ras/relays/public`, pick every relay whose status is `Draining`, and rebalance each one in turn. Useful as a periodic worker: operator calls `cowboy-ops drain <slot>`, this command eventually notices and moves the shards |
| `--dry-run` | Log the plan without actually moving anything |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.