# CLI reference

Run React Doctor from the command line:

```bash
react-doctor [directory] [options]
```

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

## Common commands

```bash
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

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

## 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:

```bash
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](/docs/configuration/config-files). An explicit `--project` flag overrides the config list.

## Install command

```bash
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.

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>-y, --yes</code>
      </td>
      <td>
        Skip prompts, install the skill for all detected agents, add or update
        the GitHub Actions workflow, and add the Git hook when detected
      </td>
    </tr>
    <tr>
      <td>
        <code>--dry-run</code>
      </td>
      <td>Show what would be installed</td>
    </tr>
    <tr>
      <td>
        <code>--agent-hooks</code>
      </td>
      <td>Install native Claude Code and Cursor hooks</td>
    </tr>
    <tr>
      <td>
        <code>--cwd &lt;cwd&gt;</code>
      </td>
      <td>Project root for install</td>
    </tr>
  </tbody>
</table>

## JSON output

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

```bash
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:

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

Repeat `--category` to include more than one category:

```bash
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:

```bash
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`:

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