refactor(cli): centralize oclif base conventions by cv · Pull Request #3612 · NVIDIA/NemoClaw

cv · 2026-05-15T17:36:13Z

Summary

Uses the shared NemoClawCommand base for common oclif conventions now that #3611 has landed. It removes duplicated command-local help flags, routes internal JSON output through the base helper, and adds a guard so help stays centralized.

Changes

Removed repeated help: Flags.help({ char: "h" }) declarations now inherited from NemoClawCommand.baseFlags.
Replaced internal command console.log(JSON.stringify(..., null, 2)) calls with this.logJson(...).
Added an oclif metadata guard that fails when discovered command classes redeclare a local help flag.

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)

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Refactor
- Centralized help flag handling across CLI commands by removing redundant individual flag declarations; help functionality remains unchanged for users.
- Standardized JSON output handling by consolidating logging through the framework's native logJson method instead of manual JSON stringification.

copy-pr-bot · 2026-05-15T17:36:17Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

coderabbitai · 2026-05-15T17:36:20Z

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: c50731a3-007e-4b24-b06d-9d3b9d3312ea

📥 Commits

Reviewing files that changed from the base of the PR and between 456a8c8 and 4cd1e72.

📒 Files selected for processing (46)

src/commands/internal/dev/npm-link-or-shim.ts
src/commands/internal/dns/fix-coredns.ts
src/commands/internal/dns/setup-proxy.ts
src/commands/internal/installer/normalize-env.ts
src/commands/internal/installer/plan.ts
src/commands/internal/installer/resolve-release-tag.ts
src/commands/internal/uninstall/classify-shim.ts
src/commands/internal/uninstall/plan.ts
src/commands/internal/uninstall/run-plan.ts
src/lib/cli/oclif-command-metadata.test.ts
src/lib/commands/credentials.ts
src/lib/commands/credentials/list.ts
src/lib/commands/credentials/reset.ts
src/lib/commands/debug.ts
src/lib/commands/deploy.ts
src/lib/commands/deprecated/start.ts
src/lib/commands/deprecated/stop.ts
src/lib/commands/gateway-token.ts
src/lib/commands/onboard/common.ts
src/lib/commands/sandbox/channels/common.ts
src/lib/commands/sandbox/channels/list.ts
src/lib/commands/sandbox/config/get.ts
src/lib/commands/sandbox/config/set.ts
src/lib/commands/sandbox/connect.ts
src/lib/commands/sandbox/doctor.ts
src/lib/commands/sandbox/hosts/common.ts
src/lib/commands/sandbox/hosts/list.ts
src/lib/commands/sandbox/logs.ts
src/lib/commands/sandbox/policy/common.ts
src/lib/commands/sandbox/policy/list.ts
src/lib/commands/sandbox/share.ts
src/lib/commands/sandbox/share/mount.ts
src/lib/commands/sandbox/share/status.ts
src/lib/commands/sandbox/share/unmount.ts
src/lib/commands/sandbox/shields/down.ts
src/lib/commands/sandbox/shields/status.ts
src/lib/commands/sandbox/shields/up.ts
src/lib/commands/sandbox/skill/install.ts
src/lib/commands/sandbox/snapshot/create.ts
src/lib/commands/sandbox/snapshot/list.ts
src/lib/commands/sandbox/snapshot/restore.ts
src/lib/commands/sandbox/status.ts
src/lib/commands/tunnel/start.ts
src/lib/commands/tunnel/stop.ts
src/lib/commands/uninstall.ts
src/lib/recover-cli-command.ts

💤 Files with no reviewable changes (32)

src/lib/commands/sandbox/snapshot/create.ts
src/commands/internal/dev/npm-link-or-shim.ts
src/lib/commands/sandbox/doctor.ts
src/commands/internal/uninstall/run-plan.ts
src/lib/commands/sandbox/snapshot/restore.ts
src/lib/commands/sandbox/hosts/common.ts
src/lib/commands/sandbox/logs.ts
src/lib/commands/tunnel/stop.ts
src/lib/commands/deprecated/stop.ts
src/lib/commands/sandbox/snapshot/list.ts
src/lib/commands/sandbox/config/set.ts
src/lib/commands/sandbox/config/get.ts
src/lib/commands/credentials/reset.ts
src/lib/commands/sandbox/shields/down.ts
src/lib/commands/onboard/common.ts
src/lib/commands/sandbox/channels/common.ts
src/lib/commands/sandbox/share.ts
src/lib/commands/uninstall.ts
src/lib/commands/sandbox/hosts/list.ts
src/lib/commands/sandbox/policy/list.ts
src/lib/commands/deprecated/start.ts
src/lib/commands/debug.ts
src/lib/commands/sandbox/shields/up.ts
src/lib/commands/tunnel/start.ts
src/lib/commands/sandbox/connect.ts
src/lib/commands/credentials/list.ts
src/lib/commands/credentials.ts
src/lib/commands/sandbox/shields/status.ts
src/lib/commands/sandbox/channels/list.ts
src/lib/commands/sandbox/policy/common.ts
src/lib/commands/sandbox/status.ts
src/lib/commands/gateway-token.ts

