feat(cli): align CLI with clig.dev and 12-factor guidelines

[rayhanadev]

Why

Bring the react-doctor CLI in line with the clig.dev and 12-factor CLI Apps guidelines. Three concrete gaps:

1. help was broken — react-doctor help tried to scan a directory named help and errored.
2. No color control — picocolors auto-detected NO_COLOR/TTY, but there was no --color/--no-color override or app-specific env toggle.
3. Thin version surface + example-less help — only terse -v/--version; no version subcommand, no -V, and --help had zero examples (clig.dev's top Help guideline is "lead with examples").

Before:

$ react-doctor help
Something went wrong…
No React project found in /…/help. Expected a package.json…

$ react-doctor --no-color    # silently stripped, no effect
$ react-doctor version       # tried to scan ./version

After:

$ react-doctor help                 # root help
$ react-doctor help install         # install help
$ react-doctor --no-color           # disables color across all output
$ react-doctor version
react-doctor/0.2.14 darwin-arm64 node-v24.14.0
$ react-doctor -V
0.2.14

What changed

• Color control — --color / --no-color flags plus app-specific REACT_DOCTOR_NO_COLOR / REACT_DOCTOR_FORCE_COLOR env vars, resolved before Commander parses so the choice reaches every surface (scan report, branded header, score, prompts, errors). Flags win over env vars, which win over picocolors' built-in NO_COLOR/FORCE_COLOR/TERM/TTY detection. Backed by a new @react-doctor/core setColorEnabled() toggle.
• Examples-led help — root and install --help now open with aligned Examples: blocks and a "Feedback & bug reports" link (rendered lazily so they honor the color preference).
• version subcommand + -V — react-doctor version prints version + Node + platform for debugging; -v / -V / --version stay terse for scripts.
• help / help <command> — normalized in the bootstrap to the existing --help paths instead of being swallowed by the default scan action.
• Allowed the new flags through the pre-parse flag stripper and consolidated the shared NODE_ARGUMENT_COUNT argv constant into constants.ts.

Eval results

Not applicable — this is a CLI/UX change, not a lint rule, so the RDE rule-eval harness was not run.

Test plan

• react-doctor suite green — pnpm --filter react-doctor exec vp test run tests/ (1453 passed)
• New unit tests pass (22): apply-color-preference, normalize-help-command, version-command, extended strip-unknown-cli-flags
• pnpm --filter react-doctor typecheck
• pnpm exec vp lint (changed files) + pnpm exec vp fmt --check
• pnpm smoke:json-report
• Manual smoke: help, help install, version, -v/-V/--version, --color/--no-color (ANSI on/off verified when piped), REACT_DOCTOR_FORCE_COLOR=1

Pre-existing failures on the merged base — core/check-expo-project (environment-specific: a global ~/.config/git/ignore that lists .env.local) and oxlint-plugin-react-doctor/no-multi-comp — are in files untouched by this PR and unrelated to it.

Made with Cursor

---

Note

Low Risk
Changes are limited to CLI bootstrap, help text, and output coloring; telemetry opt-out extends existing --no-score behavior without altering scan logic.

Overview
Aligns the react-doctor CLI with clig.dev / 12-factor UX: explicit color control, fixed help routing, richer version output, and clearer opt-out wording for score/telemetry.

Color — Adds --color / --no-color on the default scan, install, and version flows, plus REACT_DOCTOR_FORCE_COLOR / REACT_DOCTOR_NO_COLOR. Preference is resolved from stripped argv before Commander runs (so help epilogs respect it), updates the shared highlighter via new setColorEnabled() in @react-doctor/core, and mirrors the choice onto FORCE_COLOR / NO_COLOR for spinners and prompts. Last flag wins; tokens after -- are ignored.

Help — Rewrites leading help / help <command> to --help / <command> --help so users no longer scan a directory named help. Root and install help now lead with example commands (lazy epilog renderers) and add a feedback/issues link.

Version — New react-doctor version prints react-doctor/<ver> <platform>-<arch> node-<node>; standalone -V prints the bare version before parse (alongside existing -v / --version).

Telemetry alias — --no-telemetry aliases --no-score (score API, share URL, Sentry); inspect resolution and early Sentry init honor it; --score + --no-telemetry is rejected. Flag stripper knows the new flags and version subcommand spec.

^{Reviewed by Cursor Bugbot for commit a931264. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@623

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@623

npm i https://pkg.pr.new/react-doctor@623

commit: a931264

[github-actions]

React Doctor found 18 files changed in this pull request, but none matched the files covered by its enabled checks.

Scope: 18 files changed on ray/6cd0689c vs. main.

View workflow run

Generated by React Doctor. Questions? Contact founders@million.dev.

[rayhanadev]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a931264. Configure here.}