Skip to main content
A snapshot is a named, point-in-time capture of your user-global agent evidence. Gandalf stores snapshots under ~/.gandalf (or $GANDALF_STORE) and uses them as the input to diffs, restores, reports, and bundle exports.

​
Content-backed vs metadata-only

Gandalf produces two snapshot kinds:
  • Content-backed snapshot: includes captured file bytes alongside metadata and structured evidence. This is required for safe restore --apply, because byte-exact restoration of agent config files depends on stored content. Content-backed capture is available for user-global setup of currently supported agents.
  • Metadata-only snapshot: records evidence metadata (kinds, paths, structured values) without capturing file bytes. Use this for inventory tracking, cross-agent reports, or when the content-backed path is not available.
Content-backed capture requires an explicit --agent and --scope user for a supported agent. If those are missing and you did not pass --metadata-only, Gandalf refuses the capture with the GANDALF_METADATA_ONLY_REQUIRED error.

​
Create a snapshot

​
List and inspect

snapshot list prints names or JSON. snapshot show <name> prints the manifest name, or the full snapshot object when --json is passed.

​
The current reference

Every command that takes a snapshot ref accepts the special value current to mean “capture live state now, without persisting it.” This is what lets you compare a saved baseline to whatever is on disk:
Reports and restore planning use the same reference model.

​
The store

  • Default location: ~/.gandalf
  • Override: --store /path/to/store or $GANDALF_STORE
  • Layout: snapshots, timeline entries, and index. The CLI and TUI read the same store APIs, so writes stay atomic across readers.
Snapshots are the foundation for every safety workflow in Gandalf: Review Changes previews compare against them, restore writes from them, and bundles export them for another machine.