CLI reference

Run React Doctor from the command line:

react-doctor [paths...] [options]

Pass one project directory or a list of source file paths. With no paths, React Doctor scans the current directory.

Common commands

npx react-doctor@latest
npx react-doctor@latest --verbose --scope changed
npx react-doctor@latest --category Security --json
npx react-doctor@latest ci install
npx react-doctor@latest rules list
npx react-doctor@latest install

Options

Option	Description
`-v, --version`	Print the installed version
`--lint, --no-lint`	Skip lint diagnostics
`--supply-chain, --no-supply-chain`	Enable or skip Socket.dev dependency checks
`--verbose`	Show every rule and per-file details
`--debug`	Print the Sentry trace ID for a bug report
`--output-dir <dir>`	Write the full diagnostics dump to a directory
`--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`
`--json-out <path>`	With `--json`, write the report to a file
`-y, --yes`	Skip prompts and scan all detected workspace projects
`--no-parallel`	Lint serially with one worker
`--project <name>`	Select projects to scan, comma-separated. Accepts workspace package names or directory paths; `*` selects every workspace project
`--scope <value>`	Choose `full`, `files`, `changed`, or `lines`
`--base <ref>`	Set the base ref for files, changed, or lines scope
`--include-untracked`	Include ordinary untracked files in a partial scope, respecting `.gitignore`
`--no-score`	Skip the score API, share URL, and crash reporting. React Doctor also accepts `--no-telemetry`
`--staged`	Scan staged files for pre-commit hooks
`--blocking <level>`	Severity that fails CI: `error` (default), `warning`, or `none` (advisory)
`--warning-exit-code <code>`	Exit with a code from 2 to 255 for non-blocking warnings. See the GitLab warning status example for settings that override this code
`--max-duration <seconds>`	Set a time budget and report partial results when it expires
`--no-respect-inline-disables`	Audit mode for inline disables
`--warnings, --no-warnings`	Show or hide warning-severity diagnostics
`--color, --no-color`	Force or disable colored output

Scan scopes

Choose one scan scope with --scope:

full: scan the entire project and report every finding
files: scan changed files and report every finding in them
changed: compare with the base and report only introduced findings
lines: report findings whose source range touches a changed line

The default is full. React Doctor detects the base ref for partial scopes. Pass --base main when you need a specific ref. The older --diff flag still works as a deprecated alias for --scope changed.

Maintainability analysis compares repeated JSX against the full source corpus in every scope. Partial scopes report only findings connected to the selected files or changed lines.

Scan selected files

Pass file paths to scan only the files that another CI step selected:

npx react-doctor@latest src/a.tsx src/b.tsx

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 installs the /react-doctor skill for selected coding agents and offers optional local hooks. Manage CI separately with react-doctor ci.

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

CI commands

Use the ci command group to manage a GitHub Actions workflow or GitLab CI scaffold:

npx react-doctor@latest ci install
npx react-doctor@latest ci config
npx react-doctor@latest ci upgrade

ci install accepts --provider, --pr, --blocking, --scope, reporting toggles, --yes, and --cwd. ci config accepts the same settings except --pr. ci upgrade accepts --provider, --pr, --yes, and --cwd.

Reporting toggles are --comment, --review-comments, and --commit-status, with a --no-* form for each one. GitHub Actions supports every toggle. GitLab CI produces a gate-only scaffold.

Rules commands

Inspect and configure the effective rule set:

npx react-doctor@latest rules list
npx react-doctor@latest rules explain react-doctor/no-array-index-as-key
npx react-doctor@latest rules set react-doctor/no-array-index-as-key error
npx react-doctor@latest rules disable react-doctor/no-danger
npx react-doctor@latest rules enable react-doctor/no-danger
npx react-doctor@latest rules category Performance warn
npx react-doctor@latest rules ignore-tag design
npx react-doctor@latest rules unignore-tag design

Filter rules list with --category, --tag, --framework, or --configured. Add --json to rules list or rules explain for structured output. Every rules subcommand accepts --cwd.

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

Runtime performance traces

Record a Chrome DevTools performance trace while you interact with a running React app:

npx react-doctor@latest scan http://localhost:3000

React Doctor opens the installed Chrome browser in a separate, temporary profile. It records until you press Enter or five minutes pass. Purple outlines show component names as React renders.

The command returns a summary and the path to a compressed DevTools trace. Use --format json or --format jsonl for coding agents.

In an interactive terminal, you can run react-doctor scan without a URL. Select a detected localhost app or enter another URL. Coding agents and CI must pass the URL explicitly.

Use an authenticated session

React Doctor leaves your existing browser session unchanged. To reuse an authenticated session:

Start a dedicated Chrome profile with remote debugging.
Sign in to the app.
Close all non-blank tabs in that profile.
Pass its endpoint with --cdp:

npx react-doctor@latest scan https://app.example.com --cdp http://127.0.0.1:9222

Chrome performance tracing covers all pages in the browser. React Doctor rejects attached profiles with open pages and closes blank startup tabs before tracing. After tracing, it closes its scan tab and leaves the attached browser open.

React Doctor stores the trace locally and never uploads it. It can contain page URLs, source paths, and React profiling details. Treat it as sensitive application data.