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.Every subcommand requires the OWNER or ADMIN role on the target
workspace — other roles are refused at both the CLI and the server.
Subcommands
crewship backup create
Produce a new AGE-encrypted .tar.zst bundle for a workspace or crew.
--recipient is mutually exclusive with both --passphrase-file and
--no-encrypt (each combination is rejected). --no-encrypt also wins
over a passphrase — it skips the prompt entirely and writes plaintext.
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.
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.
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.
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 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.
Finishing a renamed restore
--as-workspace / --as-crew fork the bundle’s rows under a new
identity and cannot land container state in the same call — the crews
they create have no containers yet. Three steps:
--files-only is authorised by provenance, not by the flag: step 1
records which bundle the new workspace came from (matched on the
bundle’s payload digest), and step 3 is permitted only for a workspace
that record covers. A bundle never restored into your current workspace
is refused with the same 403 as before.
It also writes to the crews step 1 created, not the crews the bundle
names — the manifest still carries the source crew’s slug, so on a
same-instance restore the distinction is what keeps a sibling’s backup
from being written over the source crew’s live data.
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.
Rotation applies per workspace — it never touches another workspace’s
bundles.
crewship backup delete
Remove a single bundle from disk.
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.
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 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.
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).
Gated to instance OWNER server-side.
See also
- Backup & Restore guide — concepts, lock semantics, keyring, webhooks, metrics, instance scope.
- Backup API reference — REST endpoint shapes.
- Security → Instance-Scope Backup Security — threat model for instance backups.