feat(cli): add --json flag to nemoclaw list by dumko2001 · Pull Request #182 · NVIDIA/NemoClaw

dumko2001 · 2026-03-17T10:23:42Z

Rationale

Users and automated tools need a way to list sandboxes in a structured, machine-readable format for integration and scripting.

Changes

Added a --json flag to the nemoclaw list command that outputs the sandbox registry and default sandbox as a JSON object.

Verification Results

Automated Tests: Passed all 52 core tests via npm test.
Manual Audit: Verified JSON output format and structure.
Security Review: Verified no sensitive data leaks and correct permission enforcement.

Leading Standards

This PR follows the project's 'First Principles' approach, prioritizing deterministic behavior and zero-trust security defaults.

Summary by CodeRabbit

New Features
- The list command now supports a --json flag to output sandbox information as pretty-formatted JSON.
- --help / -h now shows list-specific usage and options.
Bug Fixes
- Unknown options are detected and produce a clear error message with usage guidance; existing human-readable listing remains unchanged.

cv · 2026-03-21T19:29:09Z

Hey @dumko2001, a --json flag for would be super useful for scripting and automation. Main has moved forward a lot though — mind rebasing so we can evaluate this with the latest code?

coderabbitai · 2026-03-21T21:41:39Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a4816d08-a61e-40d6-a772-624889bed078

📥 Commits

Reviewing files that changed from the base of the PR and between eee0cc3 and 97c33ef.

📒 Files selected for processing (1)

bin/nemoclaw.js

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

bin/nemoclaw.js

📝 Walkthrough

Walkthrough

listSandboxes in bin/nemoclaw.js now accepts an args array, validates allowed flags (--json, --help, -h), supports --json output of { sandboxes, defaultSandbox }, provides a list-specific --help/-h, and returns early on help, JSON, or invalid options.

Changes

Cohort / File(s)	Summary
CLI list implementation `bin/nemoclaw.js`	Changed `listSandboxes()` signature to `listSandboxes(args = [])`; added args allowlist validation, `--help`/`-h` handling with list-specific usage, `--json` mode which fetches `{ sandboxes, defaultSandbox }` from the registry and prints pretty JSON, and early returns for help/JSON/invalid flags. Also updated top-level `nemoclaw list` dispatcher to forward parsed CLI `args` and updated help text to mention `--json`.

Sequence Diagram(s)

sequenceDiagram
  participant User as "User (CLI)"
  participant Nemoclaw as "bin/nemoclaw (list cmd)"
  participant Registry as "Registry API"
  participant Console as "Stdout / Exit"

  User->>Nemoclaw: Run `nemoclaw list` with args
  Nemoclaw->>Nemoclaw: Validate args against allowlist (--json,--help,-h)
  alt invalid args
    Nemoclaw->>Console: Print error + usage
    Nemoclaw->>Console: Exit non-zero
  else help requested
    Nemoclaw->>Console: Print list-specific help
    Nemoclaw->>Console: Exit 0
  else --json present
    Nemoclaw->>Registry: Fetch { sandboxes, defaultSandbox }
    Registry-->>Nemoclaw: Return data
    Nemoclaw->>Console: Print pretty JSON
    Nemoclaw->>Console: Exit 0
  else no flags
    Nemoclaw->>Registry: Fetch sandboxes (existing flow)
    Registry-->>Nemoclaw: Return data
    Nemoclaw->>Console: Print human-readable list
    Nemoclaw->>Console: Exit 0
  end

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A tiny flag hopped into place,
JSON or words — both find their space,
I fetched the list, then gave a cheer,
Pretty prints or humans near. 🥕✨

