fix(cli): render missing channel arg usage by yimoj · Pull Request #3863 · NVIDIA/NemoClaw

yimoj · 2026-05-20T05:30:15Z

Summary

Missing messaging channel arguments now render oclif's normal required-argument usage instead of leaking parser internals. The public channel command signatures also show <channel> in the positional usage slot for add/remove/start/stop.

Related Issue

Fixes #3704

Changes

Keep runOclifArgv's temporary process.argv aligned with the native oclif argv while oclif renders parse-error help, then restore it in a finally block.
Move <channel> into the public channel command usage metadata and leave --dry-run in the flags column.
Add regression coverage for missing channel args through the real CLI dispatch path and root help signatures.
Update CLI/docs parity checking so canonical required placeholders such as <channel> are preserved while docs-only suffixes are still tolerated.

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)

Verification

npx prek run --all-files passes
npm test passes
Tests added or updated for new or changed behavior
No secrets, API keys, or credentials committed
Docs updated for user-facing behavior changes
make 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)

Additional verification run locally:

isolated real CLI repro for alpha channels add|remove|start|stop missing <channel>: each exited 2 with usage and no RequiredArgsError/validateArgs stack marker
npx -y -p node@22.16.0 node node_modules/vitest/vitest.mjs run src/lib/cli/oclif-runner.test.ts test/cli.test.ts test/root-help.test.ts test/cli-oclif-compatibility.test.ts -t "(runOclifArgv|restores process argv|policy and channel mutations reject missing parser-owned values before dispatch|shows channel as a required positional argument|renders native sandbox help without registry recovery|hands public sandbox execution to oclif as native argv|uses the alias binary name in native oclif help)"
npx -y -p node@22.16.0 -p npm@10 npm run typecheck:cli
npx -y -p node@22.16.0 -p npm@10 npm run build:cli
npx -y -p node@22.16.0 -p npm@10 npm run checks
bash -n test/e2e/e2e-cloud-experimental/check-docs.sh
bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-cli
cd nemoclaw && npx -y -p node@22.16.0 -p npm@10 npm test

Local broad CLI project note: NEMOCLAW_TEST_TIMEOUT=60000 NEMOCLAW_EXEC_TIMEOUT=60000 npx -y -p node@22.16.0 node node_modules/vitest/vitest.mjs run --project cli was otherwise green but failed an unrelated host-permission fixture in test/fetch-guard-patch-regression.test.ts; the fixture exits on rm -rf /usr/local/lib/node_modules/openclaw because this machine's /usr/local/lib/node_modules is root-owned 750.

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

New Features
- Channel command help text now displays complete command syntax with required arguments clearly shown.
Bug Fixes
- Enhanced error messaging for missing required arguments in channel-related commands.
Tests
- Expanded test coverage for CLI argument parsing and error handling scenarios.
- Improved documentation consistency validation for command signatures.

coderabbitai · 2026-05-20T05:30:29Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: db151f83-2f1f-47f2-ae28-3c4daa483e2c

📥 Commits

Reviewing files that changed from the base of the PR and between 45b6d22 and 8be7c2c.

📒 Files selected for processing (4)

src/lib/cli/oclif-runner.test.ts
src/lib/cli/oclif-runner.ts
src/lib/cli/public-display-defaults.ts
test/cli.test.ts

📝 Walkthrough

Walkthrough

This PR updates channel command help signatures to treat <channel> as a required positional argument, ensures runOclifArgv temporarily brands process.argv during oclif execution for correct routing, and updates integration tests and docs extraction validation to reflect the canonical signatures.

Changes

Channel command signatures and oclif argv branding

Layer / File(s)	Summary
Channel command help metadata `src/lib/cli/public-display-defaults.ts`	`sandbox:channels:add`, `sandbox:channels:remove`, `sandbox:channels:start`, and `sandbox:channels:stop` now include explicit `usage` strings showing `<channel>` as a positional argument and move it out of the `flags` fragment, leaving only `[--dry-run]`.
Process argv preservation in runOclifArgv `src/lib/cli/oclif-runner.ts`	`runOclifArgv` captures the original `process.argv`, composes a branded argv (with fallbacks to `process.execPath` and `CLI_NAME`), temporarily sets it for the `executeOclif` call, and restores the original argv in a `finally` block so oclif routing and help logic see the correct CLI context.
runOclifArgv tests `src/lib/cli/oclif-runner.test.ts`	Test suite now saves/restores `process.argv` via `beforeEach`/`afterEach`, asserts the branded argv is passed to mocked oclif `execute`, verifies argv is restored after normal execution, and confirms restoration and error propagation when `execute` throws.
Integration and help-output tests `test/cli.test.ts`, `test/root-help.test.ts`	CLI dispatch regression test validates channel subcommands (`add`/`remove`/`start`/`stop`) reject missing `<channel>` with correct oclif-style required-arg output and no parser/dispatch error artifacts. Root help test asserts `<channel>` appears as a required positional argument in rendered help for each channel action.
Docs parity extraction adjustments `test/e2e/e2e-cloud-experimental/check-docs.sh`	CLI docs parity script now loads canonical `--dump-commands` output, iteratively strips placeholder suffixes only until each `commands.mdx` heading matches a canonical signature (preserving placeholders that are part of the signature), and trims extracted section headings before checking for exact matches.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

Sandbox

Suggested reviewers

ericksoa

Poem

