CLI reference

Every WhyGraph command and its flags. Run whygraph <command> --help to see the same text from your own install. There are six commands.

$ whygraph --help
Commands:
  analyze  Describe a commit's diff with the configured LLM.
  init     Initialize the WhyGraph database under .whygraph/whygraph.db.
  scan     Run the source crawlers, then describe each commit with the LLM.
  serve    Serve the WhyGraph Explorer panel for this repository.
  version  Print installed whygraph version.

whygraph version

Print the installed package version. No options.

whygraph version

whygraph init

Bootstrap the WhyGraph database under .whygraph/whygraph.db, write a committable whygraph.example.toml documenting every tunable, and add the right .gitignore entries. It's idempotent - re-running on an initialized project just confirms both databases are present.

On a terminal, init runs a guided, arrow-key setup: pick the agent, the analyze/rationale LLMs (with optional API keys), and the source-control provider (with an optional GitHub token). It shows a summary that masks every secret, asks "Write these files?", then writes both whygraph.example.toml (secret-free) and a ready-to-run whygraph.toml (with the secrets you entered). Every prompt is defaulted. --yes (and any non-TTY invocation) skips the prompts, uses defaults, and never clobbers an existing whygraph.toml.

init also installs the auto-rescan git hooks and reconciles them to [scan].hooks in both directions - installing what the config lists and stripping the managed block from what it doesn't. Editing [scan].hooks and re-running whygraph init is the supported way to change hook coverage; see Keep it fresh. A hooks directory that can't be written is a warning, never a failed init.

init does not index CodeGraph. That happens on scan.

With --agent X, it also wires the WhyGraph MCP server into that agent's config. All supported agents are project-scoped, so the config file is written inside the repo.

Option	Description
--agent [claude\|codex\|copilot\|cursor\|vscode]	Wire the MCP server into the named agent's config. On a terminal, skips the interactive agent prompt. Run whygraph init --help for the full list of supported agents.
--yes / -y	Accept all defaults without prompting (also implied off a TTY). Writes a default whygraph.toml only if none exists.
--force	When installing assets, overwrite existing files in the agent's destination directory.

Preflight diagnostics and asset install both always run — the chosen agent's bundled assets are copied into the repo automatically (use --force to overwrite local edits).

See Wiring your editor for the per-agent paths.

whygraph scan

Run the source crawlers, then describe each commit with the configured LLM. This is the command that populates .whygraph/whygraph.db and refreshes the CodeGraph index. It's idempotent - re-running picks up new commits and backfills what's missing.

Option	Default	Description
--skip-analyze	off	Skip the per-commit LLM description phase. The git and GitHub crawlers still run; descriptions backfill lazily on demand and on a later full scan.
--codegraph / --no-codegraph	on	Refresh the CodeGraph index concurrently with the crawl - codegraph sync when an index exists, codegraph init -i on first run. A failure here warns rather than aborting.
--codegraph-image TEXT	pinned tag	Override the Docker image used for the CodeGraph refresh fallback. Ignored when a local codegraph binary is found.
--remote / --no-remote	on	Crawl the source-control remote (GitHub PRs / issues) per [scan].provider. --no-remote skips it for a fast, offline, token-free scan.
--pr-origins / --no-pr-origins	on	Recover a squash-merged PR's original feature-branch commits via one targeted git fetch. Needs the network, so it's skipped under --no-remote.

See Scanning your repo for what each phase does.

whygraph serve

Serve the read-only Explorer playground for this repository - a local web panel over the code graph, evidence, and rationale. On the Docker install it runs as its own long-lived container, published to 127.0.0.1 only. Run whygraph scan first so there's an index and evidence to show.

Option	Default	Description
--port	8765	Port to bind. On the Docker install, set the port via the WHYGRAPH_PORT environment variable instead (the shim controls both the published and in-container port).
--host	127.0.0.1	Bind address. The Docker shim passes 0.0.0.0 for the container so the loopback port-forward can reach it; you rarely set this by hand.

On the Docker install the shim also adds container-lifecycle verbs - these are not flags of the Python command, they're handled on the host before the container starts:

Command	What it does
whygraph serve --detach	Start in the background and return immediately.
whygraph serve --logs	Tail the detached server's logs.
whygraph serve --stop	Stop and remove the running server.

See The Explorer playground for the panel itself.

whygraph analyze

Describe a single commit's diff with the configured LLM and print the result. Unlike scan, it doesn't persist anything.

whygraph analyze <TARGET> [BASELINE]

TARGET is the commit being analyzed. With no BASELINE, it's compared to its parent; with a BASELINE, the diff analyzed is git diff BASELINE..TARGET.

Scan first

Every commit named on the command line must already exist in the WhyGraph database. Run whygraph scan before whygraph analyze.