Agent Commerce
Star on GitHub

Commands

agent-commerce backup

Back up the receipt database and unimported legacy files to a new directory with a backup.json manifest.

Usagebash
agent-commerce backup --out <dir> [--config <path>] [--env-file <path>] [--json]

Back up the receipt database to a new or empty directory with a backup.json manifest. For enabled AP2/ACP, include configured legacy files that exist, are not :memory: and have no recorded import. Sources open read-only without migration, imports or write locks, allowing backups beside a live gateway.

Options

--out <dir>required
A new or empty directory. Its parent must exist; new directories use 0700, and existing ones keep their permissions. Nonempty directories are refused before writing.
--config <path>
Path to the config.
--env-file <path>
Load environment variables before reading the config. Variables already set in the environment take precedence.
--jsondefault: false
Print the output directory and the manifest as JSON.

What it writes

FileSource
receipts.sqlitestorage.receipts.path, at schema v4 (2.5) or v5 (2.6); any other version is refused
ap2-replay.sqliteauthorization.ap2.replay.path, until its first 2.6.0 start imports it
acp-idempotency.sqliteprotocols.acp.idempotency.path, until its first 2.6.0 start imports it
backup.jsonwritten last: the package version, creation time, and each copy's config key, schema version and SHA-256

Each file is a separate, consistent VACUUM INTO snapshot at 0600, verified by PRAGMA integrity_check. Without backup.json, the backup is incomplete. Missing and in-memory receipt databases are refused.

Output

console
$ agent-commerce backup --out ./backups/2026-11-01
backup written to /srv/agent-commerce/backups/2026-11-01
  receipts.sqlite          storage.receipts.path (schema v5)

Exit 0 means a complete backup; 1 means failure. Backup errors print FAIL backup: …; config errors use the validation error format. For restore steps, see Storage.