CLI Reference

Complete command-line interface reference for React Doctor

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