fix(cli): clarify status command scope

[HwangJohn]

Summary

Clarifies the difference between global status and sandbox-scoped <name> status in help, docs, and text output. Wrong-form nemoclaw status <name> now prints an actionable reorder suggestion while preserving existing JSON behavior.

Related Issue

Fixes #754

Changes

• Update global and sandbox status command summaries, descriptions, examples, and root help.
• Add a scope hint for wrong-form status <name> usage, including --json preservation.
• Label global and sandbox text status output with explicit scope headings.
• Update reference docs and CLI selection guidance.
• Add and update routing, output, help, and compatibility tests.

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

Validated locally on Windows and on DGX Spark/Linux. npm run docs completed with 0 errors; Fern reported the existing 2 warnings.

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• 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: HwangJohn angelic805@gmail.com

Summary by CodeRabbit

• New Features

  • Improved CLI help and reference text to clearly distinguish global status from per-sandbox <name> status, with updated examples and scope hints.
  • Enhanced status display labeling, including a dedicated global status header for registered sandboxes and host services.

• Bug Fixes

  • Added clearer handling when a sandbox-like argument is provided to the global status command, showing a global-only usage hint and exiting with the correct error code.

• Tests

  • Updated and expanded status-routing and output-label assertions to match the revised help text and formatting.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 09c7c07b-b4f4-45d5-8358-9e58e17db017

📥 Commits

Reviewing files that changed from the base of the PR and between 3d33ab2 and c61098b.

📒 Files selected for processing (2)

• src/lib/cli/public-dispatch.ts
• test/cli/status-routing.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/cli/public-dispatch.ts

---

📝 Walkthrough

Walkthrough

This PR clarifies global versus sandbox-scoped status commands across command metadata, runtime output, routing, tests, and docs. It also adds a dispatcher guard that rejects sandbox-like arguments passed to global status and prints a corrected usage hint.

Changes

Global vs sandbox-scoped status clarity

Layer / File(s)	Summary
Command metadata and display descriptions src/commands/sandbox/status.ts, src/commands/status.ts, src/lib/cli/public-display-defaults.ts	Rewords command summaries/descriptions and updates public display descriptions for sandbox and global status commands.
Runtime output header and root-help guidance src/lib/inventory/index.ts, src/lib/actions/root-help.ts	Adds a global status header before the sandbox list and adds help text that distinguishes global commands from sandbox commands with example forms.
Wrong-form dispatcher guard src/lib/cli/public-dispatch.ts	Normalizes argv through new dispatch functions and adds a guard that rejects sandbox-like arguments passed to global status with a corrected usage hint and exit code 2.
Tests for runtime and dispatcher changes src/lib/actions/sandbox/status-flow.test.ts, src/lib/inventory/index.test.ts, test/cli-oclif-compatibility.test.ts, test/cli/status-routing.test.ts, test/root-help.test.ts	Updates assertions for the new header, help text, routing behavior, and rejected argument combinations.
Reference documentation updates docs/reference/cli-selection-guide.mdx, docs/reference/commands.mdx, docs/reference/commands-nemohermes.mdx	Updates CLI reference pages to describe global versus sandbox-scoped status usage and cross-reference the two forms.

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

Suggested reviewers: cv, prekshivyas

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% 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 is concise and accurately summarizes the main change: clarifying CLI status command scope.
Linked Issues check	✅ Passed	The PR satisfies #754 by clarifying global vs sandbox status in help, output, and remediation hints.
Out of Scope Changes check	✅ Passed	The code, docs, and tests all support the status-scope clarification and do not introduce unrelated changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (2)

docs/reference/commands.mdx (1)

1743-1743: ⚡ Quick win

Replace clause-level colon with sentence punctuation.

Line 1743 uses a colon between clauses instead of introducing a list, which violates the docs punctuation rule.

As per coding guidelines, "Colons should only introduce a list."

🤖 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 `@docs/reference/commands.mdx` at line 1743, The sentence in the docs file uses
a colon after "host-wide" to separate two independent clauses rather than to
introduce a list, which violates the punctuation guideline that colons should
only introduce lists. Replace the colon separating "This command is host-wide:"
from the rest of the sentence with a period to create two separate sentences, or
restructure the sentence entirely to remove the clause-separating colon while
maintaining clear documentation of what the command does.

Source: Coding guidelines

docs/reference/commands-nemohermes.mdx (1)

1440-1440: ⚡ Quick win

Replace clause-separating colon in this sentence.

Line 1440 uses a colon as general punctuation (host-wide: it summarizes ...), but this style guide reserves colons for introducing lists.
Please rewrite this sentence with a period/comma (and update the generator source file so regeneration preserves it).

As per coding guidelines, "Colons should only introduce a list. Flag colons used as general punctuation between clauses."

