restorable docs
Reference

CLI commands

Every subcommand of restorable and restorable-verify. Synopsis, flags, env vars, and behaviour. For the how-and-why of each command, cross-links point at the relevant narrative page.

restorable

Customer-installed agent. One binary, multiple subcommands. Invocation: 

restorable <subcommand> [flags]

Bare restorable (no subcommand) prints a one-screen status: resolved install root, mode, agent ID, service state, last receipt. Tailscale-style.

Global flags (available on every subcommand):

  • --root DIR (env RESTORABLE_HOME): install directory holding config.yaml + keys/ + blobs/ + receipts/ + events/. Resolution order: --root > RESTORABLE_HOME > walk-up of cwd looking for config.yaml > $XDG_STATE_HOME/restorable (or $HOME/.local/state/restorable) > /var/lib/restorable. doctor prints the resolved root and which branch chose it.
  • --no-color or NO_COLOR=1: disable ANSI colour output.
  • --version: print version and exit.
  • --help: print usage and exit. Works at every level (restorable --help and restorable <sub> --help).

init

Customer's one-command bootstrap. Idempotent on re-run. Mode selected by flag or existing config: --standalone skips the orchestrator entirely; --auth-key=… attaches via the unattended bootstrap; bare init prints an attach URL the operator approves from the dashboard. See Auth key setup.

  • --standalone: write a standalone-mode config.yaml; no orchestrator contact.
  • --auth-key rsk_auth_… (env RESTORABLE_AUTH_KEY): unattended attach. Single-use keys auto-revoke on first delivery.
  • --auth-key-file PATH: read the auth-key from file (mode 0600).
  • --orchestrator URL (env RESTORABLE_ORCHESTRATOR_URL, default https://app.restorable.app).
  • --name NAME: override the hostname-derived agent name surfaced in the dashboard.
  • --force-reattach: rotate the bearer token on an already-attached agent. Refused by default to prevent an accidental paste from abandoning past-receipt lineage.
  • --skip-doctor: skip the post-attach preflight.

status

Print the agent's current state: resolved root + provenance, mode, agent id, service health, last receipt. Bare restorable routes here.

serve

Long-lived heartbeat loop. Reads config.yaml, talks to the orchestrator on a heartbeat cadence, runs run_backup and run_restore_test commands the orchestrator returns. This is what the systemd unit invokes.

backup

One-shot backup of a declared source. Used by standalone mode (cron triggers this) and for manual debugging. Managed mode runs it indirectly via the run_backup command.

  • --source SLUG (env RESTORABLE_SOURCE): which source to back up. Optional when only one source is declared (or defaults.source is set in config.yaml); errors with the available list when multiple sources need disambiguation.

restore-test

One-shot restore test of a source's latest backup. Decrypts, spins up the scratch, runs every check, signs the receipt, writes the DSSE envelope into <root>/receipts/.

  • --source SLUG: same precedence as backup.
  • --check ID (repeatable): override the source's configured check list; default fires every linked check.

download

Fetch a backup's dump for disaster restore. Default mode streams the ciphertext, verifies its SHA-256 against registered metadata, decrypts with the agent's age key, and writes the engine-native dump (<backup_id>.pgdump for Postgres, <backup_id>.mongoarchive for MongoDB) into the directory you supply. Apply the dump with your engine's own restore tool.

Restorable does not write to your databases. There is no --to <target>: pg_restore, mongorestore, and your runbook's flags are yours.

  • --backup BKP_ID: specific backup to fetch. Mutually exclusive with --latest.
  • --latest --source SLUG: fetch the most recent backup for the source.
  • --out DIR: existing directory to write into. The agent picks the filename (<backup_id>.<ext>); refuses to clobber.
  • --ciphertext: skip decryption; write the raw encrypted blob. No keys are loaded in this mode. Suitable for compliance archives or hosts with no agent identity.

digest

Renders a human-readable weekly summary from receipts in <root>/receipts/. Terminal-friendly; useful for local sanity checks and (in standalone mode) for piping to mail.

  • --since DURATION (default 7d): how far back to look.

doctor

Validate host prerequisites and per-source connectivity. Prints the resolved root + provenance + chosen source so a "wrong config" run is debuggable in one shot.

  • --source SLUG or --all-sources: run per-source probes (DSN resolve, connect, role privileges, dry-run each check). Mutually exclusive.
  • --orchestrator URL: override the URL used for the orchestrator-reachability probe; defaults to the value in config.yaml.
  • --skip-pull: don't pull missing toolchain images; only report on their presence.
  • --min-disk-mb N (default 1024): fail the disk probe below this floor.

source add

Interactive wizard (or flag-driven) for adding a source + auditor-framed checks. See Add a Postgres source.

restorable-verify

Standalone receipt verifier. Offline by default; one optional flag fetches transparency-log proofs. 

restorable-verify [flags] FILE [FILE ...]
  • --pubkey PATH (required): path to the agent's public signing key. Accepts an inline base64 value if prefixed with @: --pubkey @ed25519:AAAA....
  • --format FORMAT (default text): text for the human-readable output, json for structured output.
  • --follow-chain: verify prev_receipt_id chains across the batch. Report gaps.

Exit codes:

  • 0: every input verified.
  • 1: a verification failed; first failure message on stderr, full output continues on stdout.
  • 2: CLI usage error (missing flag, file not found).

Environment variables

Agent:

  • RESTORABLE_HOME: install root (env-twin of --root).
  • RESTORABLE_SOURCE: default source slug (env-twin of --source; loses to a passed flag, wins over defaults.source in config.yaml).
  • RESTORABLE_AUTH_KEY: bootstrap auth-key (env-twin of --auth-key on init).
  • RESTORABLE_ORCHESTRATOR_URL: orchestrator base URL (env-twin of --orchestrator).
  • RESTORABLE_DB_URI or other names the operator chooses: consumed by env: secret references in config.yaml.
  • NO_COLOR: disable ANSI output.

Installer:

  • RESTORABLE_VERSION: pin a version for install; default is whatever install.sh ships.
  • RESTORABLE_BASE_URL: override where to fetch binaries from (mirror).
  • RESTORABLE_SKIP_PREREQS=1: skip Docker and minisign install.
  • RESTORABLE_SKIP_VERIFY=1: skip minisign signature verification (tests only, do not use in production).
  • See Manual install for the full list of installer env vars including the sandbox-prefix overrides.