CLI reference

Run React Doctor from the command line:

react-doctor [directory] [options]

If directory is omitted, React Doctor scans the current directory.

Common commands

npx react-doctor@latest
npx react-doctor@latest --verbose --diff
npx react-doctor@latest --category performance --json
npx react-doctor@latest install
npx react-doctor@latest install --agent-hooks

Options

Option	Description
`-v, --version`	Print the installed version
`--no-lint`	Skip lint diagnostics
`--verbose`	Show every rule and per-file details
`--score`	Output only the numeric score
`--json`	Output a structured JSON report
`--category <category>`	Show findings from one diagnostic category. Repeat the flag to include more categories
`--json-compact`	Emit compact JSON with `--json`
`-y, --yes`	Skip prompts
`--project <name>`	Select projects to scan, comma-separated. Accepts workspace package names or directory paths; `*` selects every workspace project
`--diff [base]`	Scan files changed against a base branch. Use `--diff false` to force a full scan
`--no-score`	Skip the score API, share URL, and crash reporting
`--staged`	Scan staged files for pre-commit hooks
`--blocking <level>`	Severity that fails CI: `error` (default), `warning`, or `none` (advisory)
`--no-respect-inline-disables`	Audit mode for inline disables

Multi-project scans

Use --project to score each project in a monorepo separately. Each entry resolves as a workspace package name first, then as a directory path relative to the scan root:

npx react-doctor@latest --project modules/billing,modules/payroll

Directory paths cover monorepos whose modules are not workspace packages. --project "*" selects every discovered workspace project. Unknown entries fail the run before scanning starts.

Each project scans with its own doctor.config.* layered onto the root config: rules and categories merge per key, and ignore lists union. A module can override one rule without discarding the shared base config.

Output shows one score line per project plus a worst-of aggregate. JSON reports list each project in the projects array.

To score the same projects on every run without passing the flag, set projects in the root config file. An explicit --project flag overrides the config list.

Install command

npx react-doctor install [options]

Interactive setup asks about GitHub Actions first. It then installs the /react-doctor skill for selected coding agents and offers optional local hooks.

Option	Description
`-y, --yes`	Skip prompts, install the skill for all detected agents, add or update the GitHub Actions workflow, and add the Git hook when detected
`--dry-run`	Show what would be installed
`--agent-hooks`	Install native Claude Code and Cursor hooks
`--cwd <cwd>`	Project root for install

JSON output

Use --json when another tool needs to parse the scan:

npx react-doctor@latest --json

Human-readable output is suppressed. Errors still produce JSON with ok: false, so stdout remains parseable.

Use --category when you want a report for one part of the diagnostic set:

npx react-doctor@latest --json --category performance

Repeat --category to include more than one category:

npx react-doctor@latest --category performance --category accessibility

Category filters narrow normal output, verbose output, workspace summaries, handoff prompts, and JSON reports. They do not change which files React Doctor scans. Unknown categories fail before report output.

Explain a diagnostic

Use the why subcommand when a diagnostic or suppression is confusing:

npx react-doctor@latest why src/App.tsx:42

The output reports what React Doctor sees at that location and why a nearby suppression did or didn't apply.

To learn what a rule means in general, use rules explain:

npx react-doctor@latest rules explain react-doctor/no-array-index-as-key