📝 Walkthrough

Walkthrough

This PR systematically removes the explicit -h/--help flag definition from 45+ oclif command modules across internal, library, sandbox, and tunnel commands. It refactors JSON output in installer and uninstall commands to use the standard logJson() helper. A test is added to enforce that no command owns the help flag, centralizing help handling in the shared base framework.

Changes

Help flag centralization across oclif commands

Layer / File(s)	Summary
Internal command help flag removal and JSON output standardization `src/commands/internal/dev/npm-link-or-shim.ts`, `src/commands/internal/dns/fix-coredns.ts`, `src/commands/internal/dns/setup-proxy.ts`, `src/commands/internal/installer/normalize-env.ts`, `src/commands/internal/installer/plan.ts`, `src/commands/internal/installer/resolve-release-tag.ts`, `src/commands/internal/uninstall/classify-shim.ts`, `src/commands/internal/uninstall/plan.ts`, `src/commands/internal/uninstall/run-plan.ts`	Help flag entries removed from all internal command modules. Installer commands (normalize-env, plan, resolve-release-tag) and uninstall commands (classify-shim, plan) now use `this.logJson()` instead of manual `JSON.stringify()` for `--json` output. Flags imports cleaned up where help was the only usage.
Base and credentials command help flag removal `src/lib/commands/credentials.ts`, `src/lib/commands/credentials/list.ts`, `src/lib/commands/credentials/reset.ts`, `src/lib/commands/debug.ts`, `src/lib/commands/deploy.ts`, `src/lib/commands/deprecated/start.ts`, `src/lib/commands/deprecated/stop.ts`, `src/lib/commands/gateway-token.ts`, `src/lib/commands/uninstall.ts`, `src/lib/recover-cli-command.ts`	Help flag entries removed from base library commands and credentials subcommands. Flags imports eliminated where help was the only declared flag entry, leaving static flags empty or unchanged for other flags.
Sandbox subcommand help flag removal `src/lib/commands/sandbox/channels/list.ts`, `src/lib/commands/sandbox/config/get.ts`, `src/lib/commands/sandbox/config/set.ts`, `src/lib/commands/sandbox/connect.ts`, `src/lib/commands/sandbox/doctor.ts`, `src/lib/commands/sandbox/hosts/list.ts`, `src/lib/commands/sandbox/logs.ts`, `src/lib/commands/sandbox/policy/list.ts`, `src/lib/commands/sandbox/share.ts`, `src/lib/commands/sandbox/share/mount.ts`, `src/lib/commands/sandbox/share/status.ts`, `src/lib/commands/sandbox/share/unmount.ts`, `src/lib/commands/sandbox/shields/down.ts`, `src/lib/commands/sandbox/shields/status.ts`, `src/lib/commands/sandbox/shields/up.ts`, `src/lib/commands/sandbox/skill/install.ts`, `src/lib/commands/sandbox/snapshot/create.ts`, `src/lib/commands/sandbox/snapshot/list.ts`, `src/lib/commands/sandbox/snapshot/restore.ts`, `src/lib/commands/sandbox/status.ts`	Help flag definitions removed from all sandbox subcommand modules. Flags imports removed from modules where help was the sole flag dependency.
Tunnel commands and shared flag definitions help flag removal `src/lib/commands/onboard/common.ts`, `src/lib/commands/sandbox/channels/common.ts`, `src/lib/commands/sandbox/hosts/common.ts`, `src/lib/commands/sandbox/policy/common.ts`, `src/lib/commands/tunnel/start.ts`, `src/lib/commands/tunnel/stop.ts`	Help flag removed from buildOnboardFlags and mutation flag exports (channels, hosts, policy). Tunnel start and stop commands have help entries removed, with Flags imports cleaned up accordingly.
Test enforcement for help flag centralization `src/lib/cli/oclif-command-metadata.test.ts`	Introduces `OclifCommandClass` TypeScript type, `commandOwnsHelpFlag()` detection function, and adds test case asserting that no discovered oclif commands define their own help flag, enforcing centralized help flag handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

