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.
cowboy volume is simpler.
cowboy cbfs commands share these options, unless a command’s --help leaves one out:
cowboy cbfs capabilities
Report offline executable capabilities as JSONcowboy cbfs login
Log in to Cowboy via browser wallet (wallet key never touches this machine)cowboy cbfs auth
Configure CBFS auth and delegation (advanced — prefercbfs login)
cowboy cbfs auth ensure-deploy
Prepare or reuse narrow CBFS publication access and report registration readinesscowboy cbfs auth drive-delegation-verify
Verify a signed native Drive delegation offline and print {“valid”:bool}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.
cowboy cbfs auth status
Show local delegation statuscowboy cbfs auth renew
Extend the existing certificate by 30 days while keeping its signing keycowboy 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-paidcowboy cbfs auth rotate
Rotate the delegated cbfs keypaircowboy cbfs auth revoke
Revoke the delegated cbfs key and remove it locallycowboy 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’svolume allow --encryption-key flag
cowboy cbfs whoami
Show authenticated account identity and storage summarycowboy cbfs balance
Show account storage reserve and usagecowboy cbfs volume
Manage volumescowboy 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.
cowboy cbfs volume commitment
Read a volume commitment from chain state without local volume metadatacowboy 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’scowboy cbfs volume list
List known volumescowboy cbfs volume info
Show volume detailscowboy cbfs volume deposit
Top up the rent escrow on an existing volume. The chain refuses deposits toDeleted or GarbageCollecting volumes before debiting the payer.
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 isvisibility == 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.
cowboy cbfs volume transfer
Transfer ownership of a volume to another account (CIP-9 §13.4). Public volumes only for nowcowboy cbfs volume rewrap
Re-wrap a private volume DEK to the current CBSS account release keycowboy 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)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 pointcowboy cbfs put
Upload a file to a volumecowboy 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.
cowboy cbfs courier
Place shards a browser encrypted and sealed (ciphertext only)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.
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 get
Download a file from a volumecowboy cbfs ls
List objects in a volumecowboy cbfs rm
Remove an object from a volumecowboy cbfs cat
Stream an object’s contents to stdoutcowboy cbfs commit
Commit the current manifestcowboy cbfs root
Print the volume’s current manifest root (hex)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.
cowboy cbfs status
Check storage node reachabilitycowboy 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.
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.
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.