fix(cli): report oclif parse errors without a raw stack trace

[laitingsheng]

Summary

Passing a value outside a flag's or argument's declared enum crashed the CLI instead of reporting the mistake. oclif's parse error escaped as an unhandled rejection, so the user got a Node stack trace, an error-property dump, and the Node version banner, and the process exited 1 instead of the declared parser code 2. The actionable line was present but buried mid-trace. Those commands now print that line on its own and exit 2.

Related Issue

Fixes #8123

Changes

• src/lib/cli/oclif-runner.ts: runOclifCommandById maps oclif errors to exit codes by hand rather than delegating to oclif's handle(), and it recognized parse errors from a list of class names. That list covered four of oclif's seven CLIParseError subclasses, so FlagInvalidOptionError and ArgInvalidOptionError fell through to the final rethrow and out of dispatchCli(), which has no rejection handler. Added hasOclifParseErrorShape, which matches on the three markers the CLIParseError base class gives every subclass: a numeric oclif.exit, an own parse property, and a boolean showHelp. Matching the shape rather than the name covers the subclasses added since the list was written and any added later.
• src/lib/cli/oclif-runner.ts: the existing name list stays as written and is OR'd with the new check, so no error that already reached the parse branch changes route. Recognized errors keep using the existing exit(exitCode ?? 1) line, which yields 2 for a parse error with no further change.
• Only the direct command-id route was affected. The native internal and sandbox namespaces go through runOclifArgv, which does call oclif's handle() and already printed these cleanly, which is why nemoclaw <sandbox-name> inference set behaved while the global nemoclaw inference set crashed.
• Tests: src/lib/cli/oclif-runner.test.ts covers an invalid enum flag value, an invalid enum argument value, a parse error whose class name is unknown but whose shape matches, and a command failure carrying an unrelated parse property that must still rethrow. test/cli/oclif-parse-errors.test.ts runs the real CLI for both user-visible commands and asserts the exit code, the actionable line, and the absence of stack frames, @oclif/core paths, and the Node version banner.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: no documented behavior changes. docs/inference/configure-model-capabilities.mdx documents which --reasoning-effort values are accepted, and docs/reference/commands.mdx lists the commands and flags. No page documents the previous exit code, the stack trace, or the error text for a rejected value.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: blocked
• Evidence: no documentation paths changed. The subagent review did not run because the authoring session is configured not to spawn subagents without an explicit request. The documentation assessment recorded under Quality Gates was made directly against the two pages that mention the affected commands and flag values.
• Agent: Claude Code

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli src/lib/cli/ --project integration test/cli/dispatch-basics.test.ts test/cli/onboard-compatibility.test.ts test/cli/oclif-parse-errors.test.ts — 13 files, 136 tests passed. With src/lib/cli/oclif-runner.ts reverted and dist rebuilt, the 5 new assertions fail and the other 15 in those two files still pass, which pins both the recognition change and the exit code. Before the fix, nemoclaw inference set --reasoning-effort ultra and nemoclaw completion powershell reproduced the reported trace and exit 1; after it, both print one line plus the help hint and exit 2, while nemoclaw onboard --non-interactiv is unchanged. npm run typecheck:cli clean.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of invalid command-line flag and argument values.
  • Parse errors now consistently display clear validation messages and exit with code 2.
  • Prevented stack traces and internal parser details from appearing in user-facing error output.
  • Unrelated command failures continue to propagate normally without being incorrectly formatted as parse errors.

• Tests

  • Added coverage for invalid enum values and structurally recognized parser errors.

[coderabbitai]

📝 Walkthrough

Walkthrough

The CLI now recognizes oclif parse errors by structural properties. Tests cover invalid enum flags and arguments, formatted exit code 2 responses, removal of parser details, and rethrowing unrelated command failures.

Changes

CLI parse error handling

Layer / File(s)	Summary
Structural parse error detection src/lib/cli/oclif-runner.ts, src/lib/cli/oclif-runner.test.ts	isOclifParseError now recognizes errors with oclif exit metadata, an own parse property, and boolean showHelp metadata. Tests cover matching unknown parser error classes and rejecting unrelated failures.
Parse error output validation src/lib/cli/oclif-runner.test.ts, test/cli/oclif-parse-errors.test.ts	Tests cover invalid enum flags and arguments, exit code 2, validation messages, and output without stack traces or internal parser details.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: cli

Suggested reviewers: brandonpelfrey

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: clean handling of oclif parse errors without raw stack traces.
Linked Issues check	✅ Passed	The implementation and tests address issue #8123 by formatting invalid enum errors, preserving exit code 2, and preventing stack traces.
Out of Scope Changes check	✅ Passed	All changes support the linked issue by updating parse-error detection and adding focused CLI and unit tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 fix/oclif-parse-error-boundary

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit de827bf in the fix/oclif-parse-erro... branch remains at 96%, unchanged from commit 4cd4d64 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit de827bf in the fix/oclif-parse-erro... branch remains at 81%, unchanged from commit a931be4 in the main branch.

---

_{Updated August 03, 2026 11:15 UTC}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@test/cli/oclif-parse-errors.test.ts`:
- Around line 22-26: Update both CLI parse-error tests around the
reasoning-effort validation assertions to explicitly verify the required help
hint is present in r.out, in addition to the validation message and clean
parse-failure checks. Use the observable command output and preserve the
existing exit-code assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 307e3f6c-8242-4cfb-97c4-975d4c4b9abd

📥 Commits

Reviewing files that changed from the base of the PR and between 4cd4d64 and de827bf.

📒 Files selected for processing (3)

• src/lib/cli/oclif-runner.test.ts
• src/lib/cli/oclif-runner.ts
• test/cli/oclif-parse-errors.test.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Assert the help hint in both CLI tests.

Issue #8123 requires the validation message and the help hint. These assertions pass if output omits the help hint.

Proposed test change

     expect(r.out).toContain(
       "Expected --reasoning-effort=ultra to be one of: low, medium, high, default",
     );
+    expect(r.out).toContain("See more help with --help");
     expectCleanParseFailure(r.out);
@@
     expect(r.code).toBe(PARSER_EXIT_CODE);
     expect(r.out).toContain("Expected powershell to be one of: bash, zsh, fish");
+    expect(r.out).toContain("See more help with --help");
     expectCleanParseFailure(r.out);

As per path instructions, “Prefer observable outcomes through the public boundary.”

Also applies to: 32-34

🤖 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 `@test/cli/oclif-parse-errors.test.ts` around lines 22 - 26, Update both CLI
parse-error tests around the reasoning-effort validation assertions to
explicitly verify the required help hint is present in r.out, in addition to the
validation message and clean parse-failure checks. Use the observable command
output and preserve the existing exit-code assertions.

Source: Path instructions

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Partial review preserved 0 canonical finding(s) and 1 terminology decision(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

1 semantic terminology decision

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — stack trace at test/cli/oclif-parse-errors.test.ts:17: Keep `stack trace`; repository tests, comments, and writing guidance use it for this user-visible output.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Reviewed exact head de827bf. The structural oclif parse-error predicate is narrowly gated by exit metadata, an own parse field, and boolean help metadata, with unit and CLI regression coverage plus a negative command-failure case. I found no blocking defect. The failing installer test is in unrelated station-pair preparation coverage, while the affected CLI suites passed; automated advisor output reports no blocker.