---
title: CLI usage
description: Select a review target and control the local Diffsplain page.
sidebar:
  order: 2
---

## Current checkout

With no target, Diffsplain shows staged, unstaged, and untracked changes
against `HEAD`, the same as `--worktree`. Already committed changes are excluded.

```sh
npx diffsplain
```

## Pull requests

Use a pull request number in the current repo:

```sh
npx diffsplain --pr 198
```

Pass the repo when you run the command elsewhere:

```sh
npx diffsplain owner/repo --pr 198
npx diffsplain --repo https://github.com/owner/repo --pr 198
```

`owner/repo` is fetched over HTTPS. Diffsplain adds the signed-in GitHub CLI
as a Git credential helper for `https://github.com` remotes only; existing
helpers stay in place. `gh auth login` is enough. You do not need a separate
Git HTTPS password.

A full pull request URL carries the repo:

```sh
npx diffsplain --pr https://github.com/owner/repo/pull/198
```

## Branches

Compare a branch with the remote default branch:

```sh
npx diffsplain --branch feature/my-change
npx diffsplain owner/repo --branch feature/my-change
```

Choose a different base or remote when needed:

```sh
npx diffsplain \
  --repo /path/to/repo \
  --branch feature/my-change \
  --base next \
  --remote upstream
```

## Worktree changes

Use `--worktree` explicitly to select the default review of tracked and
untracked changes against `HEAD`:

```sh
npx diffsplain --worktree
```

The watcher refreshes the page as the worktree changes. It keeps notes for
files whose patches did not change and asks the agent only about new or changed
files.

## Base through the working tree

Pass `--base` without `--head` to compare that exact commit with the current
working tree. This includes later commits, staged changes, unstaged changes,
and untracked files:

```sh
npx diffsplain --base release-1
```

The page shows the short base ref followed by `working tree`. If the ref moves,
the watcher refreshes the review against its new commit.

## Exact local ranges

Pass two refs that exist in the chosen repo:

```sh
npx diffsplain \
  --repo /path/to/repo \
  --base BASE_REF \
  --head HEAD_REF
```

## Choose a default agent

Save one default coding agent for future reviews:

```sh
npx diffsplain config agent codex
```

Show or remove it later:

```sh
npx diffsplain config agent
npx diffsplain config agent --unset
```

Selection order is `--no-agent`, an explicit `--agent`, then the configured
default. The two per-run options cannot be combined. When none is present,
Diffsplain keeps the interactive picker. The configured default also works in
scripts and other non-interactive runs.

Diffsplain validates a configured agent just like an explicit choice. A
damaged preference, unsupported name, or unavailable agent stops the run; it
does not fall through to discovery or the picker. Use `--agent NAME` for a
one-run override or `--no-agent` for a plain review without reading the saved
preference.

## Agent checkout access

For the current checkout, `--worktree`, and `--base REF` without `--head`, a
selected agent uses `checkout-read-only` access. Its working folder is the
chosen repo, so it can inspect ignored files, Git history, and symlink targets
when the note needs them. Diffsplain tells it not to edit files or run mutating
commands. Diffsplain itself does not edit the review target. Agents run under
your user permissions, and approval stays with you.

Pull requests, remote branches, and exact local ranges use `snapshot-only`
access because their target may not match the live checkout. The agent gets the
temporary review input and must use only that input; it must not run commands
or read other files.

Pass `--no-checkout-access` to use `snapshot-only` access for any target. This
option limits both agent notes and Review chat. It does not change the diff.

## Exclude files from agent context

Pass `--exclude PATTERN` to keep matching files out of automatic agent input.
You can repeat it:

```sh
npx diffsplain \
  --exclude 'private/**' \
  --exclude '!private/keep.txt'
```

Rules use gitignore-style rules in the order you pass them. A later rule wins.
A rule that starts with `!` puts a path back in. Diffsplain matches the current
path of a renamed file, not its old path.

