2.13.0-beta.20). Features may change before the next stable release.Switch to stable →ak backups
ak backups
Inspect, verify, prune, and restore the bounded rollback snapshots managed by AgentKit.
Use ak backups as the entry point for AgentKit recovery snapshots. The group
itself is read-only: running it without a subcommand prints help and exits 0.
Usage
ak backups <subcommand>ak backups --json still prints group help; it does not produce a JSON result.
Use --json on a runnable subcommand. Shared flags are described in
CLI conventions, but each backup operation has its own
confirmation, output, and exit contract.
Choose an operation
| Goal | Command | Mutation behavior |
|---|---|---|
| List rollback snapshots newest first | ak backups list | Read-only. |
| Inspect one manifest | ak backups show <id> | Read-only. |
| Recompute file hashes | ak backups verify <id> | Read-only; reports ok or corrupt. |
| Preview or restore captured state | ak backups restore <id> | --dry-run previews; apply can replace or remove paths authorized by the manifest. |
| Restore the newest snapshot | ak backups restore --latest | Same restore engine and safety rules. |
| Delete snapshots by retention policy | ak backups prune | Deletes by default; add --dry-run to preview. |
| Stage a consistent operational database copy | ak backups create | Replaces the operational staging directory and writes a verified operational.db copy. |
The top-level ak recover [id] command is another entry point to the restore
engine. It is not a Cobra alias of ak backups restore.
Understand snapshot boundaries
Rollback snapshots live under ~/.agentkit/backups/, or under
$AGENTKIT_HOME/backups/ when that environment variable is set. Every snapshot
has an ID shaped like YYYYMMDDTHHMMSSZ-<8-hex>, a manifest, captured data, and
hash metadata.
The creating lifecycle operation decides which exact files or authorized roots are captured. A snapshot is not a whole-machine backup, and different snapshot kinds can have different restore scopes. Inspect the manifest before recovery:
ak backups show <id>
ak backups verify <id>
ak backups restore <id> --dry-runManifest hashes detect accidental or partial changes; they do not authenticate a snapshot against an attacker who can rewrite the snapshot and its metadata. Protect your AgentKit home with normal user-level filesystem permissions.
ak backups create is separate from the ID-based rollback store. The current
implementation stages and verifies operational.db in the system temporary
directory; it does not mint an ID that appears in ak backups list.
Apply the command-specific safety rules
prunedoes not ask for confirmation. Preview the exact remove set first.restoreasks on an interactive TTY, but JSON,--no-interactive, or non-TTY stdin can proceed without--yes. Use--yesto make automation intentional.- Backup restore and prune operations use cross-process locks. Lock contention fails instead of waiting indefinitely.
- A restore dry-run preflights the live paths without changing them. An applied restore can overwrite captured files and remove paths that were absent at snapshot time.
Applied restore success is an output exception: even with --json, stdout is
empty and stderr prints a plain completion line. Only
ak backups restore --dry-run --json emits the
kind=backups.restore_plan success envelope.
Recovery workflow
- List snapshots and select the one created before the unwanted change.
- Show and verify it.
- Run a restore dry-run and review every restore and removal path.
- Apply only after confirming that the manifest owns the intended scope.
If verification reports corruption, do not restore that snapshot. A pruned snapshot has no built-in undelete path; recover it from an independent filesystem backup if one exists.