🤖 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 `@docs/reference/commands-nemohermes.mdx` at line 1440, The sentence at line
1440 uses a colon as general clause-separating punctuation ("host-wide: it
summarizes..."), but according to the style guide, colons should only be used to
introduce lists. Replace the colon after "host-wide" with a period or comma to
properly separate the two independent clauses. Additionally, locate and update
the generator source file that produces this documentation (not just the
markdown file itself) so that when the documentation is regenerated, this
punctuation change is preserved and not overwritten.

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 `@docs/reference/commands-nemohermes.mdx`:
- Line 1440: The sentence at line 1440 uses a colon as general clause-separating
punctuation ("host-wide: it summarizes..."), but according to the style guide,
colons should only be used to introduce lists. Replace the colon after
"host-wide" with a period or comma to properly separate the two independent
clauses. Additionally, locate and update the generator source file that produces
this documentation (not just the markdown file itself) so that when the
documentation is regenerated, this punctuation change is preserved and not
overwritten.

In `@docs/reference/commands.mdx`:
- Line 1743: The sentence in the docs file uses a colon after "host-wide" to
separate two independent clauses rather than to introduce a list, which violates
the punctuation guideline that colons should only introduce lists. Replace the
colon separating "This command is host-wide:" from the rest of the sentence with
a period to create two separate sentences, or restructure the sentence entirely
to remove the clause-separating colon while maintaining clear documentation of
what the command does.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 52b5da29-c1ed-4b87-a2d4-6a71b76926d4

📥 Commits

Reviewing files that changed from the base of the PR and between 01e5525 and 70eb884.

📒 Files selected for processing (15)

• docs/reference/cli-selection-guide.mdx
• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/commands/sandbox/status.ts
• src/commands/status.ts
• src/lib/actions/root-help.ts
• src/lib/actions/sandbox/status-flow.test.ts
• src/lib/actions/sandbox/status.ts
• src/lib/cli/public-dispatch.ts
• src/lib/cli/public-display-defaults.ts
• src/lib/inventory/index.test.ts
• src/lib/inventory/index.ts
• test/cli-oclif-compatibility.test.ts
• test/cli/status-routing.test.ts
• test/root-help.test.ts

[coderabbitai]

🧹 Nitpick comments (2)

src/lib/actions/sandbox/status.ts (1)

153-154: 🏗️ Heavy lift

Avoid blanket complexity suppression for showSandboxStatus.

Line 153 and Line 491 disable the complexity rule for the whole function instead of reducing branching. Please split showSandboxStatus into smaller helpers (e.g., preflight/header render, lookup-state handling, and post-status diagnostics) and keep complexity lint active.

As per coding guidelines: **/*.{js,ts,jsx,tsx}: Keep function complexity low.

Also applies to: 491-491

🤖 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/lib/actions/sandbox/status.ts` around lines 153 - 154, The
showSandboxStatus function has blanket eslint-disable complexity comments on
lines 153 and 491 instead of addressing the actual complexity. Refactor the
showSandboxStatus function by splitting it into smaller helper functions that
handle specific concerns: one for preflight and header rendering, one for
lookup-state handling, and one for post-status diagnostics. After refactoring
the function logic into these smaller helpers, remove the eslint-disable
complexity comments so the linter can properly enforce low complexity on the
smaller, focused functions.

Source: Coding guidelines

src/lib/cli/public-dispatch.ts (1)

310-312: 🏗️ Heavy lift

Refactor dispatchCli instead of suppressing complexity checks.

Line 310 and Line 420 suppress complexity for the full dispatcher path. Please extract the global/sandbox subflows into dedicated helpers so dispatchCli stays orchestration-only and complexity lint can remain enabled.

As per coding guidelines: **/*.{js,ts,jsx,tsx}: Keep function complexity low.

Also applies to: 420-420

🤖 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/lib/cli/public-dispatch.ts` around lines 310 - 312, The dispatchCli
function in src/lib/cli/public-dispatch.ts uses an eslint-disable complexity
comment to suppress complexity checks. Instead of suppressing the check,
refactor the function by extracting the global and sandbox subflow logic into
separate dedicated helper functions. Keep dispatchCli as a thin orchestration
layer that delegates to these new helpers, then remove the eslint-disable
complexity comment to re-enable the linting rule. This will improve code
maintainability and keep the complexity of individual functions within
acceptable limits.

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/lib/actions/sandbox/status.ts`:
- Around line 153-154: The showSandboxStatus function has blanket eslint-disable
complexity comments on lines 153 and 491 instead of addressing the actual
complexity. Refactor the showSandboxStatus function by splitting it into smaller
helper functions that handle specific concerns: one for preflight and header
rendering, one for lookup-state handling, and one for post-status diagnostics.
After refactoring the function logic into these smaller helpers, remove the
eslint-disable complexity comments so the linter can properly enforce low
complexity on the smaller, focused functions.

In `@src/lib/cli/public-dispatch.ts`:
- Around line 310-312: The dispatchCli function in
src/lib/cli/public-dispatch.ts uses an eslint-disable complexity comment to
suppress complexity checks. Instead of suppressing the check, refactor the
function by extracting the global and sandbox subflow logic into separate
dedicated helper functions. Keep dispatchCli as a thin orchestration layer that
delegates to these new helpers, then remove the eslint-disable complexity
comment to re-enable the linting rule. This will improve code maintainability
and keep the complexity of individual functions within acceptable limits.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3da3abae-63b4-4953-bbbe-df96d7723e16

📥 Commits

Reviewing files that changed from the base of the PR and between 1bf105b and 3884237.

📒 Files selected for processing (4)

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/lib/actions/sandbox/status.ts
• src/lib/cli/public-dispatch.ts

✅ Files skipped from review due to trivial changes (2)

• docs/reference/commands.mdx
• docs/reference/commands-nemohermes.mdx

[wscurran]

✨ Thanks for the proposed fix addressing the wrong-form nemoclaw status <name> usage with an actionable reorder suggestion. This proposes a way to clarify global versus sandbox-scoped status commands in help text, output headings, and reference documentation while preserving JSON output compatibility.

---

Related open issues:

• #754 feat(cli): clarify global vs sandbox-scoped status in help and UX

[cv]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cjagwani]

