Skip to main content

​
Command Syntax

npx react-doctor@latest [directory] [options]

​
Arguments

​
directory
string
default:"."
Project directory to scan. Defaults to the current directory.

​
Options

​
Scan Configuration

​
--lint
boolean
default:"true"
Enable linting checks. Can be overridden in config file.
​
--no-lint
boolean
Skip linting checks.
​
--dead-code
boolean
default:"true"
Enable dead code detection using Knip.
​
--no-dead-code
boolean
Skip dead code detection.
​
--verbose
boolean
default:"false"
Show file details per rule in the output.

​
Output Options

​
--score
boolean
default:"false"
Output only the score without diagnostic details.
​
--offline
boolean
default:"false"
Skip telemetry (anonymous, not stored, only used to calculate score).

​
Project Selection

​
--project
string
Select workspace project(s). Use comma-separated values for multiple projects.
npx react-doctor --project=app,web
​
-y, --yes
boolean
default:"false"
Skip prompts and scan all workspace projects automatically.

​
Differential Scanning

​
--diff
boolean | string
Scan only files changed vs base branch. If a branch name is provided, uses that as the base branch.
# Compare against default base branch
npx react-doctor --diff

# Compare against specific branch
npx react-doctor --diff=main

​
Error Handling

​
--fail-on
'error' | 'warning' | 'none'
default:"none"
Exit with non-zero code based on diagnostic severity:
  • error: Exit with code 1 if any errors are found
  • warning: Exit with code 1 if any warnings or errors are found
  • none: Always exit with code 0

​
Auto-fix

​
--fix
boolean
default:"false"
Open Ami to automatically fix all issues.
​
--no-ami
boolean
Skip Ami-related prompts.

​
Information

​
-v, --version
boolean
Display the version number.
​
-h, --help
boolean
Display help information.

​
Subcommands

​
fix

Open Ami to auto-fix react-doctor issues. 
npx react-doctor fix [directory]
​
directory
string
default:"."
Project directory. Defaults to current directory.

​
install-ami

Install Ami and open it to auto-fix issues. 
npx react-doctor install-ami [directory]
​
directory
string
default:"."
Project directory. Defaults to current directory.

​
Exit Codes

​
0
Success
Scan completed successfully (or no failures based on --fail-on setting).
​
1
Failure
Diagnostic issues found that match the --fail-on severity level.

​
Environment Variables

React Doctor detects automated environments and adjusts behavior accordingly. The following environment variables indicate an automated environment:
  • CI - Continuous Integration environment
  • CLAUDECODE - Claude Code environment
  • CURSOR_AGENT - Cursor Agent environment
  • CODEX_CI - Codex CI environment
  • OPENCODE - OpenCode environment
  • AMP_HOME - Amp environment
  • AMI - Ami environment
When an automated environment is detected:
  • Prompts are automatically skipped (equivalent to --yes)
  • TTY checks are bypassed

​
Examples

​
Basic scan

npx react-doctor@latest

​
Scan specific directory with verbose output

npx react-doctor ./packages/app --verbose

​
Scan only changed files

npx react-doctor --diff

​
Run in CI with fail on errors

npx react-doctor --fail-on=error --yes --no-ami

​
Skip dead code analysis

npx react-doctor --no-dead-code

​
Scan multiple workspace projects

npx react-doctor --project=app,web --verbose

​
Open Ami to fix issues

npx react-doctor --fix

Build docs developers (and LLMs) love

Get started for freeTalk to us