> ## 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 restore: preview and apply a snapshot

> Preview a restore plan from a Gandalf snapshot, then apply with explicit experimental flags. Optional rollback on failure and fail-fast execution.

`gandalf restore` builds a restore plan from a saved snapshot and, with explicit opt-in flags, applies it. Dry-run is the default. Apply requires both `--apply` and `--experimental` (or `GANDALF_EXPERIMENTAL=1`), and Gandalf creates a pre-apply restore point before writing.

## Synopsis

```bash theme={null}
gandalf restore --snapshot <name> [flags]
```

## Flags

| Flag              | Description                                     | Default                          |
| ----------------- | ----------------------------------------------- | -------------------------------- |
| `--snapshot`      | Snapshot to restore from (required)             | -                                |
| `--dry-run`       | Preview without writing                         | on when `--apply` is omitted     |
| `--apply`         | Apply restore items (requires `--experimental`) | off                              |
| `--experimental`  | Enable experimental apply mode                  | off                              |
| `--fail-fast`     | Stop on first failure during apply              | off                              |
| `--rollback`      | Auto-rollback on failure                        | off                              |
| `-p`, `--project` | Project directory                               | `.`                              |
| `--home`          | Home directory                                  | `$HOME`                          |
| `--store`         | Gandalf store directory                         | `~/.gandalf` or `$GANDALF_STORE` |
| `--agent`         | Target agent (`codex`, `claude-code`)           | (unfiltered)                     |
| `--scope`         | Scope (`user`, `project`, `managed`, `unknown`) | (unfiltered)                     |
| `--json`          | Emit JSON output                                | off                              |

`--dry-run` and `--apply` are mutually exclusive.

## Examples

### Preview

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

  ```bash Claude Code theme={null}
  gandalf restore --snapshot baseline-claude --dry-run --agent claude-code --scope user --project .
  ```
</CodeGroup>

### Apply after review

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

### Apply with automatic rollback on failure

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

## Plan output shape

The dry-run text preview prints:

* Snapshot name, target project, target home
* Writable change count and unsupported item count
* Risk summary (critical, high, medium, low, none)
* Per-item entries with kind, action, source path, risk, rollback instruction, and changed fields
* Unsupported items with reasons

Add `--json` for the full `RestorePlan` structure.

<Warning>
  `--apply` requires `--experimental` or `GANDALF_EXPERIMENTAL=1`. Without either, Gandalf returns `GANDALF_EXPERIMENTAL_REQUIRED` and does not write.
</Warning>

## Related

* [Review Changes](/concepts/review-changes)
* [Snapshot and restore guide](/guides/snapshot-and-restore)
* [Trust contract](/trust-contract)