snapshots

List snapshots for a target, and manage them with retention (prune) and pinning.

Usage

clonit snapshots <target>
clonit snapshots prune    <target> [flags]
clonit snapshots pin      <target> <index|name>
clonit snapshots unpin    <target> <index|name>
clonit snapshots validate <target> [index|name|latest|prev] [flags]

Arguments

Argument	Description	Required
target	Name of the target	Yes

Description

clonit snapshots <target> displays a table of all snapshots for a target. Each snapshot has an Index (positional, 0 = newest) and a Ver (a stable-ish version ordinal, v1 = oldest … vN = newest). The Pin column shows PIN for pinned snapshots.

Column	Description
Index	Positional index (0 = newest); the fragile selector — it shifts when snapshots are pruned
Ver	Version ordinal, v1 (oldest) … vN (newest); renumbers when older snapshots are pruned
Name	Snapshot name (timestamp-prefixed)
Type	original or sanitized
Pin	PIN when the snapshot is pinned (protected from prune)
From	Short id of the source snapshot (sanitized snapshots)
Rows	Total sanitized row count when captured
Size	Human-readable size
Local / Storage	Local file + remote sync status
Created	Creation timestamp

Snapshot selectors (load / pull / pin / unpin)

Commands that take a snapshot reference accept any of:

• latest (or an empty reference) — the newest snapshot
• prev — the second-newest snapshot
• a snapshot name (e.g. 1738900000_mydb_1a2b3c4d)
• a positional index (all-digit token; 0 = newest, matching the Index column)

Names always contain non-digit separators, so an all-digit token is always an index, never a name. Prefer latest/prev/name over an index — the index shifts when snapshots are pruned.

snapshots prune

clonit snapshots prune <target> [--dry-run] [--keep-last N] [--max-age-days D] [--remote] [--yes]

Deletes snapshots that fall outside the resolved retention policy.

A snapshot is protected (kept) when it is within keep-last N or within max-age D days (a safe union). Everything else is eligible for deletion, except the absolute vetoes, which are never deleted:

• pinned snapshots (see pin below);
• the source of a sanitized snapshot (lineage is never orphaned);
• the last remaining snapshot of a target (a target is never emptied).

Policy precedence

Highest wins:

1. explicit --keep-last / --max-age-days flags;
2. the target’s own keep_last / max_age_days columns (set via targets update; a cloud-distributed policy is applied here too);
3. the global defaults.retention.* config.

If no policy resolves (all knobs 0), nothing is deleted.

Flags

Flag	Type	Default	Description
--dry-run	bool	false	Print the plan without deleting anything
--keep-last	int	0	Override: keep the N newest snapshots (0 = off)
--max-age-days	int	0	Override: keep snapshots at most D days old (0 = off)
--remote	bool	false	Also delete each snapshot’s direct-push remote object (warns and continues per object on failure)
--yes	bool	false	Confirm deletion — required when running interactively

Without --dry-run, prune deletes each snapshot’s local DB row and zip file. Running interactively without --yes refuses (re-run with --yes); prune never prompts. The plan table shows Ver, Name, Age, Size, Action, and Reason.

snapshots pin / snapshots unpin

clonit snapshots pin   <target> <index|name>
clonit snapshots unpin <target> <index|name>

Pinning marks a snapshot as an absolute veto: prune (and the build auto-prune sweep) will never delete it, regardless of age or keep-last rank. The snapshot is identified with the same selectors as load/pull (index, name, latest, prev).

snapshots validate

clonit snapshots validate <target> [index|name|latest|prev] [--image <docker-image>]

Re-validate an existing local snapshot on demand, without re-sanitizing it. The chosen snapshot is loaded into a throwaway PostgreSQL container and the same detector-based validation pass used by sanitize --validate runs against the target’s latest completed analyze run.

This is the way to re-check a stored snapshot against a newer analysis than the one it was originally validated with — for example after analyze flags additional sensitive columns. Both original and sanitized snapshots can be re-validated. The report is persisted onto that snapshot (replacing any previous report) and shown in the web UI’s snapshot detail view.

The snapshot reference accepts the same selectors as load/pull (index, name, latest, prev); it defaults to latest.

Flags

Flag	Type	Default	Description
--image	string	(auto)	Override the Docker image used for the throwaway container (e.g. postgres:16); defaults to a version-pinned image matching the local tools

Exit-code contract (CI gate)

Re-validation reuses the sanitize validation exit-code contract:

• passed — no sensitive values found → success, exit 0.
• failed — matches found → a violations table (counts only; matched values are never printed or stored) is printed and the command exits non-zero.
• skipped — the target has no completed analysis (run clonit analyze first) → a warning is printed, exit 0.
• error — the validation pass could not connect to the loaded database → a warning is printed, exit 0.

Requires Docker (the snapshot is loaded into a throwaway container).

Retention config keys

Global defaults (lowest precedence), under defaults.retention:

Key	Default	Description
defaults.retention.keep_last	0	Keep the N newest snapshots (0 = off)
defaults.retention.max_age_days	0	Keep snapshots at most D days old (0 = off)
defaults.retention.auto_prune	false	Run a (local-only, non-interactive) prune after each successful build auto-push, using the resolved policy

Examples

List snapshots:

clonit snapshots mydb

Preview what a policy would prune:

clonit snapshots prune mydb --keep-last 5 --dry-run

Prune to the target’s configured policy, deleting remote objects too:

clonit snapshots prune mydb --remote --yes

Pin the latest snapshot so retention never deletes it:

clonit snapshots pin mydb latest

See Also

• build – Create a snapshot of the source database
• load – Load a snapshot into the destination database
• push – Push a snapshot to remote storage
• pull – Pull a snapshot from remote storage
• sanitize – Sanitize a snapshot (and optionally --validate it)
• analyze – Detect sensitive columns (the basis for validation)
• targets update – Set a target’s keep_last / max_age_days