CLI

The Chrome extension reviews GitHub pull requests. The CLI reviews a local branch, a commit, or your working tree with the same engine and walkthrough — before you open a PR, or when there isn’t one. It does not structure the walkthrough with AI until you ask. Choosing between hosts: Install.

Run it

Node.js 22 or newer:

npx @guided-review/cli

Pass flags after the command:

npx @guided-review/cli --base main --no-open

The published package is @guided-review/cli. The binary is guidedreview. npx guided-review (unscoped, hyphen) is a different package. From this repo: pnpm build:cli then pnpm review (flags after --).

The CLI binds 127.0.0.1:7182 (ASCII G+R), keeps a short terminal banner (URL, diff, last pull), and opens the UI unless you pass --no-open. Only real events (structure, scope change, errors) go to the log below. Override with --port. --port 0 picks any free port. Ctrl+C stops the server.

What it compares

The header shows the current branch and the base branch. A dropdown picks the diff:

• Branch vs base — committed work on this branch since it diverged from the base (git diff <merge-base> HEAD)
• Uncommitted — staged and unstaged work versus HEAD (untracked files included unless you passed --no-untracked)
• Unstaged — worktree versus the index only
• A specific commit — that commit’s patch

Default selected scope: the first non-empty of branch, uncommitted, unstaged, then the newest commit. --staged starts on index-only uncommitted work.

Base resolution, in order: --base → origin/HEAD → main → master.

If every scope is empty: Nothing to review against <base>. and exit 0. Not a git repo: an error that says what failed.

Follow the Walkthrough

The walkthrough starts one unit per file. Structure With AI on the Change summary card is the opt-in LLM call — same pipeline as the extension (How a review plan works). It groups files and adds context; it does not review for you.

Press d to open the scope dropdown, ⌘/Ctrl + I to structure, or ⌘/Ctrl + , for Settings — same keys as Keyboard shortcuts → Local review. Navigation, diff search, and comment mode share the extension shortcuts where they apply.

Unlike the extension, there is no GitHub submit from the CLI UI. Line notes stay in the session until you Generate Prompt or stop the server.

API keys

Same providers as the extension: Anthropic, OpenAI, Grok. Full setup (including borrowing a coding-agent subscription): Configure AI provider → CLI.

Resolution, in order:

1. --provider / --model / --agent and env (ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY or GROK_API_KEY)
2. A key already saved in ~/.config/guided-review/config.json
3. A coding agent already on this machine (Claude Code, Codex, or Grok)

If more than one agent has a usable key, the CLI asks which to use each run (Enter keeps the last choice). The chosen agent is shown in the browser UI. It reads the agent's own store at review time and does not copy the secret into Guided Review config.

No key still walks one unit per file. Structure With AI asks for a key.

The local UI has Settings (header, ⌘/Ctrl + ,, or Connect AI Provider when no key is set). Paste an API key, or turn on Use My Subscription to borrow Claude Code / Codex / Grok on this machine. A saved API key always wins. Subscription is unofficial and can break — a console key is the better option. Save writes the config file below. Flags and env still win for that run.

Config file

Saved prefs live at ~/.config/guided-review/config.json, or:

• $XDG_CONFIG_HOME/guided-review/config.json when XDG_CONFIG_HOME is set
• $GUIDED_REVIEW_CONFIG_DIR/config.json when that env var is set (wins over XDG / home)

Example shape (all fields optional — only what you saved appears):

{
  "provider": "anthropic",
  "model": "claude-opus-4-8",
  "apiKey": "sk-ant-…",
  "codingAgent": "claude-code"
}

Prefer editing through Settings in the UI. If you hand-edit the file, restart the CLI (or re-open Settings and save) so the running server picks up the change. Flags and env still override the file for that run. Clearing a key: remove apiKey from the file, or clear it in Settings — Privacy & data → Clear data.

Notes

Line comments stay in the session. There is no GitHub submit from the CLI. Generate Prompt builds a coding-agent prompt from those notes and copies it — Guided Review does not send it anywhere. Full walkthrough: Generate Prompt. On a GitHub PR, use the extension to draft and submit instead.

Flags

guidedreview [dir] --base main --port 8787 --no-open --staged --no-untracked --agent claude-code

Problems starting the server or structuring a plan: Troubleshooting → CLI.

Next. Chrome Extension · Configure AI provider · Generate Prompt · Reading the overlay · Keyboard shortcuts