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

# Quickstart: capture a baseline and preview a restore

> Install Gandalf, capture a content-backed baseline of your Codex or Claude Code setup, diff it, and preview a safe restore in under five minutes.

This quickstart walks through installing Gandalf, capturing a content-backed snapshot of your user-global Codex or Claude Code setup, diffing it against your current state, and previewing a restore. No files are changed until you explicitly opt in with `--apply --experimental`.

## Prerequisites

* macOS or Linux (amd64 or arm64).
* A user-global setup for at least one of Codex (`~/.codex/`) or Claude Code (`~/.claude/`).

## 1. Install

<CodeGroup>
  ```bash Homebrew theme={null}
  brew install qyinm/tap/gandalf
  gandalf --help
  ```

  ```bash install.sh theme={null}
  curl -fsSL https://raw.githubusercontent.com/qyinm/gandalf/main/install.sh | sh
  gandalf --help
  ```

  ```bash Go theme={null}
  go install github.com/qyinm/gandalf/cmd/gandalf@latest
  ```
</CodeGroup>

See [Install](/install) for more details.

## 2. Open the terminal workspace

Running `gandalf` with no arguments opens the Changes-first Home in the Bubble Tea TUI:

```bash theme={null}
gandalf
```

The sidebar links Home, Console, Changes, Timeline, and Saves. The Console tabs cover Hooks, Plugins, Marketplace, Skills, and MCP Servers. Every write begins with Review Changes.

## 3. Capture a content-backed baseline

Content-backed snapshots are what make restore safe. They require an explicit `--agent` and `--scope user` for a currently supported agent.

<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 .
  ```
</CodeGroup>

Snapshots are written to `~/.gandalf` (or `$GANDALF_STORE`). List and inspect them:

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

## 4. Diff against your current state

Change something in your agent setup (add a skill, edit a hook), then compare:

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

The output separates **semantic changes** (typed entities such as MCP server entries) from **raw source changes** (file-level additions and removals). Add `--json` for machine-readable output.

## 5. Preview a restore

Dry-run is the default and never writes:

```bash theme={null}
gandalf restore --snapshot baseline --dry-run --agent codex --scope user --project .
```

The plan lists writable changes, unsupported items with reasons, per-item risk, and rollback instructions.

## 6. Apply after review

Applying requires both `--apply` and `--experimental` (or `GANDALF_EXPERIMENTAL=1`). Gandalf creates a pre-apply restore point before writing.

```bash theme={null}
gandalf restore --snapshot baseline --apply --experimental --agent codex --scope user --project .
```

Add `--rollback` to automatically undo on failure:

```bash theme={null}
gandalf restore --snapshot baseline --apply --experimental --rollback --agent codex --scope user --project .
```

## Next steps

<CardGroup cols={2}>
  <Card title="Terminal workspace" icon="terminal" href="/guides/terminal-workspace">
    Navigate Home, Console, Changes, Timeline, and Saves.
  </Card>

  <Card title="Bundles" icon="box" href="/guides/bundles">
    Export, verify, and import portable `.gandalf` archives.
  </Card>

  <Card title="Team manifest" icon="users" href="/guides/team-manifest">
    Declare shared MCP servers and skills in `gandalf.toml`.
  </Card>

  <Card title="Trust contract" icon="shield" href="/trust-contract">
    Read the safety boundaries Gandalf promises.
  </Card>
</CardGroup>