The local page and snapshot keep every changed file and its full patch. A
matching file gets `agentExcluded: true`. Its path, metadata, patch, snippet,
and old note stay out of automatic agent input. Diffsplain hides its cached
note while the file is excluded. It can reuse that note when the file returns
only if its patch still matches. If the patch changes while excluded,
Diffsplain drops that cached note. `--force` does not override an exclusion.

When all files are excluded, Diffsplain makes no agent request. The local page
still shows the diff and reports zero agent notes. Removing or changing rules
can show a matching cached note again when its patch has not changed.

This is prepared-context control, not a privacy boundary. It does not change
checkout access. A checkout-access agent can inspect files in the repo, so do
not use `--exclude` to hide secrets from an agent.

## Check your setup

Run the doctor command to see the separate local review, agent note, and pull
request lookup capabilities:

```sh
npx diffsplain doctor
```

The report lists every supported agent, even when it is not installed. It keeps
installation, compatibility, authentication, and smoke-test results separate.
Missing agents do not stop a plain local review with `--no-agent`.

Use JSON for setup checks in scripts or cloud jobs:

```sh
npx diffsplain doctor --json
```

The normal check does not send prompts to a provider. `--deep` runs local
`--help` checks for installed providers after a warning; it does not send a
provider prompt.

## Saved note cache

Inspect the default note cache, or remove inactive notes:

```sh
npx diffsplain cache
npx diffsplain cache status
npx diffsplain cache prune --age 30
npx diffsplain cache prune --size 104857600
npx diffsplain cache clear --yes
```

`cache` and `cache status` show the cache location, byte count, oldest entry,
and active targets. `prune --age DAYS` removes notes older than that many days.
`prune --size BYTES` removes the oldest notes first until the cache fits the
limit or only active notes remain. Pass one limit at a time; both accept
non-negative numbers. `clear` requires `--yes`. All cleanup keeps notes under
an active lease.

