> ## 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 diff: compare two snapshots

> Show semantic and raw-source changes between any two Gandalf snapshots, or between a saved snapshot and current live state, with text or JSON output.

`gandalf diff` compares two snapshots and reports what changed. Output separates semantic changes (typed entities such as MCP server entries) from raw source changes (file-level additions and removals). Use the special `current` ref to compare against live state without persisting a new snapshot.

## Synopsis

```bash theme={null}
gandalf diff <baseline> <target> [flags]
```

Both `<baseline>` and `<target>` are snapshot names, or the special ref `current`.

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

## Examples

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

  ```bash Claude Code theme={null}
  gandalf diff baseline-claude current --agent claude-code --scope user --project .
  ```

  ```bash JSON theme={null}
  gandalf diff baseline current --agent codex --scope user --project . --json
  ```
</CodeGroup>

## Output shape

The text output has two sections:

* **Semantic changes**: severity-labeled entries with a code and entity name.
* **Raw source changes**: file status and source path per entry.

Use `--json` for the machine-readable graph diff.

## Related

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