> ## 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 CLI reference overview

> Overview of all gandalf subcommands, common flags, and the TUI entry point. Use this page as your map to the complete local AI agent control console.

Gandalf is a Go CLI and Bubble Tea TUI that acts as a local control console for AI agent setup across Codex and Claude Code. It inspects installed skills, hooks, MCP servers, and plugins, browses agent-native marketplace and source entries, and applies only reviewed provider-backed changes.

This page lists every top-level command, the common flags available on most commands, and how to open the interactive setup console.

## Commands

| Command                    | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `gandalf` or `gandalf tui` | Open the interactive setup console (see below).                      |
| `gandalf init`             | Create `gandalf.toml` and `.gandalf/skills/` in the project.         |
| `gandalf scan`             | Read-only discovery of local agent configuration.                    |
| `gandalf check`            | Detect drift between `gandalf.toml` and the local setup.             |
| `gandalf apply`            | Sync a team manifest to the local agent setup.                       |
| `gandalf snapshot`         | Create, list, and show named configuration snapshots.                |
| `gandalf diff`             | Compare two snapshot refs (or `current`).                            |
| `gandalf restore`          | Restore a saved snapshot, with mandatory preview and optional apply. |
| `gandalf bundle`           | Export, import, inspect, and verify portable configuration bundles.  |
| `gandalf timeline`         | List, show, and preview undo operations on the setup history.        |
| `gandalf doctor`           | Run a readiness report for setup portability.                        |
| `gandalf report`           | Generate a markdown report for a snapshot or the current state.      |

## The TUI entry point

Running `gandalf` with no arguments opens the interactive **setup console**:

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

This is equivalent to:

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

The setup console presents five top tabs:

* **Home**: Dashboard and quick navigation
* **Console**: Interactive workspace for managing configuration
* **Changes**: Review Changes before any mutation
* **Timeline**: Browse history and undo candidates
* **Saves**: Manage saved snapshots

The **Console** tab contains five sub-tabs:

* Hooks
* Plugins
* Marketplace
* Skills
* MCP Servers

## Common flags

Most `gandalf` commands accept the following flags, and some accept additional command-specific flags.

| Flag              | Description                                     | Default                            |
| ----------------- | ----------------------------------------------- | ---------------------------------- |
| `-p`, `--project` | Project path                                    | `.`                                |
| `--home`          | Home directory path                             | `$HOME`                            |
| `--store`         | Gandalf data directory                          | `~/.gandalf` (or `$GANDALF_STORE`) |
| `--agent`         | Target agent (`codex`, `claude-code`)           | (none)                             |
| `--scope`         | Scope (`user`, `project`, `managed`, `unknown`) | (none)                             |
| `--json`          | Emit output as JSON                             | (disabled)                         |

<Note>
  You can override the default store directory with the `$GANDALF_STORE` environment variable or the `--store` flag.
</Note>

## Quick navigation

<CardGroup cols={3}>
  <Card title="scan" href="/cli/scan">
    Read-only discovery
  </Card>

  <Card title="snapshot" href="/cli/snapshot">
    Save and inspect snapshots
  </Card>

  <Card title="diff" href="/cli/diff">
    Compare two refs
  </Card>

  <Card title="restore" href="/cli/restore">
    Restore from a snapshot
  </Card>

  <Card title="bundle" href="/cli/bundle">
    Export and import bundles
  </Card>

  <Card title="timeline" href="/cli/timeline">
    Browse history and undo
  </Card>

  <Card title="tui" href="/cli/tui">
    Interactive setup console
  </Card>

  <Card title="init" href="/cli/init">
    Initialize a project
  </Card>

  <Card title="check" href="/cli/check">
    Detect drift
  </Card>

  <Card title="apply" href="/cli/apply">
    Sync a manifest
  </Card>

  <Card title="doctor" href="/cli/doctor">
    Portability readiness
  </Card>

  <Card title="report" href="/cli/report">
    Markdown reports
  </Card>
</CardGroup>