CLI Commands

Complete command-line interface reference for React Doctor

Basic Usage

Run React Doctor in your project directory:

npx react-doctor@latest

Scan a specific directory:

npx react-doctor@latest ./my-project

Commands

Main Command

The main command scans your React codebase for issues.

react-doctor [directory] [options]

directory · string · default: "."

Project directory to scan

Fix Command

Open Ami to automatically fix detected issues.

react-doctor fix [directory]

Install Ami Command

Install Ami and open it to fix issues.

react-doctor install-ami [directory]

Options

Linting Options

--lint · boolean · default: "true"

Enable linting checks using oxlint

--no-lint · boolean

Skip linting checks

Example:

npx react-doctor --no-lint

Dead Code Detection

--dead-code · boolean · default: "true"

Enable dead code detection using Knip

--no-dead-code · boolean

Skip dead code detection

Example:

npx react-doctor --no-dead-code

Output Options

--verbose · boolean · default: "false"

Show file details per rule, including line numbers for each diagnostic

--score · boolean · default: "false"

Output only the score (0-100) without diagnostics

Examples:

# Show detailed file information
npx react-doctor --verbose

# Get just the score
npx react-doctor --score

Project Selection

--project · string

Select workspace project(s) to scan. Comma-separated for multiple projects.

-y, --yes · boolean · default: "false"

Skip prompts and scan all workspace projects

Examples:

# Scan a specific project in a monorepo
npx react-doctor --project web

# Scan multiple projects
npx react-doctor --project web,mobile

# Skip all prompts
npx react-doctor -y

Diff Mode

--diff [base] · boolean | string

Scan only files changed vs base branch. If no base branch is specified, compares against uncommitted changes or the default base branch.

Examples:

# Scan only changed files vs main
npx react-doctor --diff main

# Auto-detect changes
npx react-doctor --diff

Diff mode automatically disables dead code detection since it requires a full codebase scan.

Error Handling

--fail-on · string · default: "none"

Exit with error code on diagnostics. Valid values: error, warning, none

Examples:

# Fail only on errors
npx react-doctor --fail-on error

# Fail on warnings and errors
npx react-doctor --fail-on warning

# Never fail (useful for CI reporting)
npx react-doctor --fail-on none

Telemetry

--offline · boolean · default: "false"

Skip telemetry. Telemetry is anonymous, not stored, and only used to calculate your health score.

Example:

npx react-doctor --offline

Ami Integration

--fix · boolean · default: "false"

Open Ami to auto-fix all detected issues

--no-ami · boolean · default: "false"

Skip Ami-related prompts

Examples:

# Scan and immediately open Ami to fix
npx react-doctor --fix

# Disable Ami prompts in CI
npx react-doctor --no-ami

Version

-v, --version · boolean

Display the version number

Example:

react-doctor --version

Common Workflows

Quick Scan

# Basic scan with default settings
npx react-doctor@latest

# Non-interactive mode with error exit codes
npx react-doctor --fail-on error -y --no-ami

# Scan only changed files
npx react-doctor --diff main --verbose

# Scan specific workspace projects
npx react-doctor --project api,web --verbose

# Skip dead code detection for faster scans
npx react-doctor --no-dead-code

# Just get the health score
npx react-doctor --score

Exit Codes

React Doctor uses exit codes to indicate scan results:

• 0: Success (or no failures based on --fail-on setting)
• 1: Diagnostics detected that match the --fail-on level

Example CI usage:

npx react-doctor --fail-on error
if [ $? -eq 0 ]; then
  echo "No errors found"
else
  echo "Errors detected, failing build"
  exit 1
fi

Environment Variables

React Doctor detects automated environments and adjusts behavior accordingly:

• CI: Continuous Integration
• CLAUDECODE: Claude Code
• CURSOR_AGENT: Cursor Agent
• OPENCODE: OpenCode
• AMI: Ami environment

When these are set, React Doctor:

• Skips interactive prompts
• Scans all workspace projects automatically
• Disables Ami installation prompts

Output

Standard Output

A typical scan produces:

1. Project Detection: Framework, React version, TypeScript/JavaScript
2. Diagnostics: Grouped by rule with severity, message, and help text
3. Summary: Health score, error/warning counts, affected files
4. Full Report: Diagnostics written to /tmp/react-doctor-{uuid}/

Verbose Output

With --verbose, each diagnostic includes:

• File paths
• Line numbers for each occurrence
• Detailed context

Example:

  ✗ useEffect dependencies array is missing dependencies (2)
    Ensure all dependencies are included in the array
    src/components/Header.tsx: 45, 67
    src/pages/Dashboard.tsx: 123

Score-Only Output

With --score, outputs a single number (0-100):

$ npx react-doctor --score
87