gandalf snapshot: create, list, and show snapshots - Gandalf

gandalf snapshot manages the point-in-time captures Gandalf uses for diffs, restores, and bundles. It has three subcommands: create, list, and show. Snapshots live under ~/.gandalf (or $GANDALF_STORE).

Synopsis

gandalf snapshot create --name <name> [--metadata-only] [flags]
gandalf snapshot list [flags]
gandalf snapshot show <name> [--json] [flags]

Common flags

Flag	Description	Default
`-p`, `--project`	Project directory	`.`
`--home`	Home directory	`$HOME`
`--store`	Gandalf store directory	`~/.gandalf` or `$GANDALF_STORE`
`--agent`	Filter by agent (`codex`, `claude-code`)	(unfiltered)
`--scope`	Filter by scope (`user`, `project`, `managed`, `unknown`)	(unfiltered)
`--json`	Emit JSON output	off

snapshot create

Captures and persists a snapshot. --name is required.

Flag	Description	Default
`--name`	Snapshot name (required)	-
`--metadata-only`	Store metadata only, no file content	off

Content-backed capture requires --agent codex --scope user or --agent claude-code --scope user. Without one of those, pass --metadata-only or you will get the GANDALF_METADATA_ONLY_REQUIRED error.

gandalf snapshot create --name baseline --agent codex --scope user --project .

gandalf snapshot create --name baseline-claude --agent claude-code --scope user --project .

gandalf snapshot create --name inventory --metadata-only --project .

snapshot list

Prints saved snapshot names, one per line. Add --json for a JSON array.

gandalf snapshot list
gandalf snapshot list --agent codex
gandalf snapshot list --json

snapshot show

Prints the manifest name for a snapshot. With --json, prints the full snapshot object.

gandalf snapshot show baseline
gandalf snapshot show baseline --json

⌘I