These commands manage the default user note cache. They do not remove fetched
Git objects or custom `--summaries` files outside that cache. `--cache-dir`
chooses the bare Git cache for reviews, not the note cache. See
[Agent notes](/agent-notes/#cache-control) for storage details.

## First run and shutdown

Run the setup check through `npx`, which installs the package if needed:

```sh
npx diffsplain doctor
```

You can instead run `npm install -g diffsplain` and then `diffsplain doctor`.
Use `--no-agent` for a plain local review when no coding agent is ready.

A normal review prints a local URL and tries to open it in your browser. If the
browser cannot open, open that URL yourself. The command keeps watching until
you press <kbd>Ctrl</kbd>+<kbd>C</kbd>. It then stops the watcher, local server,
and any active note process. Normal shutdown removes temporary page and agent
input files. Saved notes remain in the user cache. Fetched Git objects remain
in the installed package's `.cache/git` folder. See
[Agent notes](/agent-notes/) and [Diff data](/data/) for paths and cleanup.

## Run from source

The `diffsplain` package script accepts every public command and option:

```sh
pnpm run diffsplain -- --worktree
pnpm run diffsplain -- doctor
```

The doctor command also has a short package script:

```sh
pnpm run doctor
```

## Options

| Argument | Use |
| --- | --- |
| `doctor [--json] [--deep]` | Check local review, agent note, and pull request capabilities. |
| `cache [status\|prune --age DAYS\|prune --size BYTES\|clear --yes]` | Inspect or remove inactive saved notes. |
| `config agent [NAME\|--unset]` | Show, set, or unset the default coding agent. |
| `REPO`, `--repo PATH\|URL\|OWNER/REPO` | Select a local path, Git URL, or GitHub repo. |
| `--pr NUMBER\|URL` | Review a GitHub pull request. |
| `--branch NAME` | Compare a remote branch with its default branch. |
| `--worktree` | Review tracked and untracked changes against `HEAD`. |
| `--base REF` | Compare that exact commit with the live working tree. |
| `--base REF --head REF` | Review an exact local range. |
| `--agent NAME` | Use `codex`, `claude`, `copilot`, `cursor`, or `opencode`. |
| `--no-agent` | Show the diff without agent notes. |
| `--no-checkout-access` | Limit agent notes and Review chat to the supplied snapshot. |
| `--exclude PATTERN` | Keep matching files out of automatic agent input. Repeat in gitignore order. |
| `--model NAME` | Choose the model used for notes. |
| `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh`. |
| `--fast` | Enable provider Fast mode for agent notes and Review chat. |
| `--batch-size COUNT` | Set the most files per agent pass, from `1` to `50`. Large patches use smaller batches. |
| `--jobs COUNT` | Set agent passes to run at once, from `1` to `8`. |
| `--force` | Regenerate all agent notes instead of using cached notes. |
| `--support-record` | Print a safe JSON record if the review fails. |
| `--support-record-file FILE` | Write one safe JSON record if the review fails. |
| `--remote NAME\|URL` | Choose the Git remote. The default is `origin`. |
| `--summaries FILE` | Choose the saved agent-note file. |
| `--output FILE` | Choose the live snapshot file. |
| `--cache-dir PATH` | Choose the bare Git cache folder. |
| `--codex-bin PATH` | Choose the Codex executable. |
| `--port NUMBER` | Choose an exact local port. The default starts at `2299`. |
| `--host ADDRESS` | Choose the page bind address. The default is `localhost`. |
| `--no-browser` | Do not open the page in a browser. |
| `-h`, `--help` | Show command help. |
| `-v`, `--version` | Show the installed version. |

Remote repos need `--branch` or `--pr`. `--pr` cannot use `--branch`, `--base`,
or `--head`. `--branch` can use `--base`, but not `--head`.
`--head` requires `--base`. Without `--head`, local `--base` compares that
exact commit with the live working tree; a branch can also use `--base` as its
remote base. `--worktree` cannot use another target. `--no-agent` cannot use
`--summaries` or `--fast`. Paths passed to
`--repo`, `--summaries`, `--output`, `--cache-dir`, and `--codex-bin` resolve
from the current directory. `CODEX_BIN`, `CLAUDE_BIN`, `COPILOT_BIN`,
`CURSOR_BIN`, and `OPENCODE_BIN` can select provider binaries. Supported agents
accept `--model`. Only Codex and OpenCode accept `--reasoning`; its levels are
`minimal`, `low`, `medium`, `high`, and `xhigh`.

`--fast` is opt-in and supports Codex CLI 0.108.0 or newer and Claude Code
2.1.36 or newer. Diffsplain checks the selected executable before the first
agent call and stops for an older or unsupported provider. It passes the
provider's native Fast setting to every note and Review chat call without
changing the selected model or a global provider setting. Account, model, and
entitlement errors come from the provider.

`--batch-size` defaults to `12` and accepts `1` through `50`. `--jobs` defaults
to `3` and accepts `1` through `8`. `--port` accepts `0` through `65535`. When
you omit it, Diffsplain starts at `2299` and increments until it finds a free
port. An explicit occupied port stops the command; `--port 0` asks the OS for
a free port.

When you omit `--agent` and have no configured default in an interactive
terminal, Diffsplain lists the usable choices in this order: Codex, Claude,
Copilot, Cursor, then OpenCode. Choose one before the review starts. In a
script or other non-interactive run, configure a default, pass `--agent NAME`,
or use `--no-agent`. Cursor Agent needs version 2026.08.11 or newer. Note
batches run in Ask mode with the user's Cursor login and home. Diffsplain
passes `--trust` and `--workspace` for its snapshot directory. Cursor still
contacts its own service.
`--agent cursor` reports an upgrade or flag error before note generation when
the CLI is too old or missing required flags. Once Diffsplain chooses an
agent, a failed check or run ends the command; Diffsplain does not switch
agents.

For `checkout-read-only` access, agents run with the chosen repo as their
working folder and their normal user settings. Diffsplain keeps approval with
you. Copilot and OpenCode do not have a proven native read-only mode, so
Diffsplain warns before either uses checkout access. See [Agent
notes](/agent-notes/) for the provider details.

The two support record options are opt-in and cannot be combined. They include
the selected agent, so you cannot use them with `--no-agent`. See
[Agent notes](/agent-notes#failed-run-support-records) for the data contract.