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.
crewship backup <subcommand> [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.
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.
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. 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 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. |
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.
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.
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.
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.
crewship backup rotate
Retention sweep. Either flag on its own is valid; both together apply
the stricter cutoff.
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. |
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.
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.
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.
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.
crewship backup self-test --crew dev-team
| Flag | Type | Default | Description |
|---|
--crew | string | — | Crew slug or ID to run the canary against. Required. |
"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).
Output is pretty-printed JSON.
Gated to instance OWNER server-side.
See also
