> ## Documentation Index
> Fetch the complete documentation index at: https://reikon.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Every rei flag, output format, exit code, and config option.

# CLI Reference

`rei` is Reikon's headless CLI — same analyzers as the desktop app, runnable from a
terminal or CI pipeline with no UI. Published to npm as
[`@reikondev/cli`](https://www.npmjs.com/package/@reikondev/cli).

For installation steps, see the [CLI install guide](../guides/cli-install). This page
is the flag/exit-code/config reference.

```
Usage: rei <command> [options]
```

## Commands

| Command   | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| `analyze` | Analyze a git repository                                                                        |
| `review`  | Work the review loop in the terminal — list flags, reply, resolve, request a fix, send one back |
| `status`  | The dispatch ledger — what's in flight (returned / out / goals) across your repos               |
| `mcp`     | Run the Reikon MCP server over stdio (for coding agents)                                        |

## Review loop

`rei review` is the loop's **read + act** surface in the terminal. It reads and mutates the *same*
review state as the desktop app and the MCP server, so a reply you make in the terminal shows up
in the desktop Review tab, and vice versa.

| Subcommand                           | Description                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `rei review`                         | List in-flight flags + threads (add `--format json` for agents/CI)                               |
| `rei review reply <id> <text>`       | Reply on a flag's thread                                                                         |
| `rei review resolve <id>`            | Mark a flag resolved                                                                             |
| `rei review request-fix <id>`        | Request a fix — the connected agent picks it up over MCP and calls `mark_fix_returned` when done |
| `rei review send-back <id> <reason>` | Reject a returned fix with a reason; it goes back to `fix-requested` so the agent iterates       |
| `rei review --watch`                 | Live stream of flag/return status changes                                                        |

Authoring goals and the visual substrate (ownership maps, hotspot charts) stay in the desktop app;
the CLI reads and acts on the loop.

## Dispatch ledger

`rei status` is the terminal form of the desktop dispatch ledger — a glanceable "what's in flight"
across every repo you've analyzed. It's the `git status` of the dispatch loop.

```bash theme={null}
rei status
rei status --watch      # re-print on every change
```

It reports, per repo:

* **returned** — fixes an agent has sent back (`fix-returned`), waiting for you to verify
* **out** — notes still with the agent (`fix-requested`)
* **open** — open flags not yet acted on
* **goals** — the current repo's active dispatched goals

Notes are **cross-repo for free** — the annotation store keys by repo path, so `rei status` sums
every repo you've analyzed and marks the current one, with a cross-repo total. Dispatched goals
are shown for the current repo only. With nothing in flight anywhere, it prints
*"Nothing in flight — the dispatch loop is quiet."*

## Options

| Flag         | Short | Argument                      | Description                                                                           |
| ------------ | ----- | ----------------------------- | ------------------------------------------------------------------------------------- |
| `--path`     | `-p`  | `<dir>`                       | Path to the git repository (default: `.`)                                             |
| `--format`   | `-f`  | `json` \| `html` \| `summary` | Output format (default: `summary`)                                                    |
| `--output`   | `-o`  | `<file>`                      | Output file. Defaults to stdout for `json`/`summary`, `reikon-report.html` for `html` |
| `--quiet`    | `-q`  | —                             | Suppress progress output to stderr                                                    |
| `--no-cache` | —     | —                             | Skip the cache, force a fresh analysis                                                |
| `--watch`    | `-w`  | —                             | Re-run on every new commit (watches the repo's `logs/HEAD`, worktree-aware)           |
| `--version`  | `-v`  | —                             | Show version                                                                          |
| `--help`     | `-h`  | —                             | Show help                                                                             |

## Output formats

* **`summary`** *(default)* — colored terminal output with a ✓/⚠/✗ status icon per
  signal. Respects `NO_COLOR` and non-TTY output (colors auto-disable when piped).
* **`json`** — the full `AnalysisResult` object, same shape the desktop app consumes.
  Pipe it into `jq` or any other JSON tool.
* **`html`** — the same self-contained HTML report the desktop app's Export button
  produces (inline CSS + SVG charts, no external dependencies).

## Exit codes

| Code | Meaning                                                               |
| ---- | --------------------------------------------------------------------- |
| `0`  | Health score meets or exceeds the warn threshold                      |
| `1`  | Health score below the warn threshold — warnings                      |
| `2`  | Health score below the fail threshold, or the analysis itself errored |

Designed to gate a CI step directly — see the
[CI integration guide](../guides/cli-ci-integration).

## Config

`rei` reads `.reikon/config.json` exactly as the desktop app does — `ignorePaths`,
`teams`, `aliases`, `assignments`, `fileTypeGroups`, `inactiveAuthors`, and
`hiddenExtensions` all apply the same way. See the full
[config reference](./config-schema).

One CLI-only addition, nested under a `cli` key:

```json theme={null}
{
  "cli": {
    "warnBelow": 70,
    "failBelow": 50
  }
}
```

`warnBelow` and `failBelow` control the exit-code thresholds above. Defaults are 70 and
50 if the key is absent.

## Caching

Results are cached in `~/.reikon/cache/`, keyed by repo path + current HEAD hash + a
hash of `.reikon/config.json`'s content — changing the config invalidates the cache the
same way a new commit does. Pass `--no-cache` to force a fresh run regardless.

## Watch mode

```bash theme={null}
rei analyze --watch
```

Re-runs analysis after every new commit, debounced \~1.5s. It watches the repository's
commit log directly rather than the working tree, so it won't re-trigger on every
unsaved file edit — only on actual commits. Safe inside a `git worktree` checkout.

## `rei mcp`

```bash theme={null}
rei mcp
```

Hosts Reikon's MCP server over stdio, scoped to the git repo `rei` was launched in.
Use this to give a coding agent (Claude Code, Cursor, Windsurf, any MCP client) the
same project context the desktop app exposes — health score, complexity hotspots, diff
review, annotations — with **no desktop app installed**.

Register it with your agent the same way as any other stdio MCP server. For Claude
Code:

```bash theme={null}
claude mcp add reikon -- rei mcp
```

For Cursor, Windsurf, or any other MCP client, point `command` at `rei` with
`"args": ["mcp"]`:

```json theme={null}
{
  "mcpServers": {
    "reikon": { "command": "rei", "args": ["mcp"] }
  }
}
```

The command takes no flags — it reads no arguments, accepts JSON-RPC on stdin, writes
responses on stdout, and logs to stderr. It runs until the client closes the stream.

**Warming the context.** Run `rei analyze` in the repo first so context-dependent tools
(`get_project_health`, `get_complexity_hotspots`, …) answer instantly. If you skip it,
the first such call returns a short "run `rei analyze`" hint and warms the cache in the
background — a retry shortly after succeeds. Diff and annotation tools
(`get_annotated_diff`, `list_annotations`, `add_annotation_comment`, …) work
immediately either way, since they read live git and your annotation file.

**Shared state.** The CLI-hosted server and the desktop app read and write the same
on-disk state (under `<appData>/reikon`), so annotations stay in sync between them.

See [Run MCP Without the Desktop App](../guides/mcp-cli) for the full walkthrough, or
the [MCP tool reference](./mcp-tools) for what each tool returns.