crab replica

Manage read replicas and enterprise replication state for Crab remotes. Replica configuration is a storage-operations feature: verify provider replication and object readiness before enabling reads or promoting a replica.

Synopsis

crab replica <SUBCOMMAND> [OPTIONS]

The command currently includes:

add, export, cost, runbook, wait, verify, backfill, enable, disable, mode, writers, coordinator, failover, repair, promote, set-primary, diagnostics, certify, evidence, status, doctor, and remove.

Typical readiness flow

crab replica add us-west \
  --provider s3 \
  --primary crab://primary-bucket/org/repo \
  --replica s3://replica-bucket/org/repo \
  --region us-west-2
crab replica status --json
crab replica verify --deep --json
crab replica wait us-west --enable-read --json

Use crab replica doctor for configuration and readiness diagnostics. Use promote or set-primary only as guarded disaster-recovery operations after reviewing the generated plan and provider state.

Read-enabled replicas participate in both legacy Git fetches and protocol-v2 clone/fetch sessions. Protocol v2 selects the ready replica before capability advertisement and pins its storage location for the upload-pack session. Replica configuration changes also publish a bounded discovery document under the primary repository prefix. A fresh direct-bucket clone reads that document before its initial fetch, so it does not need an ancestor crab.toml.

The primary endpoint remains the discovery trust anchor. Its discovery object must be reachable even when Git packs or Crab payloads are unavailable there; if the entire primary endpoint is unreachable, a client that knows only the primary URL cannot discover an unknown replica without an external registry. When the optional discovery read is unavailable, Crab continues against the primary; a discovery object that is readable but malformed or incompatible still fails closed. An explicit local replication config takes precedence over discovered routing.

Run crab replica <subcommand> --help for the exact provider, active-active, failover, and evidence options available in the installed CLI.