NVIDIA/NemoClaw#3611: Both PRs touch the same oclif command modules (e.g., internal/dns/fix-coredns, internal/dns/setup-proxy, internal/installer/*, internal/uninstall/*) by modifying their oclif import/static flags wiring (help/Flags removal) alongside the NemoClawCommand base-class migration.

Suggested labels

NemoClaw CLI, enhancement: feature

Suggested reviewers

jyaunches
ericksoa

Poem

🐰 Hop, hop! The help flag bounces free,
From each command it once did dwell,
Now centralized, one shared key,
In base commands, unified and well!
JSON logs now tidy, logJson shines so bright,
A refactor hopping toward the light! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 'refactor(cli): centralize oclif base conventions' accurately captures the main objective of the pull request, which is to remove duplicated help flag declarations and centralize oclif conventions in a shared base class.
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 docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch refactor/oclif-base-conventions

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

github-actions · 2026-05-15T17:38:04Z

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, sandbox-operations-e2e, diagnostics-e2e, network-policy-e2e, shields-config-e2e, credential-migration-e2e
Optional E2E: snapshot-commands-e2e, tunnel-lifecycle-e2e, channels-stop-start-e2e, skill-agent-e2e, state-backup-restore-e2e

Dispatch hint: cloud-onboard-e2e,sandbox-operations-e2e,diagnostics-e2e,network-policy-e2e,shields-config-e2e,credential-migration-e2e

Auto-dispatched E2E: cloud-onboard-e2e, sandbox-operations-e2e, diagnostics-e2e, network-policy-e2e, shields-config-e2e, credential-migration-e2e via nightly-e2e.yaml at 4cd1e727cb98618284ca98e8e03bbd66e0457559 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

cloud-onboard-e2e (about 45 minutes): Covers public install plus onboard, policy preset setup, sandbox health, Landlock/read-only enforcement, API key leak checks, and inference.local. This is the best required guard for changed installer internals and onboard flag construction.
sandbox-operations-e2e (about 60 minutes): Exercises real sandbox list/connect/status/logs/recovery/multi-sandbox operations, matching the broad sandbox command wrapper changes.
diagnostics-e2e (about 45 minutes): Covers debug diagnostics, credentials list, sandbox config, and CLI availability paths touched by this PR.
network-policy-e2e (about 45 minutes): Required because sandbox policy/common and DNS/security-boundary command wrappers changed; validates deny-by-default, whitelist, live policy add, dry-run, hot reload, inference exemption, permissive mode, and SSRF validation.
shields-config-e2e (about 30 minutes): Covers shields up/down/status and sandbox config get/set lifecycle, directly matching changed shields and config command wrappers that affect sandbox security state.
credential-migration-e2e (about 30 minutes): Credential commands are touched; this validates credential migration hardening and confirms credentials list reads from the OpenShell gateway without leaking plaintext credentials.

Optional E2E

snapshot-commands-e2e (about 30 minutes): Useful adjacent coverage for changed snapshot create/list/restore command wrappers; optional because changes appear limited to centralized help metadata.
tunnel-lifecycle-e2e (about 60 minutes): Useful for changed tunnel start/stop and deprecated start/stop aliases; optional because command action logic did not change.
channels-stop-start-e2e (medium): Optional confidence for changed sandbox channels command wrappers and provider bridge lifecycle.
skill-agent-e2e (medium): Optional coverage for the changed sandbox skill install command wrapper.
state-backup-restore-e2e (about 60 minutes): Optional broader state lifecycle confidence around sandbox state operations adjacent to snapshot/share changes.

New E2E recommendations

host uninstall lifecycle (high): This PR touches uninstall command wrappers and internal uninstall plan/run-plan JSON output, but existing non-GPU E2E coverage does not appear to exercise nemoclaw uninstall, internal uninstall plan --json, shim classification, and host cleanup on a standard CPU runner.
- Suggested test: Add a CPU host-uninstall E2E that installs from source, runs internal uninstall plan/classify-shim JSON checks, executes nemoclaw uninstall --yes, and verifies user-local shim/config cleanup without requiring Ollama GPU model deletion.
packaged CLI help and command discovery (medium): The PR centralizes help flags across many oclif commands. Unit metadata coverage was added, but no existing E2E appears to smoke-test representative --help invocations from the packaged CLI after install.
- Suggested test: Add a lightweight installed-CLI smoke test that runs nemoclaw --help plus representative command help for onboard, credentials reset, sandbox connect, sandbox policy add, sandbox config set, tunnel start, and uninstall.
sandbox share and host-alias commands (medium): Share mount/status/unmount and hosts list/mutation wrappers changed, but the inspected E2E set does not show dedicated coverage for SSHFS share lifecycle or sandbox host-alias command parsing.
- Suggested test: Add a sandbox filesystem share and host-alias E2E covering sandbox share mount/status/unmount and sandbox hosts add/list/remove --dry-run against a live sandbox.

