Docs / Command reference

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.

prod-app-01
$ 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.

prod-app-01
$ 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.

prod-app-01
$ 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
The certificate is the signed record of this drill. The console lists it under Fire Drills, and you can check its signature offline.

4. Restore it into an empty database

The snapshot comes down still encrypted, and this host decrypts it.

prod-app-01
$ 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.
Recorded on 18 October 2026 with this release's CLI, against PostgreSQL 16. The test server's address is shown as https://safegrd.dev.

Global flags

FlagMeaning
--configConfig file. Default ~/.safegrd/config.yaml.
--server-urlSafeGrd's server. Default $SAFEGRD_SERVER_URL if set, else https://safegrd.dev.
-v, --versionPrint 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.

CodeMeaning
0The command did what it was asked.
1Failed, for a reason not listed below. The Error: line says why.
3guard only: no locked snapshot was taken, so guard did not run the command.
10The source failed: the database, mailbox or directory refused the connection or the credential, or does not exist.
11SafeGrd'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).
12Storage failed: the CLI could not open, write or read the bucket or directory the backups go to.
130Interrupted with Ctrl-C or SIGTERM.
140wal 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

safegrd try <database-url | directory> [flags]

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.

FlagMeaning
--key-custodysafegrd (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.
--nameThis host's name in the console. Default: the hostname.
--no-browserPrint the sign-up link without opening a browser.

signup

safegrd signup [--no-browser]

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

safegrd init [flags]

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.

FlagMeaning
--node-nameThis host's name in the console. Default: the hostname.
--database-urlThe 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.
--laravelAdd 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-idWith --laravel: the surface's id. Default: APP_NAME as a slug, or the directory's name if APP_NAME is not set.
--migrations-tableWith --laravel: the app's migrations table, if it is not named migrations.
--storagelocal, s3 or hosted. Default local.
--local-pathThe directory backups go to with --storage local.
--s3-bucketBucket for WORM storage.
--s3-prefixKey prefix in the bucket. Default safegrd/snapshots.
--s3-regionBucket region. Default us-east-1.
--s3-endpointCustom endpoint, for MinIO, R2 or Wasabi.
--retention-daysWORM retention in days. Default 14.
--worm-modeObject Lock mode for --storage s3: COMPLIANCE (default), GOVERNANCE, or NONE for a bucket with no Object Lock, such as DigitalOcean Spaces.
--forceOverwrite 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

safegrd enroll [flags]

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.

FlagMeaning
--tokenA personal access token to register a new host, or a node token together with --node-id. Takes env:VAR or file:/path.
--node-idThe 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-nameThis host's name in the console. Default: the hostname.
--orgThe organization to enroll into. Needed only when the credential can see more than one.
--projectProject id or slug. Defaults to the organization's default project.
--key-custodysafegrd (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.
--storageWhere 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-unconfiguredEnroll 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

safegrd keygen [--out path] | safegrd keygen --recipient path | safegrd keygen --held [--snapshot id] --out path

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.

FlagMeaning
--outWhere to write the private key. Default: ~/.safegrd/keys/daemon.key. Required with --held.
--recipientPrint the public key for the private key in this file. Generates nothing.
--heldWrite a copy of the SafeGrd-managed key. Generates nothing.
--snapshotWith --held: write the key this snapshot was sealed to, instead of this host's.
prod-app-01
$ 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
A customer-managed key. keygen writes the private key and prints the public key for the hosts that back up.
prod-app-01
$ 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.
A copy of a SafeGrd-managed key, written on an enrolled host. The key access record lists the copy.

claim

safegrd 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

safegrd login [flags]

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.

FlagMeaning
--tokenPersonal access token (sg_pat_...) for CI and headless use.
--no-browserPrint the URL instead of opening a browser.

whoami

safegrd whoami

Prints who you are signed in as and the active server session.

Protect

backup

safegrd backup [flags]

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).

FlagMeaning
--database-urlDatabase 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.
--surfaceThe 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.
--filesDirectory 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.
--emailBack up an IMAP mailbox. Selects the email surface.
--excludeGlob patterns to leave out of a file backup, for example '*.tmp,node_modules/*'.
--noteA note on the snapshot, key=value, repeatable. See note.
--compressionHow hard to compress: zstd:1 (fastest) to zstd:19 (smallest). A restore needs no matching setting. In the config, set compression on the surface.
--formatHow --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-logFor 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-passwordsPostgreSQL: 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-epochStart a new monthly epoch now, which uploads everything once. Works with --format repo or --surface.
--rescanRead every file, not only those whose size or times changed. Works with --format repo or --surface.
--one-filesystemStay on the root's filesystem. On by default when the root is /.
--email-hostIMAP hostname.
--email-portIMAP TLS port. Default 993.
--email-userMailbox username or address.
--email-passwordMailbox password. Use SAFEGRD_EMAIL_PASSWORD instead where you can, because a flag shows in the process table.
--email-foldersFolders to back up. Default: all except spam and trash.
--email-ca-fileA 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-daysHow 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-monthlyLock 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-bucketWrite to this bucket instead of the project's or the config's.
--s3-prefixKey prefix in the bucket.
--s3-endpointS3 endpoint, for MinIO, R2 or another S3-compatible store.
--s3-regionS3 region.
--s3-access-keyS3 access key id.
--s3-secret-keyS3 secret access key, as env:VAR or file:/path.
--tagA prefix for the snapshot tag.
--jsonPrint the result as JSON.
prod-app-01
$ 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
One surface backed up between scheduled runs. 312 rows were new since the last run, so 19.1 KiB of the 3.2 MiB read was uploaded.

guard

safegrd guard [--surface ID] [-- command [args...]]

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.

FlagMeaning
--surfaceThe surface to back up, by its id in the config.
--allow-unlockedRun the command even when the backup is not locked, as on local storage or with worm_mode: NONE.
--listPrint the rules that mark a command as destructive.
--matchesCheck a command against the rules and take no backup: exit 0 if it matches, 1 if not.
--hookAnswer a pre-command hook on stdin: claude-code, cursor or codex.

wal

safegrd wal push | base | bundle | status | point | restore | drill | fetch

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

safegrd restore --snapshot <id> | --path <file> | --table <schema.table> | --from <export> [flags]

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).