🐰 The argv now stands tall and true,
Branded bright for oclif to chew,
Channel routes find their rightful way,
Help and docs align today,
Hops away, task complete! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(cli): render missing channel arg usage' directly and clearly summarizes the main change across all modified files, which center on ensuring missing messaging channel arguments render proper oclif usage instead of parser internals.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

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

Keep the native oclif dispatch argv in sync with process.argv while oclif handles parser errors, so missing channel args render command usage instead of leaking parser internals. Move the required <channel> positional into public channel command signatures and cover add/remove/start/stop through CLI dispatch tests. Signed-off-by: Yimo Jiang <yimoj@nvidia.com>

wscurran · 2026-05-20T16:08:35Z

✨ Related open issues:

#3704 [All Platforms][CLI&UX] nemoclaw channels add without argument dumps raw stack trace instead of actionable usage hint

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

ericksoa

Approved after conflict/topper repair. The branch carries forward the missing parser-owned arg usage fix without reintroducing obsolete publicDisplay command blocks; local validation passed build, focused runner/root-help/CLI tests, docs check with remote links disabled, and live checks are green at 8be7c2c.

## Summary Refreshes the NemoClaw docs for the v0.0.49 hardening release, including release notes, command reference updates, troubleshooting guidance, version metadata, and regenerated user skills. ## Changes - #3796, #3854, #3863, #3866, #3984, #4001, #4011, #4013, #4020, #4022, #4023, #4060, #4062 -> `docs/about/release-notes.mdx`: Adds the v0.0.49 hardening release summary covering gateway reliability, status/doctor/shields and debug UX, OpenClaw compatibility, messaging channel teardown, Hermes policy scoping, snapshots, source installs and Docker group security note, GPU preflight, CLI usage, E2E, and CI improvements. - #3796 -> `docs/manage-sandboxes/backup-restore.mdx` and `docs/reference/commands.mdx`: Documents `snapshot restore --to` overwrite protection and the `--force` opt-in. - #3863, #4013, #4020, #4023 -> `docs/reference/commands.mdx`: Documents missing channel argument usage, sandbox-scoped custom preset matching, session policy preset sync, and gateway failure classification (uses the real probe states from `src/lib/status-command-deps.ts`). - #4022, #4060, #4062 -> `docs/reference/troubleshooting.mdx`: Adds guidance for gateway-down `connect`, source checkout OpenShell bootstrapping, WDDM placeholder GPU names, and Jetson sandbox GPU passthrough. - Release prep -> `docs/project.json`, `docs/versions1.json`, `.agents/skills/nemoclaw-user-*`: Bumps docs metadata to 0.0.49 and refreshes generated user skills from the Fern docs. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [x] Doc only (includes code sample changes) ## Verification - [x] `npx prek run --all-files` passes - [ ] `npm test` passes - [ ] Tests added or updated for new or changed behavior - [x] No secrets, API keys, or credentials committed - [x] Docs updated for user-facing behavior changes - [ ] `make docs` builds without warnings (doc changes only) - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) \`make docs\` was attempted locally but did not complete because \`npm\` returned \`403 Forbidden\` while fetching \`fern-api\` from \`registry.npmjs.org\` in the sandboxed environment. --- Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>  ## Summary by CodeRabbit * **Documentation** * Released v0.0.49 with reliability and compatibility improvements including faster gateway failure diagnostics and safer snapshot restore behavior * Enhanced snapshot restore documentation with `--to` cloning and `--force` overwrite requirements * Expanded troubleshooting guides for source installs, GPU setup, and gateway recovery * Clarified Docker group access requirements and improved CLI command reference * **Chores** * Version bumped to 0.0.49  [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/4078?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)   --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

yimoj self-assigned this May 20, 2026

yimoj force-pushed the fix/3704-channels-required-arg-usage branch from 5299449 to 45b6d22 Compare May 20, 2026 05:41

yimoj added the v0.0.48 Release target label May 20, 2026

wscurran added fix labels May 20, 2026

github-actions Bot mentioned this pull request May 21, 2026

fix(connect): fail fast when gateway is down #3853

Closed

6 tasks

cv added v0.0.49 Release target and removed v0.0.48 Release target labels May 21, 2026

github-actions Bot mentioned this pull request May 22, 2026

fix(connect): fail fast when gateway is down #4022

Merged

2 tasks

cv added v0.0.50 Release target and removed v0.0.49 Release target labels May 22, 2026

Merge origin/main into channels usage fix

8be7c2c

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

ericksoa force-pushed the fix/3704-channels-required-arg-usage branch from 6beb63b to 8be7c2c Compare May 22, 2026 15:20

ericksoa approved these changes May 22, 2026

View reviewed changes

ericksoa merged commit 8659463 into NVIDIA:main May 22, 2026
22 checks passed

miyoungc mentioned this pull request May 22, 2026

docs: refresh release notes for v0.0.49 #4078

Merged

12 tasks

wscurran added area: cli Command line interface, flags, terminal UX, or output bug-fix PR fixes a bug or regression and removed NemoClaw CLI labels Jun 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(cli): render missing channel arg usage#3863

fix(cli): render missing channel arg usage#3863
ericksoa merged 2 commits into
NVIDIA:mainfrom
yimoj:fix/3704-channels-required-arg-usage

yimoj commented May 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 20, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

wscurran commented May 20, 2026

Uh oh!

ericksoa left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

yimoj commented May 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

wscurran commented May 20, 2026

Uh oh!

ericksoa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yimoj commented May 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 20, 2026 •

edited

Loading