feat(cli)!: document exit codes, usage errors use exit code 2

[DavidWells]

Potentially breaking change: Usage errors (e.g. invalid command) now exit with exit code 2 (previously 1).

Split from #8300 (1 of 9).

What

• Adds a documented exit-code dictionary: 0 ok · 1 error · 2 usage error · 4 input needed (src/utils/exit-codes.ts), shown in the root --help footer
• Commander usage errors (unknown command, unknown option, bad/missing arguments) now exit 2 instead of 1
• Unknown-command "did you mean" output moves from stdout to stderr

Why it helps agents

Agents and scripts branch on exit codes. Today every failure exits 1, so a typo'd flag is indistinguishable from a failed deploy — retry logic can't tell "fix the command" from "the operation failed." Keeping suggestions on stderr means stdout stays parseable.

New codes only appear on paths that already failed; nothing that exited 0 changes.

Testing

• New unit tests for the dictionary; didyoumean/help integration snapshots regenerated on this branch (help delta is only the new footer lines)
• typecheck ✓ lint ✓ 406 unit tests ✓

Stacked PRs that build on this: space-form subcommand guard, --non-interactive (exit 4).

[github-actions]

📊 Benchmark results

Comparing with 8943e38

• Dependency count: 1,127 (no change)
• Package size: 379 MB (no change)
• Number of ts-expect-error directives: 358 (no change)

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a structured EXIT_CODES contract (SUCCESS, GENERAL_ERROR, USAGE_ERROR, NON_INTERACTIVE_PROMPT) and a USAGE_ERROR_CODES set aggregating Commander error codes for usage-related failures. run-program.ts now exits with EXIT_CODES.USAGE_ERROR when a CommanderError's code matches USAGE_ERROR_CODES. main.ts reworks unknown-command handling to write warnings and suggestions to stderr instead of stdout, outputs help, and exits with the new usage error code; the help footer documents exit codes. Corresponding unit and integration tests were updated.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: jaredm563

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main change: documenting exit codes and making usage errors exit with code 2.
Description check	✅ Passed	The description matches the changeset and explains the exit-code update, stderr move, and testing coverage.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch split/exit-codes

Warning

Review ran into problems

🔥 Problems

Repository analysis: Couldn't refresh netlify/cli clone - clone failed: Clone operation failed: Stream initialization permanently failed: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/commands/main.ts (1)

208-210: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

New "what the code does" comment violates coding guideline.

These three lines explain what the following block does. As per coding guidelines, **/*.{ts,tsx,js,jsx} should "Never write comments on what the code does; make the code clean and self-explanatory instead."

♻️ Proposed removal

-  // In non-interactive environments (CI/CD, scripts), show the suggestion
-  // without prompting, and display full help for available commands.
-  // Diagnostics belong on stderr so stdout stays clean for machine consumers.
   if (!isInteractive()) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/main.ts` around lines 208 - 210, Remove the explanatory comment
in the non-interactive handling block in main.ts, since it restates what the
code already does and violates the no-comment guideline. Keep the logic in the
surrounding non-interactive flow self-explanatory, and if needed rely on the
existing code structure around the command suggestion/help output and stderr
diagnostics instead of adding a narrative comment.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/main.ts`:
- Around line 208-210: Remove the explanatory comment in the non-interactive
handling block in main.ts, since it restates what the code already does and
violates the no-comment guideline. Keep the logic in the surrounding
non-interactive flow self-explanatory, and if needed rely on the existing code
structure around the command suggestion/help output and stderr diagnostics
instead of adding a narrative comment.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d9d1e639-b321-4a53-9ad4-7308af62ff9e

📥 Commits

Reviewing files that changed from the base of the PR and between 3c41e72 and fa31597.

⛔ Files ignored due to path filters (2)

• tests/integration/commands/didyoumean/__snapshots__/didyoumean.test.ts.snap is excluded by !**/*.snap
• tests/integration/commands/help/__snapshots__/help.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (6)

• src/commands/main.ts
• src/utils/command-error-handler.ts
• src/utils/exit-codes.ts
• src/utils/run-program.ts
• tests/integration/commands/didyoumean/didyoumean.test.ts
• tests/unit/utils/exit-codes.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• netlify/blueprints (manual)