FlagMeaning
--snapshotThe 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.
--fromThe export to restore from: the directory export --to-dir wrote (add --snapshot), or one .safegrd file in it.
--from-bucketRead the snapshot from one of the surface's other buckets, by its name in copies: or in the console (A second bucket).
--requestRun 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).
--targetThe 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-dirThe 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.
--pathFor an incremental files snapshot: restore only this path, relative to /. Repeatable. *, ? and ** work as wildcards.
--tableRestore 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.
--asWith 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.
--rowsWith 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.
--overwriteWith --rows: replace a row the target already has with the backup's. Without this flag, a restore does not write over existing data.
--versionWith one --path or --table: restore this version, numbered as safegrd find lists them, instead of naming a --snapshot.
--surfaceWith --version: the surface whose repository holds the file, when more than one does.
--schemaPostgreSQL 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-schemaPostgreSQL 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.
--salvageFor 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-erasuresPostgreSQL 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-activePostgreSQL 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.
--parallelFor 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-ownerPostgreSQL 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-sqlWrite 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-pathPath to the Age private identity file.
--private-keyThe Age private identity inline (AGE-SECRET-KEY-1...).

verify

safegrd verify --snapshot <id> [flags]

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.

FlagMeaning
--snapshotSnapshot id to verify. Required.
--surfaceFor 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-memoryRestore in memory, with no target database, even when --sandbox-target is set. This is the default when --sandbox-target is not set.
--sandbox-targetAn 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-sandboxWhen a sandbox drill fails, record that the sandbox is kept for someone to inspect.
--queryRead 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.
--outWith --query: write the CSV to this file instead of stdout.
--keepWith --query: keep the PostgreSQL cluster the run started running for a day, and print how to connect to it with psql.
--show-urlWhen a sandbox drill fails, print the sandbox URL with its password.
--key-pathPath to the Age private identity file.
--private-keyThe Age private identity inline.
--s3-bucketRead the snapshot from this bucket instead of the configured storage.
--s3-prefixKey prefix in the bucket.
--s3-endpointS3 endpoint, for MinIO, R2 or another S3-compatible store.
--s3-regionS3 region.
--from-bucketRead the snapshot from one of the surface's other buckets, by its name (A second bucket).
--s3-access-keyS3 access key id.
--s3-secret-keyS3 secret access key, as env:VAR or file:/path.
A Fire Drill, then a restore of the same backup. This host is not enrolled, so the CLI says the result was not reported to SafeGrd. On an enrolled host, SafeGrd records and signs the result.

note

safegrd note <snapshot> key=value... [--json]

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

safegrd find <pattern>... [flags]

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.

FlagMeaning
--surfaceSearch 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.
--tableList 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.
--deletedList only files the newest snapshot no longer holds.
--from-bucketSearch one of the surface's other buckets, by its name, instead of this host's storage (A second bucket).
--jsonPrint the histories as JSON.
--key-pathPath to the Age private identity file.
--private-keyThe Age private identity inline.

check

safegrd check --snapshot <id> | --epoch <id> | --all [--read-data]

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.

FlagMeaning
--read-dataAlso open every chunk and check its SHA-256. This downloads the snapshot's data.
--key-pathPath to the Age private identity file.
--private-keyThe Age private identity inline.

verify history

safegrd verify history [flags]

