> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Backup Commands > Admin-only backup and restore — create, inspect, verify, restore, rotate, and unlock encrypted workspace / crew bundles. # crewship backup Create, list, inspect and restore workspace / crew backups. This page is the flat flag reference; for the conceptual overview (bundle layout, lock semantics, encryption chain, admin UI, instance-scope details) see the [Backup & Restore guide](/guides/backup). ```bash theme={null} crewship backup [flags] ``` Every subcommand requires the **OWNER** or **ADMIN** role on the target workspace — other roles are refused at both the CLI and the server. ## Subcommands | Command | Description | | ----------- | ------------------------------------------------------------------ | | `create` | Create a new backup bundle. | | `list` | List bundles in `~/.crewship/backups`. | | `download` | Stream a backup bundle from the server to disk. | | `inspect` | Show the manifest of a bundle without decrypting the payload. | | `verify` | Recompute and check the bundle SHA-256 without restoring. | | `restore` | Restore a workspace or crew from a bundle. | | `rotate` | Apply retention — drop bundles over `--keep-last` / `--keep-days`. | | `delete` | Remove a single bundle from disk. | | `status` | Show the active advisory lock for this workspace. | | `unlock` | Force-release a stale advisory lock (emergency only). | | `self-test` | Run the backup canary round-trip on a crew (admin diagnostic). | | `metrics` | Show process-lifetime backup counters (instance owner only). | *** ## `crewship backup create` Produce a new AGE-encrypted `.tar.zst` bundle for a workspace or crew. ```bash theme={null} crewship backup create --scope=workspace crewship backup create --scope=crew --crew dev-team crewship backup create --scope=workspace --recipient age1ql3z7hjy54... crewship backup create --scope=workspace --use-keyring ``` | Flag | Type | Default | Description | | ------------------- | -------- | --------------------- | -------------------------------------------------------------------- | | `--scope` | `string` | `workspace` | Backup scope: `workspace` or `crew`. | | `--crew` | `string` | | Crew slug or ID (required when `--scope=crew`). | | `--no-encrypt` | `bool` | `false` | Write a plaintext payload instead of AGE-encrypting. Test / CI only. | | `--passphrase-file` | `string` | | Read the passphrase from a file instead of prompting. | | `--use-keyring` | `bool` | `false` | Cache and reuse the passphrase via `~/.crewship/backup-keyring.enc`. | | `--recipient` | `string` | | AGE X25519 public key (`age1…`) for asymmetric encryption. | | `--output` | `string` | `~/.crewship/backups` | Override the output directory on the server. | `--recipient`, `--passphrase-file`, and `--no-encrypt` are mutually exclusive. The CLI prompts twice for a passphrase to guard against typos. In a non-interactive session without `--passphrase-file` / `--use-keyring`, a single line is read from stdin. *** ## `crewship backup list` List bundles on disk for the current workspace's default backup directory. ```bash theme={null} crewship backup list ``` **Output columns:** FILE, SCOPE, SIZE, ENCRYPTED, FORMAT, CREATED\_AT. *** ## `crewship backup download` Stream a backup bundle from the server's backup directory to a local file. The argument is the bundle's full path as returned by [`backup list`](#crewship-backup-list). Used when the bundle lives on the server (e.g. nightly create on a remote instance) and you need a local copy before [`restore`](#crewship-backup-restore). ```bash theme={null} crewship backup download /var/crewship/backups/crewship-workspace-acme-2026-05-27.tar.zst crewship backup download /var/crewship/backups/bundle.tar.zst --out ~/restores/bundle.tar.zst ``` | Flag | Type | Default | Description | | --------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--out` | `string` | basename of source | Output file path. | | `--force` | `bool` | `false` | Overwrite the output file if it already exists. Without this flag the command refuses to clobber, since a bundle is the only authoritative copy of a workspace at that point in time. | The endpoint sends `no-store`/`no-cache` headers and a half-written file is removed on copy failure — partial bundles never land on disk. *** ## `crewship backup inspect` Print the plaintext MANIFEST of a bundle — `format_version`, `scope`, timestamps, source instance, SHA-256 of the sealed payload. Never touches the encrypted payload, so no passphrase is needed. ```bash theme={null} crewship backup inspect ~/.crewship/backups/crewship-workspace-acme-...tar.zst ``` *** ## `crewship backup verify` Recompute the SHA-256 of the sealed payload and check it against the manifest. Confirms the bundle was not truncated or tampered with. Does not decrypt or restore anything. ```bash theme={null} crewship backup verify ~/.crewship/backups/crewship-workspace-acme-...tar.zst ``` *** ## `crewship backup restore` Restore a workspace or crew from a bundle. The server refuses a restore if a workspace (or crew) with the same slug already exists; pass `--as-workspace` / `--as-crew` to land the payload under a fresh identity. ```bash theme={null} crewship backup restore ~/.crewship/backups/bundle.tar.zst crewship backup restore bundle.tar.zst --as-workspace acme-dr crewship backup restore bundle.tar.zst --dry-run crewship backup restore bundle.tar.zst --use-keyring ``` | Flag | Type | Default | Description | | ------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--as-workspace` | `string` | | Restore the workspace under a new slug. Docker phase is skipped. | | `--as-crew` | `string` | | Restore the crew under a new slug (`--scope=crew` only). | | `--passphrase-file` | `string` | | Read the passphrase from a file instead of prompting. | | `--use-keyring` | `bool` | `false` | Read the passphrase from `~/.crewship/backup-keyring.enc` before prompting. | | `--replace` | `bool` | `false` | Disaster-recovery path: wipe existing target rows matching the bundle's workspace (by id **or** slug) **before** restore, so the bundle lands with its original IDs after a `nuke` or fresh-instance bootstrap re-took the slug under a new id. Mutually exclusive with `--as-workspace` / `--as-crew`. | | `--dry-run` | `bool` | `false` | Verify format / checksum / decrypt, replay the restore tx, then roll back. Writes a `backup.restore.dry_run` audit row. | The server refuses a restore if a workspace (or crew) with the same slug already exists. Use `--as-workspace` / `--as-crew` to land the payload under a fresh identity, or `--dry-run` to validate before cutover. A dry-run leaves only the audit row — no DB rows, no docker changes. Use it to prove a bundle is restorable before cutover. *** ## `crewship backup rotate` Retention sweep. Either flag on its own is valid; both together apply the stricter cutoff. ```bash theme={null} crewship backup rotate --keep-last 10 crewship backup rotate --keep-days 30 crewship backup rotate --keep-last 10 --keep-days 30 --dry-run ``` | Flag | Type | Default | Description | | ------------- | ------ | ------- | --------------------------------------------------------- | | `--keep-last` | `int` | `0` | Keep only the N newest bundles (0 disables). | | `--keep-days` | `int` | `0` | Drop bundles older than N days (0 disables). | | `--dry-run` | `bool` | `false` | List bundles that would be deleted without touching disk. | Rotation applies per workspace — it never touches another workspace's bundles. *** ## `crewship backup delete` Remove a single bundle from disk. A bundle may be the only authoritative copy of a workspace at that point in time. Interactive confirmation is required unless `--force` is passed. ```bash theme={null} crewship backup delete ~/.crewship/backups/old.tar.zst crewship backup delete old.tar.zst --force ``` | Flag | Type | Default | Description | | --------- | ------ | ------- | ---------------------------------------------------------------------- | | `--force` | `bool` | `false` | Delete without interactive confirmation. Required in non-TTY sessions. | | `--yes` | `bool` | `false` | Alias for `--force` — the CLI-wide pre-confirmation convention. | *** ## `crewship backup status` Show the advisory lock state for the current workspace — who holds it, when it was acquired, and when the 1-hour TTL expires. ```bash theme={null} crewship backup status ``` **Output columns:** WORKSPACE, ACQUIRED\_BY, ACQUIRED\_AT, EXPIRES\_AT. *** ## `crewship backup unlock` Force-release a stale backup lock. Emergency only — use when the previous CLI session crashed and the 1-hour TTL has not yet fired. ```bash theme={null} crewship backup unlock --force ``` | Flag | Type | Default | Description | | --------- | ------ | ------- | --------------------------------------------------------------- | | `--force` | `bool` | `false` | Skip interactive confirmation. Required in non-TTY sessions. | | `--yes` | `bool` | `false` | Alias for `--force` — the CLI-wide pre-confirmation convention. | Forcibly releasing a live backup's lock lets a second backup start alongside it; the two will race on the Docker pause / unpause sequence. Confirm no backup is actually running before invoking this. *** ## `crewship backup self-test` Run the server-side canary round-trip (collect → destroy → restore → verify → cleanup) on a crew's container without producing a bundle on disk. Quick way to validate the backup pipeline end-to-end after upgrading the agent runtime image or after restoring an instance. ```bash theme={null} crewship backup self-test --crew dev-team ``` | Flag | Type | Default | Description | | -------- | -------- | ------- | -------------------------------------------------------- | | `--crew` | `string` | — | Crew slug or ID to run the canary against. **Required.** | Output is the server's raw JSON: an `"ok"` boolean and per-stage timings. Non-zero exit if any stage of the round-trip fails. *** ## `crewship backup metrics` Dump the in-memory backup counters — created / failed totals, duration quantiles, lock-held gauge. These are **process-lifetime** values that reset on a restart of `crewshipd`, so they're useful for a quick health read after a long-running run, not for historical reporting (use the journal for that). ```bash theme={null} crewship backup metrics ``` Output is pretty-printed JSON. Gated to instance OWNER server-side. ## See also * [Backup & Restore guide](/guides/backup) — concepts, lock semantics, keyring, webhooks, metrics, instance scope. * [Backup API reference](/api-reference/backup) — REST endpoint shapes. * [Security → Instance-Scope Backup Security](/security/backup-instance-security) — threat model for instance backups.