🚥 Pre-merge checks | ✅ 2 | ❌ 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 (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a `--json` flag to the nemoclaw list command, which is the primary focus of 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

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

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@bin/nemoclaw.js`:
- Around line 252-259: The CLI's new --json flag in listSandboxes is not
documented in the help output; update the CLI help text that prints the
"nemoclaw list" usage (the same help generator shown by `nemoclaw help`) to
include the --json option and a short description (e.g., "Output list as JSON");
ensure the help entry references the --json flag and matches the behavior
implemented in listSandboxes so users can discover the flag.
- Around line 252-259: The listSandboxes function currently ignores any flags
other than "--json", which can hide typos; update listSandboxes to validate
args: parse args and allow only the known flag "--json" (and optionally "--help"
if desired), and if any unknown flag is present log an error or throw (e.g., use
console.error and process.exit(1)) so the CLI fails fast; locate the function
listSandboxes and add a validation step that iterates args, accepts only the
allowed flags, and rejects everything else before calling
registry.listSandboxes() or printing JSON.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5a0115b8-5aff-48b0-a294-bc7034dbbad5

📥 Commits

Reviewing files that changed from the base of the PR and between 255e606 and eee0cc3.

📒 Files selected for processing (1)

bin/nemoclaw.js

dumko2001 · 2026-03-24T09:01:21Z

@cv rebased

…ifecycle cleanup (NVIDIA#182) * fix(security): add SSH session token expiry, connection limits, and lifecycle cleanup Closes NVIDIA#22 SSH session tokens previously had no TTL and remained valid indefinitely. This adds configurable token expiry (default 24h), per-token (10) and per-sandbox (20) concurrent connection limits, session cleanup on sandbox deletion, and a background reaper for expired/revoked sessions. * fix(security): lower per-token concurrent connection limit from 10 to 3 --------- Co-authored-by: John Myers <johntmyers@users.noreply.github.com>

wscurran · 2026-04-21T05:37:35Z

Thanks for this. bin/nemoclaw.js is now a thin shim that delegates to the TypeScript CLI — the list command lives in the TypeScript source. This diff no longer applies, and the --json flag for nemoclaw list hasn't been implemented in the TypeScript rewrite either, so there's still a real gap here.

A new PR adding --json to the TypeScript list command would be a welcome contribution. Feel free to reopen or open a new PR targeting the TypeScript source.

@dumko2001

## Summary This adds machine-readable `nemoclaw list --json` output while preserving the existing human-readable list view. It extracts structured inventory generation from the list renderer so future CLI work can reuse the same inventory path. This carries forward the earlier `list --json` proposal from #182 by @dumko2001 (Sidharth Rajmohan). ## Changes - Add `getSandboxInventory()` and `renderSandboxInventoryText()` in `src/lib/inventory-commands.ts` so the sandbox inventory can be reused for both text and JSON output. - Update `src/nemoclaw.ts` so `nemoclaw list` accepts `--json`, emits pretty JSON to stdout, and rejects unsupported `list` flags with list-specific usage guidance. - Add tests in `src/lib/inventory-commands.test.ts` and `test/cli.test.ts` for empty and populated JSON output plus invalid `list` arguments. - Update `docs/reference/commands.md` and regenerate `.agents/skills/nemoclaw-user-reference/references/commands.md` for `nemoclaw list --json`. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [x] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Verification - [x] `npx prek run --all-files` passes - [x] `npm test` passes - [x] 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) - [ ] 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) ## AI Disclosure - [x] AI-assisted — tool: OpenAI Codex --- Signed-off-by: Carlos Villela <cvillela@nvidia.com>  ## Summary by CodeRabbit * **New Features** * Added `--json` flag to `nemoclaw list` command for machine-readable output containing schema version, default sandbox, recovery metadata, and sandbox inventory. * Added `--help`/`-h` support for list command. * **Documentation** * Updated command documentation with new `--json` flag specification and usage examples. * **Tests** * Added comprehensive test coverage for JSON output and argument validation.  Signed-off-by: Carlos Villela <cvillela@nvidia.com>

wscurran added enhancement: feature labels Mar 19, 2026

dumko2001 force-pushed the fix/h12-list-json-flag branch from 06a13c6 to eee0cc3 Compare March 21, 2026 21:41

coderabbitai Bot reviewed Mar 21, 2026

View reviewed changes

Comment thread bin/nemoclaw.js

dumko2001 added 2 commits March 24, 2026 14:13

feat(cli): add --json flag to nemoclaw list

c48c702

feat(cli): validate nemoclaw list flags and update help

97c33ef

dumko2001 force-pushed the fix/h12-list-json-flag branch from eee0cc3 to 97c33ef Compare March 24, 2026 08:51

prekshivyas mentioned this pull request Mar 25, 2026

refactor(cli): migrate to oclif + TypeScript #909

Closed

8 tasks

wscurran mentioned this pull request Mar 25, 2026

feat(cli): add --json output for list and status commands #753

Closed

cv mentioned this pull request Mar 25, 2026

refactor(cli): shell consolidation, TypeScript migration & oclif #924

Open

wscurran closed this Apr 21, 2026

cv mentioned this pull request Apr 21, 2026

feat(cli): add nemoclaw list --json #2147

Merged

13 tasks

wscurran added area: cli Command line interface, flags, terminal UX, or output feature PR adds or expands user-visible functionality and removed NemoClaw CLI labels Jun 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add --json flag to nemoclaw list#182

feat(cli): add --json flag to nemoclaw list#182
dumko2001 wants to merge 2 commits into
NVIDIA:mainfrom
dumko2001:fix/h12-list-json-flag

dumko2001 commented Mar 17, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

cv commented Mar 21, 2026

Uh oh!

coderabbitai Bot commented Mar 21, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

dumko2001 commented Mar 24, 2026

Uh oh!

wscurran commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dumko2001 commented Mar 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale

Changes

Verification Results

Leading Standards

Summary by CodeRabbit

Uh oh!

cv commented Mar 21, 2026

Uh oh!

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

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dumko2001 commented Mar 24, 2026

Uh oh!

wscurran commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dumko2001 commented Mar 17, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Mar 21, 2026 •

edited

Loading