> ## 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.

# gandalf snapshot: create, list, and show snapshots

> Create content-backed or metadata-only snapshots of your Codex or Claude Code setup, list saved snapshots, and inspect the manifest for any snapshot.

`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

```bash theme={null}
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.

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

  ```bash Claude Code content-backed 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>

## snapshot list

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

```bash theme={null}
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.

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

## Related

* [Snapshots concept](/concepts/snapshots)
* [`gandalf diff`](/cli/diff)
* [`gandalf restore`](/cli/restore)