/ok to test 3c99b2d

[cv]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cjagwani]

/ok to test c61098b

[cv]

Maintainer disposition for the exact-head PR Review Advisor run 28548396812 at c61098b5a06b885955c1bb901868884c7f8d858b:

• The GPT advisor reports no required-before-merge item; all acceptance and security categories pass. Its architecture warning recommends extracting the two status-scope helpers from public-dispatch.ts. I am not expanding this focused UX PR with that mechanical extraction: the helpers are small, private, and specific to the dispatcher grammar boundary, while the full pre-commit source-shape/complexity gates and independent review pass. Moving them would add a cross-module validation/branding contract without changing behavior. The hotspot recommendation remains reasonable follow-up refactoring, but is not a correctness or security blocker here.
• The suggested alias runtime validation is complete under an isolated temporary HOME: nemohermes status alpha --json exits 2 and prints Run: nemohermes alpha status --json plus the branded global-JSON alternative.
• Nemotron was canceled by workflow concurrency before producing a final result, so it is not being counted as a pass. Exact-head CodeRabbit and two independent reviews are clean; the advisor-required live E2Es are running separately.

[github-actions]

Vitest E2E Target Results — ✅ All selected jobs passed

Run: 28548560495
Workflow ref: codex/pr5540-e2e-c61098b5
Requested targets: ubuntu-repo-cloud-openclaw
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, jetson-nvmap-gpu, and sandbox-rlimits-connect are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
live	✅ success

[cjagwani]

Approving.

Fixes #754 — all three acceptance criteria verified against the live CLI:

• Top-level help explains global vs sandbox-targeted commands ("Global commands inspect host-wide state; sandbox commands start with a sandbox name").
• status output labels its scope ("Global status (registered sandboxes and host services):" vs "Sandbox-scoped status for '':").
• Wrong-form status <name> prints a concrete reorder hint and exits 2, preserving --json in the suggestion.

Security review clean — flag-aware argv parsing, the sandbox name is echoed only into a display hint (never executed), no injection or content leak. CI is fully green: CodeRabbit, cli-tests, static-checks, and every E2E lane pass; the GPT-5.5 advisor reports no required-before-merge items (the helper-extraction hotspot is reasonable follow-up, not a blocker). Coverage includes the wrong-form, flag-ordering, and unknown-flag-precedence cases.

[cv]

Follow-up on the uncanceled exact-head dual-advisor rerun 28548785363: both GPT-5.5 and Nemotron completed with merge_as_is, high confidence, and 9/9 security categories passing.

Nemotron's non-blocking items are dispositioned as follows:

• The file-size/extraction recommendation matches the follow-up refactor already noted above; it is not a behavior or security blocker.
• Guiding status <valid-name> to <valid-name> status without consulting the registry is intentional. This is a grammar correction before any recovery/runtime side effect; existence is checked by the corrected command.
• The alleged metacharacter reflection in printUnknownSandboxOrCommand is not the described path: nameSuggestion is selected from registered allNames, not copied from the raw unknown cmd. The exact status path separately validates the user token and has a metacharacter regression.
• The registered-name test and additional docs callout are optional depth/discoverability suggestions. Existing routing tests prove the registry-independent grammar behavior, and the exact-head docs-writer audit found the source/reference coverage complete.

No further code change is warranted from these advisory items.

[github-actions]

Vitest E2E Target Results — ✅ All requested jobs passed

Run: 28548570748
Workflow ref: codex/pr5540-e2e-c61098b5
Requested targets: (default — all supported)
Requested jobs: sandbox-operations
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
sandbox-operations	✅ success