> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots: point-in-time agent setup captures

> Snapshots persist your Codex or Claude Code user-global agent state. Content-backed snapshots power safe restore; metadata-only snapshots capture inventory.

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

<CodeGroup>
  ```bash Codex theme={null}
  gandalf snapshot create --name baseline --agent codex --scope user --project .
  ```

  ```bash Claude Code theme={null}
  gandalf snapshot create --name baseline-claude --agent claude-code --scope user --project .
  ```

  ```bash Metadata-only theme={null}
  gandalf snapshot create --name inventory --metadata-only --project .
  ```
</CodeGroup>

## List and inspect

```bash theme={null}
gandalf snapshot list
gandalf snapshot list --agent codex
gandalf snapshot show baseline --json
```

`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:

```bash theme={null}
gandalf diff baseline current --agent codex --scope user --project .
```

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](/concepts/review-changes) previews compare against them, [restore](/cli/restore) writes from them, and [bundles](/guides/bundles) export them for another machine.