Dispatch hint

Workflow: nightly-e2e.yaml
jobs input: cloud-onboard-e2e,sandbox-operations-e2e,diagnostics-e2e,network-policy-e2e,shields-config-e2e,credential-migration-e2e

# Conflicts: # src/commands/internal/dns/fix-coredns.ts # src/commands/internal/dns/setup-proxy.ts # src/lib/cli/oclif-command-metadata.test.ts # src/lib/commands/credentials.ts # src/lib/commands/credentials/list.ts # src/lib/commands/deploy.ts # src/lib/commands/deprecated/start.ts # src/lib/commands/deprecated/stop.ts # src/lib/commands/sandbox/channels/list.ts # src/lib/commands/sandbox/hosts/list.ts # src/lib/commands/sandbox/policy/list.ts # src/lib/commands/sandbox/share.ts # src/lib/commands/sandbox/share/mount.ts # src/lib/commands/sandbox/share/status.ts # src/lib/commands/sandbox/share/unmount.ts # src/lib/commands/sandbox/shields/status.ts # src/lib/commands/sandbox/shields/up.ts # src/lib/commands/sandbox/skill/install.ts # src/lib/commands/sandbox/snapshot/list.ts # src/lib/commands/sandbox/status.ts # src/lib/commands/tunnel/start.ts # src/lib/commands/tunnel/stop.ts # src/lib/commands/uninstall.ts # src/lib/recover-cli-command.ts

github-actions · 2026-05-15T18:06:33Z

Selective E2E Results — ✅ All requested jobs passed

Run: 25932751198
Target ref: 4cd1e727cb98618284ca98e8e03bbd66e0457559
Workflow ref: main
Requested jobs: cloud-onboard-e2e,sandbox-operations-e2e,diagnostics-e2e,network-policy-e2e,shields-config-e2e,credential-migration-e2e
Summary: 6 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
credential-migration-e2e	✅ success
diagnostics-e2e	✅ success
network-policy-e2e	✅ success
sandbox-operations-e2e	✅ success
shields-config-e2e	✅ success

cv added 10 commits May 15, 2026 09:46

refactor(cli): migrate global commands to shared base

d653d66

refactor(cli): migrate sandbox inspection commands to shared base

5e5e13c

refactor(cli): migrate sandbox mutation commands to shared base

4bfc3fa

refactor(cli): migrate nested sandbox commands to shared base

c26098e

refactor(cli): migrate internal commands to shared base

3ebfcfc

refactor(cli): migrate recover command to shared base

3f5e81c

test(cli): require commands to use shared oclif base

d17c6c7

refactor(cli): inherit shared oclif help flag

b97a971

refactor(cli): use shared JSON logging helper

0a19e82

test(cli): guard centralized oclif help flag

9a36948

cv self-assigned this May 15, 2026

cv added the v0.0.44 label May 15, 2026

cv changed the base branch from refactor/oclif-shared-command-base to main May 15, 2026 17:46

cv marked this pull request as ready for review May 15, 2026 17:46

cv enabled auto-merge (squash) May 15, 2026 17:47

jyaunches approved these changes May 15, 2026

View reviewed changes

cv merged commit d42e605 into main May 15, 2026
32 of 35 checks passed

cv deleted the refactor/oclif-base-conventions branch May 27, 2026 21:17

wscurran added the refactor PR restructures code without intended behavior change label Jun 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(cli): centralize oclif base conventions#3612

refactor(cli): centralize oclif base conventions#3612
cv merged 11 commits into
mainfrom
refactor/oclif-base-conventions

cv commented May 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

copy-pr-bot Bot commented May 15, 2026

Uh oh!

coderabbitai Bot commented May 15, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented May 15, 2026 •

edited

Loading

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented May 15, 2026

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

Uh oh!

github-actions Bot commented May 15, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cv commented May 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 15, 2026 •

edited

Loading

github-actions Bot commented May 15, 2026 •

edited

Loading