Checks a host's attestation chain, and each record's Ed25519 signature against the key the record names.

FlagMeaning
--nodeThe node id of the host whose history to check.
--fileLocal JSON file of verifications, for an offline audit.
--saveAlso write the records fetched from SafeGrd to this file, for a later --file check.
--keyOne hex-encoded Ed25519 public key, checked against every record. file:/path reads it from a file.
--keys-fileThe 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.
--jsonPrint the result as JSON, with the keys that signed the chain.

Storage

list

safegrd 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.

FlagMeaning
--jsonPrint 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-bucketList one of the surface's other buckets, by its name, instead of this host's storage (A second bucket).

undelete

safegrd undelete [flags]

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).

FlagMeaning
--snapshotMake one snapshot visible again.
--allClear delete markers from every hidden snapshot.

export

safegrd export --to-dir <dir> | --to-bucket <bucket> [flags]

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.

FlagMeaning
--to-dirExport into this local directory.
--to-bucketExport into this S3 bucket.
--to-endpointS3 endpoint of the bucket (MinIO, B2, R2, ...).
--to-regionRegion of the bucket. Default us-east-1.
--to-prefixKey prefix in the bucket. Default safegrd/snapshots.
--to-worm-modeCOMPLIANCE (default), GOVERNANCE or NONE.
--snapshotExport only this snapshot. Repeat it or give a comma-separated list. An id that is not in storage is an error.
--nodeExport only the snapshots of the hosts with these node ids. Repeatable.

copies

safegrd copies status | sync [--surface <id>] [--copy <name>]

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.

FlagMeaning
--surfaceOnly this surface.
--copyOnly this copy, by its name.

estimate

safegrd estimate --database-url postgres://... [flags]

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).

FlagMeaning
--database-urlThe database to measure. Default: the first PostgreSQL surface in the config.
--surfaceMeasure this surface's database.
--providersupabase, neon, rds or other. Default: read from the host name.
--provider-planThe provider plan whose included egress applies: Supabase free, pro (default) or team; Neon free, launch (default) or scale.
--egress-price-per-gbThe price in US dollars per GB, for --provider other or to replace the one built in.
--included-gbFree egress a month that your application does not already use.
--scheduleAlso price this schedule, written the way the config writes it.
--planThe SafeGrd plan to compare with: starter, growth (default) or scale.
--jsonPrint the estimate as JSON.

keep

safegrd keep --snapshot <id> --until <date> --yes

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).

FlagMeaning
--snapshotThe snapshot to keep longer.
--untilWhen the new lock ends: a date (locked to the end of that day, UTC) or an RFC 3339 time.
--yesExtend the lock. Without this flag, the command says what it would lock and stops.

prune

safegrd prune [--dry-run] [--grace 24h] [--min-keep 3] [--from-bucket name]

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-keep snapshots 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.

FlagMeaning
--min-keepHow many of each surface's newest snapshots are never deleted, whatever their locks say. At least 1. Default 3.
--dry-runList what would be deleted, and delete nothing.
--graceHow long after a lock ends a snapshot is kept anyway. Default 24h.
--from-bucketPrune only this one of your other buckets, by its name (A second bucket).

Unattended

daemon run

safegrd daemon run [flags]

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.

FlagMeaning
--onceRun one pass, then exit. Use it from cron or a Kubernetes Job.
--intervalHow 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-dirDirectory for state and locks.

daemon status

safegrd daemon status [flags]

Shows the current status of the daemon and of every surface in the config.

FlagMeaning
--jsonPrint the status as JSON.
--state-dirState directory to read.
prod-app-01
$ 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

safegrd daemon install [flags]

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.

FlagMeaning
--userInstall as a user agent instead of a system service.
--printPrint the service definition to stdout and install nothing.

Diagnose

doctor

safegrd doctor [flags]

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.

FlagMeaning
--jsonPrint the report as JSON.
--agent-proofCheck instead whether an AI agent on this host could destroy the backups, and print the fix for each failure. See Agent guard.
prod-app-01
$ 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

safegrd config validate

Checks the config's syntax, its file permissions and the surface definitions, without running anything.

mcp

safegrd 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

safegrd org list | safegrd org members

org list prints your organization's profile, plan and quota status. org members lists the team. orgs works as an alias.

project

safegrd project list [--org <id>]

Lists the projects inside an organization.

version

safegrd version

Prints the CLI version, commit and build date. Include it in any bug report.

Environment variables

VariableMeaning
SAFEGRD_SERVER_URLSafeGrd's server, the same as --server-url.
SAFEGRD_PRIVATE_KEYThe Age private identity, for restores and drills on a host without the key file.
SAFEGRD_EMAIL_PASSWORDMailbox password. Use this instead of the flag.
SAFEGRD_EMAIL_CA_FILEPEM 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.