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:
crew start, not crew provision: --files-only writes each section by exec’ing into the
crew’s container, so the container has to be running. Provision only
builds the image, which left this recipe one command short. crew start
builds the image too when there is none, so it covers both.
--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.