Command reference
Every safegrd command and its flags. Run safegrd <command> --help
on the host for the same list. If this page and the binary disagree, trust the binary.
A first run, start to finish
Four commands take a host from nothing to a restored database. The windows below show real
output from one run on a host called prod-app-01. It backs up a PostgreSQL
database named shop to SafeGrd-hosted storage. Each window plays when you
scroll to it. Click one to see the whole run at once.
1. Enroll the host
Get the claim code from Add surface in the console. It tells the host which
surfaces to back up. Get the token from Tokens. If you leave out
--token, you approve a login in any browser instead.
$ safegrd enroll --token env:SG_TOKEN --claim sgc_7rj6zi5k3ruu5asw
Generated an age X25519 keypair
Public key: age1lq70sjlq9u8ymuxvmxqwf20trfjn5qx44578xy3gvu2fqyzsaa9scp2uzm
Private key: /home/safegrd/.safegrd/keys/daemon.key (mode 0600)
No local setup found, so it was created first.
Enrolling with https://safegrd.dev
Registering a new node with the personal access token.
Claim for project 'Production'.
Enrolled node node-c97be882 as 'prod-app-01'
Node token: sg_tok_…51fb (saved to the config file)
Key: SG:e53b6c6a:cc58f416
Custody: SafeGrd-managed key
SafeGrd keeps this key sealed and releases it only to your enrolled hosts,
so you can restore these backups even after losing this host.
For a customer-managed key next time, enroll with --key-custody=local.
Project ID: proj-e1e56658
Surfaces named for this host in the console:
shop postgres: set SHOP_DB on this host (the credential never leaves it)
Saved to /home/safegrd/.safegrd/config.yaml
Next: check every surface opens from this host. The console shows the result:
safegrd doctor
Take the first backups now, and watch them land in the console:
safegrd daemon run --once
Then keep the daemon running as a service that starts at boot. Nothing backs up
on a schedule until it runs:
sudo safegrd daemon install
2. Take the first backup
One pass of the daemon backs up every surface that is due. A new surface is due straight
away. After that, safegrd daemon install keeps the daemon running.
$ safegrd daemon run --once SafeGrd daemon dev started Surfaces: 1 State directory: /home/safegrd/.safegrd Surface shop (postgres) is due for backup. [shop] Epoch e202610-06bca287 opened (first backup). Every table is uploaded once this month. [shop] 3 tables, 70,240 rows, 3.1 MiB read, 386.9 KiB stored in 2 packs, 532ms. [shop] Snapshot snap-20261018-024047-450e5d complete. Locked until 2026-11-02: the month's first backup is kept as its monthly copy. Later backups follow the surface's retention. [shop] That date is capped: a backup is locked no longer than the objects it is built from, and no longer than a trial runs. Backed up surface shop
3. Check that it restores
A Fire Drill loads the snapshot into an empty database and checks every table against what the backup recorded. The daemon runs drills on your plan's schedule. Here the same drill runs by hand.
$ safegrd verify --snapshot snap-20261018-024047-450e5d --sandbox-target "$SANDBOX_DB" Verifying snap-20261018-024047-450e5d (epoch e202610-06bca287, shop): checking the packs, restoring it into postgres://postgres:xxxxx@db.internal:5432/drill_sandbox?sslmode=verify-full&sslrootcert=/etc/ssl/rec-ca.crt. [PASS] DecryptionIntegrity (Expected: the run, its indexes and trees open with the identity, Actual: they do) [PASS] RepositoryIntegrity (Expected: every pack present and agreeing with its index, Actual: 2 packs checked) [PASS] DigestIntegrity (Expected: 82cb21e4088ce87ec18c364554153f6ef05348bd5dcf5d6cb89ad3d2ecfb71d1, Actual: 82cb21e4088ce87ec18c364554153f6ef05348bd5dcf5d6cb89ad3d2ecfb71d1) [PASS] TableCountMatch (Expected: 3 tables, Actual: 3 tables) [PASS] RowCountMatch (Expected: 70240 rows, Actual: 70240 rows) [PASS] Row Count: public.customers (Expected: 2000 rows, Actual: 2000 rows) [PASS] Row Count: public.order_items (Expected: 48000 rows, Actual: 48000 rows) [PASS] Row Count: public.orders (Expected: 20240 rows, Actual: 20240 rows) [PASS] Newest Row: public.customers (Expected: created_at 2026-10-18T02:31:41.771586Z, Actual: created_at 2026-10-18T02:31:41.771586Z) [PASS] ExtensionBootCheck (Expected: [], Actual: []) [PASS] Schema Captured By pg_dump (Expected: schema from pg_dump, Actual: pg_dump 18.6) Fire Drill Passed Verification ID: verif-9fc2992a Duration: 253ms Tables: 3 Rows: 70,240 Certificate: cert_sg_49ec5f75ecbe913b4c9e9d3c5b1bf13c503af8e6f2e57eda780c1258918e0ba7
4. Restore it into an empty database
The snapshot comes down still encrypted, and this host decrypts it.
$ safegrd restore --snapshot snap-20261018-024047-450e5d --target env:SCRATCH_DB Restoring snap-20261018-024047-450e5d (epoch e202610-06bca287, shop) into postgres://postgres:xxxxx@db.internal:5432/shop_restored?sslmode=verify-full&sslrootcert=/etc/ssl/rec-ca.crt Content root: matches the remote server's record from backup time Restored 3 tables, 70,240 rows, from snap-20261018-024047-450e5d in 147ms. Every table matched its SHA-256 and its row count.
https://safegrd.dev.Global flags
| Flag | Meaning |
|---|---|
| --config | Config file. Default ~/.safegrd/config.yaml. |
| --server-url | SafeGrd's server. Default $SAFEGRD_SERVER_URL if set, else https://safegrd.dev. |
| -v, --version | Print the version and exit. |
Exit codes
A command that fails exits non-zero. When the CLI can tell which side failed, the exit code says so. A script can then retry when a service is down, and stop when the mistake is its own.
| Code | Meaning |
|---|---|
| 0 | The command did what it was asked. |
| 1 | Failed, for a reason not listed below. The Error: line says why. |
| 3 | guard only: no locked snapshot was taken, so guard did not run the command. |
| 10 | The source failed: the database, mailbox or directory refused the connection or the credential, or does not exist. |
| 11 | SafeGrd's server failed: the CLI could not reach it, it answered with a server error, or it sent a reply this CLI cannot read (upgrade the CLI). |
| 12 | Storage failed: the CLI could not open, write or read the bucket or directory the backups go to. |
| 130 | Interrupted with Ctrl-C or SIGTERM. |
| 140 | wal fetch could not read a WAL file that the archive may hold, for example because the storage did not answer or there was no key. PostgreSQL then stops recovery instead of ending the replay at that file. Fix the cause and start recovery again. A file the archive does not hold exits 1. |
Setup
try
Backs up one database or directory before you have an account. It then restores the backup in memory from SafeGrd's storage to check it, and prints the tables and rows it read back. It takes a PostgreSQL, MySQL, MongoDB or SQLite URL, or a directory.
The URL stays on this host. Pass it as env:VAR or file:/path to keep the
password out of the config. SafeGrd keeps the backup for 24 hours, unlocked.
safegrd try status tells you whether it is still kept, signed up or gone. The
install guide covers the limits and what happens next.
| Flag | Meaning |
|---|---|
| --key-custody | safegrd (default) is a SafeGrd-managed key. SafeGrd keeps your key sealed and releases it only to this host, so you can restore even after losing the host. local is a customer-managed key. Only you can decrypt this backup. |
| --name | This host's name in the console. Default: the hostname. |
| --no-browser | Print the sign-up link without opening a browser. |
signup
Opens the sign-up page for the backup that try took, with a code to match against the
one in the terminal. Sign up there, or sign in to an account that has no organization yet. The host,
its backup and its daily schedule then become your organization, and you run nothing more on the
host.
If your account already has an organization, run safegrd login and then
safegrd enroll on the host instead. The host joins that organization as a new host,
with the same surfaces and key.
init
Writes the local config, and generates an Age keypair if this host has none. It does not contact SafeGrd's server. With --storage s3, it asks the bucket whether Object Lock is on.
| Flag | Meaning |
|---|---|
| --node-name | This host's name in the console. Default: the hostname. |
| --database-url | The database to back up, written to the config as its first surface: PostgreSQL, MySQL, MongoDB or SQLite. Pass env:VAR or file:/path to keep the URL out of the file. safegrd backup then backs it up. |
| --laravel | Add a Laravel app as a surface, given the app's root (where artisan and .env are). See Laravel. If the host already has a config, only the surface is added, and the key, the host's registration and the storage stay as they are. With --laravel, --database-url replaces the connection named in .env. |
| --surface-id | With --laravel: the surface's id. Default: APP_NAME as a slug, or the directory's name if APP_NAME is not set. |
| --migrations-table | With --laravel: the app's migrations table, if it is not named migrations. |
| --storage | local, s3 or hosted. Default local. |
| --local-path | The directory backups go to with --storage local. |
| --s3-bucket | Bucket for WORM storage. |
| --s3-prefix | Key prefix in the bucket. Default safegrd/snapshots. |
| --s3-region | Bucket region. Default us-east-1. |
| --s3-endpoint | Custom endpoint, for MinIO, R2 or Wasabi. |
| --retention-days | WORM retention in days. Default 14. |
| --worm-mode | Object Lock mode for --storage s3: COMPLIANCE (default), GOVERNANCE, or NONE for a bucket with no Object Lock, such as DigitalOcean Spaces. |
| --force | Overwrite an existing config. This discards its settings and generates a new keypair. Snapshots taken before that can only be read with the old key, so back up the old key first. |
enroll
Registers this host with SafeGrd's server, and runs local setup first if the host has none. A personal access token enrolls new hosts only. A host that is already enrolled keeps its node token.
If you lost the token or rebuilt the host, click Rotate token on the host under Hosts in
the console. Then run safegrd enroll --token <node token> --node-id <id> on
the host. The host goes on backing up to its own key. With a SafeGrd-managed key, enroll fetches the
key and writes it to key_path. With a customer-managed key, put the key file at
~/.safegrd/keys/daemon.key first.
| Flag | Meaning |
|---|---|
| --token | A personal access token to register a new host, or a node token together with --node-id. Takes env:VAR or file:/path. |
| --node-id | The id of the host the node token belongs to. The console shows it beside the token. Leave it out with a personal access token. |
| --node-name | This host's name in the console. Default: the hostname. |
| --org | The organization to enroll into. Needed only when the credential can see more than one. |
| --project | Project id or slug. Defaults to the organization's default project. |
| --key-custody | safegrd (default) stores a SafeGrd-managed key, sealed, on SafeGrd's server. local creates a customer-managed key on this host and sends only the public half. Ignored if you supply your own key. |
| --storage | Where this host's backups go if its project has no bucket. hosted uses SafeGrd-hosted storage, if your plan includes it. local keeps them in a directory on this host. |
| --allow-unconfigured | Enroll a host that has nowhere to back up to yet, with no storage in its config or its project. Without this flag, enroll stops and tells you what to set, so the host does not enroll and then fail its first backup. |
keygen
Generates an age key pair for a customer-managed key. You need no other tools. keygen writes the
private key at mode 0600 and does not print it. It prints the public key. Put that in
encryption.public_key on the hosts that back up, and leave key_path empty.
Those hosts can then encrypt but cannot decrypt. Keep a copy of the private key somewhere safe, such
as a password manager. keygen does not overwrite an existing file.
On an enrolled host, --held writes a copy of a SafeGrd-managed key to
--out instead. By default that is this host's key. With --snapshot it is the
key that snapshot was sealed to, for example a snapshot of a database SafeGrd backs up for you, or of
a host you lost. SafeGrd keeps the key as before, and the key access record in
Settings lists the copy.
| Flag | Meaning |
|---|---|
| --out | Where to write the private key. Default: ~/.safegrd/keys/daemon.key. Required with --held. |
| --recipient | Print the public key for the private key in this file. Generates nothing. |
| --held | Write a copy of the SafeGrd-managed key. Generates nothing. |
| --snapshot | With --held: write the key this snapshot was sealed to, instead of this host's. |
$ safegrd keygen --out /tmp/offline.key Private key: /tmp/offline.key (mode 0600). Keep a copy somewhere safe. Public key: age1k0j89dn7xm007xyd2ct7z4jxfyw7scph5tt5my6f83rmcza6tp9s3ppdmu Fingerprint: SG:b26ce676:74b55239
keygen writes the private key and prints the public key for the hosts that back up.$ safegrd keygen --held --out /tmp/prod-app-01.key Private key: /tmp/prod-app-01.key (mode 0600), a copy of the SafeGrd-managed key. Public key: age1lq70sjlq9u8ymuxvmxqwf20trfjn5qx44578xy3gvu2fqyzsaa9scp2uzm Fingerprint: SG:e53b6c6a:cc58f416 SafeGrd still holds this key and releases it only to your enrolled hosts. Keep this copy somewhere safe: it opens every backup sealed to this key.
claim
Adds the surfaces you named for this host in the console (Add surface on the
host's row under Surfaces) to an enrolled host's config. Nothing changes on the host until you run it,
and it only adds. It leaves any surface the config already has as it is, and keeps the previous config
as config.yaml.bak. Running it again adds nothing. A running daemon reads the new config at
the start of its next pass. On a new host, run safegrd enroll --claim <code> instead.
login
Signs this machine in to your SafeGrd account. It prints a link and a code, which you approve in a browser on any device, so it works the same over SSH.
On an enrolled host, login refuses to run while SafeGrd still accepts the host's node token,
because it would replace that token. On a host where nobody signed up for the try backup,
login replaces the trial's token. enroll then registers the host as a new host in your
organization.
| Flag | Meaning |
|---|---|
| --token | Personal access token (sg_pat_...) for CI and headless use. |
| --no-browser | Print the URL instead of opening a browser. |
whoami
Prints who you are signed in as and the active server session.
Protect
backup
Streams a surface, compresses it with zstandard, encrypts it to your Age public key and writes the ciphertext to WORM storage. Unencrypted data never touches disk. The one exception is a SQLite surface's private temporary copy on the same host (why).
| Flag | Meaning |
|---|---|
| --database-url | Database connection string. The scheme picks the surface: postgres://… for PostgreSQL, mysql://… (or mariadb://…) for MySQL, mongodb://… for MongoDB, sqlite:///path/to/file.db for SQLite. |
| --surface | The id of one surface under surfaces: in the config. Backs it up now, whatever its schedule, the way the daemon would, with the surface's own storage, retention and credential. Run it before a migration. Do not combine it with the flags that describe a surface. |
| --files | Directory tree to back up, or a bucket as s3://bucket/prefix. Selects the files surface. |
| --source-endpoint, --source-region, --source-access-key, --source-secret-key, --source-session-token | With --files s3://…: where the bucket is, and the keys that read it, as env:VAR or file:/path. Add the session token when the key is temporary. --files s3://* reads every bucket the key lists, each as a directory in the archive. See a bucket as a surface. |
| Back up an IMAP mailbox. Selects the email surface. | |
| --exclude | Glob patterns to leave out of a file backup, for example '*.tmp,node_modules/*'. |
| --note | A note on the snapshot, key=value, repeatable. See note. |
| --compression | How hard to compress: zstd:1 (fastest) to zstd:19 (smallest). A restore needs no matching setting. In the config, set compression on the surface. |
| --format | How --files or a database is stored. repo (the default) is incremental: each run uploads only what changed. tar writes one archive per backup. See incremental file backups and databases. |
| --change-log | For a PostgreSQL backup in repo format: skip reading tables that nothing has written to since the last run. A trigger it puts on each table records the writes. See the change log. |
| --roles-without-passwords | PostgreSQL: leave role password hashes out of the backup. By default, the roles the schema names are backed up with their password hashes, encrypted like everything else. See roles, owners and grants. |
| --new-epoch | Start a new monthly epoch now, which uploads everything once. Works with --format repo or --surface. |
| --rescan | Read every file, not only those whose size or times changed. Works with --format repo or --surface. |
| --one-filesystem | Stay on the root's filesystem. On by default when the root is /. |
| --email-host | IMAP hostname. |
| --email-port | IMAP TLS port. Default 993. |
| --email-user | Mailbox username or address. |
| --email-password | Mailbox password. Use SAFEGRD_EMAIL_PASSWORD instead where you can, because a flag shows in the process table. |
| --email-folders | Folders to back up. Default: all except spam and trash. |
| --email-ca-file | A PEM bundle of extra CAs to trust for the IMAP server. They are added to the system roots and do not replace them. Also SAFEGRD_EMAIL_CA_FILE. |
| --retention-days | How many days this backup is locked. If you pass no --keep-* flag with it, the config's defaults.keep_* tiers do not apply to this run. |
| --keep-daily, --keep-weekly, --keep-monthly | Lock the first one-off backup of each UTC day, ISO week or month for this many days, weeks or months (GFS). Default: the config's defaults.keep_*. |
| --s3-bucket | Write to this bucket instead of the project's or the config's. |
| --s3-prefix | Key prefix in the bucket. |
| --s3-endpoint | S3 endpoint, for MinIO, R2 or another S3-compatible store. |
| --s3-region | S3 region. |
| --s3-access-key | S3 access key id. |
| --s3-secret-key | S3 secret access key, as env:VAR or file:/path. |
| --tag | A prefix for the snapshot tag. |
| --json | Print the result as JSON. |
$ safegrd backup --surface shop Surface shop (postgres): backing up now. [shop] Incremental, in epoch e202610-06bca287: only what changed since the last run is uploaded. [shop] 3 tables, 70,552 rows, 3.2 MiB read, 19.1 KiB stored in 2 packs, 453ms. [shop] Snapshot snap-20261018-024147-da47c0 complete. Locked until 2026-11-02. Backed up surface shop Snapshot ID: snap-20261018-024147-da47c0
guard
Backs up one surface, waits until the snapshot is uploaded and locked, then runs the command. If the backup fails or the snapshot is not locked, the command does not run and guard exits 3. See Agent guard.
| Flag | Meaning |
|---|---|
| --surface | The surface to back up, by its id in the config. |
| --allow-unlocked | Run the command even when the backup is not locked, as on local storage or with worm_mode: NONE. |
| --list | Print the rules that mark a command as destructive. |
| --matches | Check a command against the rules and take no backup: exit 0 if it matches, 1 if not. |
| --hook | Answer a pre-command hook on stdin: claude-code, cursor or codex. |
wal
Point-in-time recovery for a PostgreSQL, SQLite, MySQL or MongoDB surface with a wal: block. wal restore --to <time> restores to any second in the recovery window. Run wal point before a risky change to mark a restore point.
For PostgreSQL, set archive_command to wal push. It compresses and encrypts each WAL file on the host and writes it to the surface's storage. The daemon runs wal base weekly and wal bundle daily. The bundle locks the day's WAL in one object. For MySQL and MongoDB, the daemon follows the binary log or oplog, and wal restore --target-url loads a base backup into an empty database and replays the log up to the moment you ask for.
Setup and the recovery window are on the PostgreSQL, SQLite, MySQL and MongoDB pages.
Recover and prove
restore
Downloads a snapshot still encrypted, decrypts it on this machine and restores it into a database
or a directory. With --from, it reads a copy that safegrd export --to-dir made
instead of the storage in the config (Runbook 4).
| Flag | Meaning |
|---|---|
| --snapshot | The snapshot id to restore. Leave it out to restore the newest kept version of one --path or one --table, or when --from names a .safegrd file. |
| --from | The export to restore from: the directory export --to-dir wrote (add --snapshot), or one .safegrd file in it. |
| --from-bucket | Read the snapshot from one of the surface's other buckets, by its name in copies: or in the console (A second bucket). |
| --request | Run a restore someone requested in the console, by its id (rst_...). The request sets the snapshot, the target and what to restore, and the CLI reports the outcome back. The only other flags it takes are --key-path and --private-key (Restore from the console). |
| --target | The database URL to restore into, postgres://… or mysql://… to match the snapshot. The database must be empty. For a files snapshot, s3://bucket/prefix uploads each file into that bucket with the content type it had at backup time (restore into a bucket). |
| --source-endpoint, --source-region, --source-access-key, --source-secret-key, --source-session-token | With --target s3://…: where the bucket is, and the keys that write to it, as env:VAR or file:/path. For a snapshot of every bucket, --target s3://* puts each file back in the bucket it came from. |
| --target-dir | The directory to restore file and email snapshots into. For a WordPress site or a Laravel app, use it together with --target: the database goes to --target and the files go here. |
| --path | For an incremental files snapshot: restore only this path, relative to /. Repeatable. *, ? and ** work as wildcards. |
| --table | Restore this table alone into --target, which may hold other tables. Repeatable. For PostgreSQL, from any backup, give schema.table, with either part quoted the way psql prints it. For MySQL, MariaDB and SQLite, from an incremental backup, give the table's name. For MongoDB, from an incremental backup, give one collection's name. The table loads into an empty table of the same definition. If the target does not have the table, the restore creates it as the backup defined it, with its indexes (and for PostgreSQL its schema, sequences and constraints). The target's other tables are left as they are. A full (tar) backup of MySQL, SQLite or MongoDB restores whole. |
| --as | With one --table of a PostgreSQL backup: restore it beside the live table under this name (schema.table_restored). The live table stays as it is. The copy has the live table's columns and NOT NULL rules, and no indexes, keys, checks or defaults. Compare the two with SQL and copy back what you need. The live table must still have the definition the backup recorded. |
| --rows | With one --table: restore only the rows that match a SQL condition, such as "id IN (4211, 4212)" or "deleted_at > '2026-10-30'", into the table as the target has it. The restore loads the backup's rows into a temporary table inside the target's own transaction, then writes the matching rows into the table by primary key. The target's other rows and tables stay as they are. A row the target already has is left alone and counted. The table must exist in the target with the definition the backup recorded, and it must have a primary key. The command prints how many rows it inserted, replaced and left. It does not move a sequence the table owns. If you put back a row with an id past the sequence, the next insert collides with it until you move the sequence with setval. |
| --overwrite | With --rows: replace a row the target already has with the backup's. Without this flag, a restore does not write over existing data. |
| --version | With one --path or --table: restore this version, numbered as safegrd find lists them, instead of naming a --snapshot. |
| --surface | With --version: the surface whose repository holds the file, when more than one does. |
| --schema | PostgreSQL only: restore this schema's objects and rows into a database that already has other schemas, such as a Supabase project. Repeatable. The target must not already have the schema's objects. |
| --data-only-schema | PostgreSQL only: load this schema's rows into the tables the target already has, and create nothing. If the target lacks a table, or the restoring role cannot insert into it, the restore leaves it out and names it with its row count. If none of a schema's tables can be loaded, the restore refuses that schema. Repeatable, and you can combine it with --schema. |
| --salvage | For an incremental files snapshot with a damaged or missing pack: restore every file that still matches its SHA-256, leave the rest out of the target, and list each one with the reason. Exits non-zero if any file is left out. Without this flag, such a restore writes nothing and tells you to run it again with --salvage. |
| --without-erasures | PostgreSQL only: restore even when the surface's erasure record cannot be read. Rows erased after the backup may come back, and the restore says so. See the erasure record. |
| --keep-cron-active | PostgreSQL only: create the snapshot's pg_cron jobs as they were at backup time. By default, each job is created turned off. See pg_cron jobs. |
| --parallel | For incremental PostgreSQL backups: how many connections load tables at once. Default 4, capped by the server's free connections. With more than one, the restore is not one transaction, so if it fails, drop the target and restore again. 1 loads everything in one transaction. |
| --no-owner | PostgreSQL only: restore without owners, grants and default privileges, so every object belongs to the restoring role. The roles the schema names are still created, because a policy cannot be restored without them. See roles, owners and grants. |
| --to-sql | Write a PostgreSQL snapshot into this new directory as files psql can load: the schema as SQL, each table's rows as binary COPY, and load.sql. Run psql "$URL" -f load.sql from that directory. The files are not encrypted. The directory is created with mode 0700. |
| --key-path | Path to the Age private identity file. |
| --private-key | The Age private identity inline (AGE-SECRET-KEY-1...). |
verify
Runs a Fire Drill: downloads the snapshot, decrypts it and checks what came back. By default it restores in memory, so you need no database.
| Flag | Meaning |
|---|---|
| --snapshot | Snapshot id to verify. Required. |
| --surface | For a surface with watch:, drill the backup it last read, in the place the other tool put it, instead of a snapshot. The drill runs in memory or loads into --sandbox-target. safegrd backup --surface runs that surface's check. See watched backups. |
| --in-memory | Restore in memory, with no target database, even when --sandbox-target is set. This is the default when --sandbox-target is not set. |
| --sandbox-target | An empty database to restore into for a full drill. verify does not empty it afterwards. If the drill fails, verify prints where the sandbox is. |
| --keep-sandbox | When a sandbox drill fails, record that the sandbox is kept for someone to inspect. |
| --query | Read rows out of a database backup without restoring the table they came from. The CLI restores the snapshot into --sandbox-target, or into a PostgreSQL cluster the host starts for the run, and prints the query's rows as CSV. The run is not reported as a drill, and stdout carries only the CSV. Example: safegrd verify --snapshot <id> --query "SELECT * FROM orders WHERE id = 4211". To put rows back, use restore --rows. |
| --out | With --query: write the CSV to this file instead of stdout. |
| --keep | With --query: keep the PostgreSQL cluster the run started running for a day, and print how to connect to it with psql. |
| --show-url | When a sandbox drill fails, print the sandbox URL with its password. |
| --key-path | Path to the Age private identity file. |
| --private-key | The Age private identity inline. |
| --s3-bucket | Read the snapshot from this bucket instead of the configured storage. |
| --s3-prefix | Key prefix in the bucket. |
| --s3-endpoint | S3 endpoint, for MinIO, R2 or another S3-compatible store. |
| --s3-region | S3 region. |
| --from-bucket | Read the snapshot from one of the surface's other buckets, by its name (A second bucket). |
| --s3-access-key | S3 access key id. |
| --s3-secret-key | S3 secret access key, as env:VAR or file:/path. |
note
Sets notes on a snapshot, such as release=v2.3 or ticket=OPS-12.
key= with no value removes that note. To set notes while the backup runs, use
backup --note key=value. SafeGrd stores the notes outside the locked backup, so you
can change them later. safegrd list shows them. Keys use lowercase letters, digits,
_, . and -. A snapshot holds up to 20 notes.
find
Lists every kept version of the matching files in incremental backups. For each version it shows when it was first and last seen, its size and SHA-256, and how many snapshots hold it. Patterns are paths relative to /. A directory matches everything below it. Run it on a host that has the private key.
| Flag | Meaning |
|---|---|
| --surface | Search this surface only. Without it, the host searches the surfaces it has the key for and says how many others it skipped. If you name another host's surface and it has a SafeGrd-managed key, find fetches that key. |
| --table | List the kept versions of a table instead. Give schema.table for PostgreSQL, and the name alone for a MySQL, MariaDB or SQLite table or a MongoDB collection. Repeatable. restore --table <name> --version <n> restores one of them. |
| --deleted | List only files the newest snapshot no longer holds. |
| --from-bucket | Search one of the surface's other buckets, by its name, instead of this host's storage (A second bucket). |
| --json | Print the histories as JSON. |
| --key-path | Path to the Age private identity file. |
| --private-key | The Age private identity inline. |
check
Checks incremental backups without restoring them. It confirms that every pack a snapshot names is in storage and agrees with its index, and that every directory listing decodes. It recomputes the content digest from them, compares it with the recorded one, and checks that the catalog agrees. If anything is wrong, check names it and exits non-zero.
| Flag | Meaning |
|---|---|
| --read-data | Also open every chunk and check its SHA-256. This downloads the snapshot's data. |
| --key-path | Path to the Age private identity file. |
| --private-key | The Age private identity inline. |
verify history
Checks a host's attestation chain, and each record's Ed25519 signature against the key the record names.
| Flag | Meaning |
|---|---|
| --node | The node id of the host whose history to check. |
| --file | Local JSON file of verifications, for an offline audit. |
| --save | Also write the records fetched from SafeGrd to this file, for a later --file check. |
| --key | One hex-encoded Ed25519 public key, checked against every record. file:/path reads it from a file. |
| --keys-file | The JSON from /api/v1/attestations/public-key, saved while online. It holds the active key and the retired ones, for a chain that spans a key rotation. |
| --json | Print the result as JSON, with the keys that signed the chain. |
Storage
list
Lists every snapshot in the bucket, with the host it was filed under, what it holds and
its retention state. restore and verify find a snapshot whichever
host it is filed under, so when you rebuild a lost host you do not need the old node id
(Recovery runbooks).
Incremental file backups are listed in a second table. For each snapshot it shows the month (epoch) it belongs to, whether its run opened the month or followed on from it, the size of the tree it holds and the bytes its run uploaded.
| Flag | Meaning |
|---|---|
| --json | Print a JSON array on stdout, one object per snapshot with snapshot_id, created_at, status, locked and locked_until. Every other line goes to stderr. |
| --from-bucket | List one of the surface's other buckets, by its name, instead of this host's storage (A second bucket). |
undelete
Brings back snapshots hidden by delete markers in a versioned bucket. It removes only delete markers, by version id, and cannot remove a version that holds data. With --all, it rolls the bucket back to before the deletion, every snapshot and sidecar, without uploading anything again (how a deletion is undone).
| Flag | Meaning |
|---|---|
| --snapshot | Make one snapshot visible again. |
| --all | Clear delete markers from every hidden snapshot. |
export
Copies every snapshot and its metadata, still encrypted, to a directory or to a bucket
you own. Use it to move off hosted storage or to keep an offline copy. It needs no key.
--snapshot and --node narrow what it copies.
An incremental files backup is copied a whole month (epoch) at a time, because a snapshot
needs every object of its month. --snapshot copies the month that holds that
snapshot. Each copy is checked against the digest recorded at backup time, and a snapshot
keeps its lock in the destination bucket. A snapshot already in the destination is skipped,
so you can run an interrupted export again. Credentials for --to-bucket come from
the standard AWS environment. safegrd restore --from restores from a directory
export.
| Flag | Meaning |
|---|---|
| --to-dir | Export into this local directory. |
| --to-bucket | Export into this S3 bucket. |
| --to-endpoint | S3 endpoint of the bucket (MinIO, B2, R2, ...). |
| --to-region | Region of the bucket. Default us-east-1. |
| --to-prefix | Key prefix in the bucket. Default safegrd/snapshots. |
| --to-worm-mode | COMPLIANCE (default), GOVERNANCE or NONE. |
| --snapshot | Export only this snapshot. Repeat it or give a comma-separated list. An id that is not in storage is an error. |
| --node | Export only the snapshots of the hosts with these node ids. Repeatable. |
copies
Keeps a surface's other buckets up to date (A second bucket).
status shows, for each surface and copy, how many backups within the copy's
retention the copy is missing. It exits non-zero when a copy is behind. sync writes
the missing backups from the surface's own storage. It checks for an archive before writing it,
so no archive is written twice, and it copies an incremental backup's run object by object. The
daemon runs the same sync every half hour for any copy that is behind.
| Flag | Meaning |
|---|---|
| --surface | Only this surface. |
| --copy | Only this copy, by its name. |
estimate
Measures a PostgreSQL database and prints the monthly egress of weekly, daily and hourly backups at its provider, after the egress the provider plan includes. Every backup reads every row uncompressed, so one backup reads about the size of the tables without their indexes.
The CLI reads the provider from the host name (Supabase, Neon, Amazon RDS). Its prices come from the providers' pricing pages, read on 5 October 2026. A warning on stderr names each schedule whose egress costs more a month than the SafeGrd plan you compare it with, at the price SafeGrd's server publishes. Your application's own traffic uses the same allowance, so pass what is left with --included-gb. For a database SafeGrd backs up for you, the console's add dialog prices the schedule before you add the surface (Price this schedule).
| Flag | Meaning |
|---|---|
| --database-url | The database to measure. Default: the first PostgreSQL surface in the config. |
| --surface | Measure this surface's database. |
| --provider | supabase, neon, rds or other. Default: read from the host name. |
| --provider-plan | The provider plan whose included egress applies: Supabase free, pro (default) or team; Neon free, launch (default) or scale. |
| --egress-price-per-gb | The price in US dollars per GB, for --provider other or to replace the one built in. |
| --included-gb | Free egress a month that your application does not already use. |
| --schedule | Also price this schedule, written the way the config writes it. |
| --plan | The SafeGrd plan to compare with: starter, growth (default) or scale. |
| --json | Print the estimate as JSON. |
keep
Extends one snapshot's lock to the end of --until (UTC). The backup file, its metadata and its recovery document are extended together. Nobody can shorten a lock once it is extended, so the date can be at most 13 months from today and the command needs --yes. In your own bucket, the host extends the lock and tells SafeGrd's server. That needs s3:PutObjectRetention and s3:GetObjectRetention. On hosted storage, SafeGrd's server extends it. An incremental snapshot is kept as long as its month, and you cannot keep one on its own (keep a snapshot longer).
| Flag | Meaning |
|---|---|
| --snapshot | The snapshot to keep longer. |
| --until | When the new lock ends: a date (locked to the end of that day, UTC) or an RFC 3339 time. |
| --yes | Extend the lock. Without this flag, the command says what it would lock and stops. |
prune
Deletes snapshots from your S3 bucket whose Object Lock retention expired more than a day ago,
going by the bucket's own timestamp and retention status. It needs the
s3:DeleteObjectVersion and s3:GetObjectRetention permissions. Set
storage.expire_after_lock: true to prune automatically every day.
prune always keeps:
- The newest
--min-keepsnapshots of each surface (three by default), whatever their locks say. - The last known-good snapshot, while Threat Shield (SafeGrd's anomaly detection) reports an open anomaly.
- The newest older backup whose drill passed, when none of the kept backups passed its Fire Drill and the oldest of them failed. prune says which backup it kept.
Snapshot versions are removed before delete markers and metadata. An incremental files backup is
pruned by month. A month's expired objects are deleted once every snapshot that could use them is
past its retention, and never from the month that holds the surface's newest snapshot. Each of your
other buckets is pruned next, by its own locks and min_keep, and prints its own
Prune offsite: line.
For a surface with erasures:, prune also prunes the erasure record. An object in it
is deleted once its lock and the grace period have passed and no backup older than its newest
erasure remains. The record's marker stays while the surface has a backup. On local storage, only
the erasure record is pruned.
| Flag | Meaning |
|---|---|
| --min-keep | How many of each surface's newest snapshots are never deleted, whatever their locks say. At least 1. Default 3. |
| --dry-run | List what would be deleted, and delete nothing. |
| --grace | How long after a lock ends a snapshot is kept anyway. Default 24h. |
| --from-bucket | Prune only this one of your other buckets, by its name (A second bucket). |
Unattended
daemon run
Runs the daemon. On each pass it finds the surfaces that are due and backs them up, with a lock per surface so a surface never runs two backups at once.
| Flag | Meaning |
|---|---|
| --once | Run one pass, then exit. Use it from cron or a Kubernetes Job. |
| --interval | How often the daemon polls. Default 5m. With --once, set it to how often your scheduler runs the pass. The host then counts as a daemon at that interval. It picks up Back up now and Drill now from the console on its next run, and the console shows it as silent when the runs stop. |
| --state-dir | Directory for state and locks. |
daemon status
Shows the current status of the daemon and of every surface in the config.
| Flag | Meaning |
|---|---|
| --json | Print the status as JSON. |
| --state-dir | State directory to read. |
$ safegrd daemon status SafeGrd daemon status Daemon ID: afc6de1d State dir: /home/safegrd/.safegrd SURFACE ID TYPE SCHEDULE LAST SUCCESS NEXT DUE STATUS shop postgres @daily 2026-10-18 02:40 UTC 2026-10-19 02:40 UTC OK
daemon install
Installs the daemon as a systemd unit or launchd job, or prints the definition with --print. After that, use daemon restart and daemon uninstall to manage it.
| Flag | Meaning |
|---|---|
| --user | Install as a user agent instead of a system service. |
| Print the service definition to stdout and install nothing. |
Diagnose
doctor
Checks what a backup on this host depends on: config permissions (0600 on POSIX), the keypair, that the WORM storage connects and that Object Lock works on it, that SafeGrd's server answers, and the host's clock skew.
It also opens every surface with the credential its backup will use. It runs a query on each PostgreSQL, MySQL, MongoDB and SQLite database, logs in to each mailbox and opens each files root. For each database it finds a pg_dump or mysqldump that can dump that server. For each PostgreSQL surface it warns when the role can write, prints the read-only role to use, and names the tables where row-level security hides rows (read-only role). On an enrolled host, doctor reports the results to the console, which shows the host as checked.
| Flag | Meaning |
|---|---|
| --json | Print the report as JSON. |
| --agent-proof | Check instead whether an AI agent on this host could destroy the backups, and print the fix for each failure. See Agent guard. |
$ safegrd doctor Doctor [PASS] Config Permissions : 0600 verified at /home/safegrd/.safegrd/config.yaml [PASS] Encryption Public Key : valid Age public key (age1lq70sjlq...) [PASS] Storage Configuration : SafeGrd hosted storage (the remote server leases it for each run) [PASS] Surface shop schedule : "@daily" runs every 24h [PASS] Surface shop (postgres) : configured [PASS] Encryption Recipient Source : local config [PASS] Surface shop credentials : resolve (from the environment variable SHOP_DB) [PASS] Surface shop connection : opened shop on db.internal:5432 [PASS] Surface shop role : safegrd_backup writes to no table [PASS] TLS to surface shop : the server's certificate is checked against /etc/ssl/rec-ca.crt (1 certificates) [PASS] pg_dump for surface shop : pg_dump 18.6 (/usr/bin/pg_dump) can dump this PostgreSQL 16 server [PASS] Decryption Private Key : valid Age private identity key present [PASS] Hosted Storage : 675.6 KiB of 250.0 GiB locked in SafeGrd hosted storage (compliance mode) [PASS] Storage Provider Init : initialized hosted backend [PASS] Storage Read : hosted storage readable, 2 snapshots [PASS] Remote Server Reachability : connected to https://safegrd.dev (HTTP 200) [PASS] Host Clock Skew : in sync (skew 0.95s) [PASS] Key Custody : SafeGrd-managed key. SafeGrd keeps your key sealed and releases it only to your enrolled hosts, so you can restore even after losing a host All critical checks passed. Reported to https://safegrd.dev: the console shows this host as checked.
config validate
Checks the config's syntax, its file permissions and the surface definitions, without running anything.
mcp
Runs an MCP server on stdin and stdout, so a coding agent on the same machine can use this host's safegrd (claude mcp add safegrd -- safegrd mcp). Its tools are status, list, doctor, backup, verify, restore and export, and each runs with this host's config. No tool deletes a backup or takes a private key. The restore tool writes only into a new or empty directory or an empty database. For the hosted MCP server, which needs no install, see the MCP page.
Organization
org
org list prints your organization's profile, plan and quota status. org members lists the team. orgs works as an alias.
project
Lists the projects inside an organization.
version
Prints the CLI version, commit and build date. Include it in any bug report.
Environment variables
| Variable | Meaning |
|---|---|
| SAFEGRD_SERVER_URL | SafeGrd's server, the same as --server-url. |
| SAFEGRD_PRIVATE_KEY | The Age private identity, for restores and drills on a host without the key file. |
| SAFEGRD_EMAIL_PASSWORD | Mailbox password. Use this instead of the flag. |
| SAFEGRD_EMAIL_CA_FILE | PEM bundle of extra CAs to trust for IMAP. |
Token lifetime
A personal access token works until the date you pick when you create it, from 7 days to a
year. The default is 90 days. The console shows the date beside each token, and does not offer
tokens without an end date. Give each pipeline or cluster its own token, scoped to the one
project it needs, and create the next one before the date. The token that
safegrd login creates lasts 30 days. On a host, enroll replaces it with
the host's own token.