Skip to content

docs(policy): fix openshell policy set CLI examples#848

Merged
cv merged 3 commits into
NVIDIA:mainfrom
HagegeR:update-policy-docs
Apr 14, 2026
Merged

docs(policy): fix openshell policy set CLI examples#848
cv merged 3 commits into
NVIDIA:mainfrom
HagegeR:update-policy-docs

Conversation

@HagegeR

@HagegeR HagegeR commented Mar 25, 2026

Copy link
Copy Markdown
Contributor

Summary

Updates all openshell policy set examples to match the current CLI: openshell policy set --policy <policy-file> <sandbox-name> (instead of the outdated openshell policy set <policy-file> form).

Related Issue

N/A (documentation alignment with OpenShell CLI).

Changes

  • README.md — dynamic policy row in the network-policy table
  • docs/network-policy/customize-network-policy.md — apply policy and preset examples
  • docs/reference/network-policies.md — running-sandbox policy update example
  • .agents/skills/nemoclaw-manage-policy/SKILL.md — same examples for agent workflows

Type of Change

  • Doc only. Prose changes without code sample modifications.

Checklist

  • I have read and followed the contributing guide.
  • I have read and followed the style guide.
  • No secrets, API keys, or credentials committed.
  • Doc pages updated for any user-facing behavior changes.

Signed-off-by: Ruben Hagege rhagege@nvidia.com

@coderabbitai

coderabbitai Bot commented Mar 25, 2026

Copy link
Copy Markdown
Contributor
📝 Walkthrough

Walkthrough

Documentation updates in three files standardize the openshell policy set CLI examples to require an explicit --policy <policy-file> flag and a <sandbox-name> argument instead of a single positional policy-file parameter.

Changes

Cohort / File(s) Summary
CLI Documentation Updates
docs/network-policy/customize-network-policy.md, docs/reference/network-policies.md, .agents/skills/nemoclaw-user-manage-policy/SKILL.md
Rewrote openshell policy set examples to use openshell policy set --policy <policy-file> <sandbox-name> (replacing prior positional <policy-file> usage). Applied consistently across examples and presets.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🐰
A flag I found beneath a log,
--policy tucked beside the frog,
Three docs hopped in step and song,
Clearer commands to carry on,
—a rabbit's cheer for docs made strong 🥕

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and specifically describes the main change: fixing OpenShell CLI examples in documentation for the 'policy set' command.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ 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 coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/network-policy/customize-network-policy.md (1)

25-26: 🛠️ Refactor suggestion | 🟠 Major

Use active voice.

Line 25 uses passive constructions. Rewrite to active voice per the style guide.

✍️ Suggested rewrite
-The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell).
-NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI.
+NemoClaw defines the sandbox policy in a declarative YAML file, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime.
+You can make static policy changes that persist across restarts or apply dynamic updates to a running sandbox through the OpenShell CLI.

As per coding guidelines, active voice is required for all docs/** files.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/network-policy/customize-network-policy.md` around lines 25 - 26,
Replace the passive sentence "The sandbox policy is defined in a declarative
YAML file in the NemoClaw repository and enforced at runtime by NVIDIA
OpenShell." with an active-voice version such as "NemoClaw defines the sandbox
policy in a declarative YAML file in the repository, and NVIDIA OpenShell
enforces it at runtime." Leave the following sentence about static and dynamic
updates as-is (it is already active) and ensure the file under docs/** uses the
active phrasing.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.agents/skills/nemoclaw-manage-policy/SKILL.md:
- Line 156: Update the example CLI invocation in SKILL.md so it matches the
implemented behavior by adding the required --wait flag to the command;
specifically change the shown command string (the example using openshell policy
set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox) to
include --wait before the target sandbox name so the call to openshell policy
set includes --wait.
- Line 123: Update the documented command example that currently reads "$
openshell policy set --policy <policy-file> <sandbox-name>" so it includes the
required --wait flag (as exercised by test/policies.test.js); edit the SKILL.md
command example to show the --wait flag in the position the implementation
expects so the docs match the real behavior.

In `@docs/network-policy/customize-network-policy.md`:
- Line 84: Update the example CLI invocation to include the required --wait flag
so it matches the implementation in the policies.js handler for the "policy set"
command: change the command to use --policy <policy-file> --wait <sandbox-name>
(i.e., insert --wait between --policy and the sandbox name) so the docs reflect
the actual behavior implemented in the policies.js "policy set" handler.
- Line 117: The example CLI invocation for the policy preset is missing the
required --wait flag; update the command shown (the openshell policy set
invocation that references nemoclaw-blueprint/policies/presets/pypi.yaml and
my-sandbox) to include --wait so it matches the implementation and behavior of
the policy set command.

In `@docs/reference/network-policies.md`:
- Line 141: Update the documented CLI example for the "openshell policy set"
command to include the required --wait flag between --policy and the sandbox
name (i.e., change "$ openshell policy set --policy <policy-file>
<sandbox-name>" to include "--wait" after "--policy"). This matches the CLI
implementation that expects the --wait flag for the policy set operation and
ensures the docs reflect the actual behavior of the "openshell policy set"
command.

In `@README.md`:
- Line 232: The README's CLI example for dynamic policy application omits the
required --wait flag used by the implementation; update the command string in
the table to match the behavior in bin/lib/policies.js (around the handler that
parses the --policy option) by inserting --wait between --policy <policy-file>
and <sandbox-name> so the documented invocation mirrors the actual CLI argument
order and requirement.

---

Outside diff comments:
In `@docs/network-policy/customize-network-policy.md`:
- Around line 25-26: Replace the passive sentence "The sandbox policy is defined
in a declarative YAML file in the NemoClaw repository and enforced at runtime by
NVIDIA OpenShell." with an active-voice version such as "NemoClaw defines the
sandbox policy in a declarative YAML file in the repository, and NVIDIA
OpenShell enforces it at runtime." Leave the following sentence about static and
dynamic updates as-is (it is already active) and ensure the file under docs/**
uses the active phrasing.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4b1ea484-bd39-434a-93da-9379f59f30a6

📥 Commits

Reviewing files that changed from the base of the PR and between 93a475a and 92bb317.

📒 Files selected for processing (4)
  • .agents/skills/nemoclaw-manage-policy/SKILL.md
  • README.md
  • docs/network-policy/customize-network-policy.md
  • docs/reference/network-policies.md

@@ -120,7 +120,7 @@ Follow the same format as the baseline policy in `nemoclaw-blueprint/policies/op
Use the OpenShell CLI to apply the policy update:

```console
$ openshell policy set <policy-file>
$ openshell policy set --policy <policy-file> <sandbox-name>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify the openshell policy set command interface

# Check the implementation that builds this command
rg -nC5 'buildPolicySetCommand' bin/lib/policies.js

# Check if there are tests that validate the command format
rg -nC3 'policy set.*--wait' test/

Repository: NVIDIA/NemoClaw

Length of output: 2212


Update documented command syntax to include required --wait flag.

The documented command in line 123 is missing the --wait flag that is required by the actual implementation. Tests in test/policies.test.js confirm the correct format includes this flag.

Fix
-$ openshell policy set --policy <policy-file> <sandbox-name>
+$ openshell policy set --policy <policy-file> --wait <sandbox-name>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$ openshell policy set --policy <policy-file> <sandbox-name>
$ openshell policy set --policy <policy-file> --wait <sandbox-name>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/nemoclaw-manage-policy/SKILL.md at line 123, Update the
documented command example that currently reads "$ openshell policy set --policy
<policy-file> <sandbox-name>" so it includes the required --wait flag (as
exercised by test/policies.test.js); edit the SKILL.md command example to show
the --wait flag in the position the implementation expects so the docs match the
real behavior.


```console
$ openshell policy set nemoclaw-blueprint/policies/presets/pypi.yaml
$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Missing --wait flag in CLI command.

The concrete preset example is missing the --wait flag required by the actual implementation.

🐛 Proposed fix
-$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox
+$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml --wait my-sandbox
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox
$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml --wait my-sandbox
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/nemoclaw-manage-policy/SKILL.md at line 156, Update the
example CLI invocation in SKILL.md so it matches the implemented behavior by
adding the required --wait flag to the command; specifically change the shown
command string (the example using openshell policy set --policy
nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox) to include --wait
before the target sandbox name so the call to openshell policy set includes
--wait.


```console
$ openshell policy set <policy-file>
$ openshell policy set --policy <policy-file> <sandbox-name>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Missing --wait flag in CLI command.

The documented command syntax does not match the actual implementation in bin/lib/policies.js:51-60. The --wait flag is required between --policy and the sandbox name.

🐛 Proposed fix
-$ openshell policy set --policy <policy-file> <sandbox-name>
+$ openshell policy set --policy <policy-file> --wait <sandbox-name>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$ openshell policy set --policy <policy-file> <sandbox-name>
$ openshell policy set --policy <policy-file> --wait <sandbox-name>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/network-policy/customize-network-policy.md` at line 84, Update the
example CLI invocation to include the required --wait flag so it matches the
implementation in the policies.js handler for the "policy set" command: change
the command to use --policy <policy-file> --wait <sandbox-name> (i.e., insert
--wait between --policy and the sandbox name) so the docs reflect the actual
behavior implemented in the policies.js "policy set" handler.


```console
$ openshell policy set nemoclaw-blueprint/policies/presets/pypi.yaml
$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Missing --wait flag in CLI command.

The concrete preset example is missing the --wait flag required by the actual implementation.

🐛 Proposed fix
-$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml my-sandbox
+$ openshell policy set --policy nemoclaw-blueprint/policies/presets/pypi.yaml --wait my-sandbox
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/network-policy/customize-network-policy.md` at line 117, The example CLI
invocation for the policy preset is missing the required --wait flag; update the
command shown (the openshell policy set invocation that references
nemoclaw-blueprint/policies/presets/pypi.yaml and my-sandbox) to include --wait
so it matches the implementation and behavior of the policy set command.


```console
$ openshell policy set <policy-file>
$ openshell policy set --policy <policy-file> <sandbox-name>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Missing --wait flag in CLI command.

The documented command syntax does not match the actual implementation in bin/lib/policies.js:51-60. The --wait flag is required between --policy and the sandbox name.

🐛 Proposed fix
-$ openshell policy set --policy <policy-file> <sandbox-name>
+$ openshell policy set --policy <policy-file> --wait <sandbox-name>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$ openshell policy set --policy <policy-file> <sandbox-name>
$ openshell policy set --policy <policy-file> --wait <sandbox-name>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/network-policies.md` at line 141, Update the documented CLI
example for the "openshell policy set" command to include the required --wait
flag between --policy and the sandbox name (i.e., change "$ openshell policy set
--policy <policy-file> <sandbox-name>" to include "--wait" after "--policy").
This matches the CLI implementation that expects the --wait flag for the policy
set operation and ensures the docs reflect the actual behavior of the "openshell
policy set" command.

Comment thread README.md Outdated
|--------|-----|-------|
| **Static** | Edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. | Persists across restarts. |
| **Dynamic** | Run `openshell policy set <policy-file>` on a running sandbox. | Session only; resets on restart. |
| **Dynamic** | Run `openshell policy set --policy <policy-file> <sandbox-name>` on a running sandbox. | Session only; resets on restart. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Missing --wait flag in CLI command.

The documented command syntax does not match the actual implementation in bin/lib/policies.js:51-60. The --wait flag is required between --policy and the sandbox name.

🐛 Proposed fix
-| **Dynamic** | Run `openshell policy set --policy <policy-file> <sandbox-name>` on a running sandbox. | Session only; resets on restart. |
+| **Dynamic** | Run `openshell policy set --policy <policy-file> --wait <sandbox-name>` on a running sandbox. | Session only; resets on restart. |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| **Dynamic** | Run `openshell policy set --policy <policy-file> <sandbox-name>` on a running sandbox. | Session only; resets on restart. |
| **Dynamic** | Run `openshell policy set --policy <policy-file> --wait <sandbox-name>` on a running sandbox. | Session only; resets on restart. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 232, The README's CLI example for dynamic policy
application omits the required --wait flag used by the implementation; update
the command string in the table to match the behavior in bin/lib/policies.js
(around the handler that parses the --policy option) by inserting --wait between
--policy <policy-file> and <sandbox-name> so the documented invocation mirrors
the actual CLI argument order and requirement.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (2)
.agents/skills/nemoclaw-manage-policy/SKILL.md (1)

123-123: ⚠️ Potential issue | 🔴 Critical

Update both SKILL examples to the implemented policy set syntax.

These two commands also miss the required --wait argument.
Per the provided implementation context (bin/lib/policies.js, buildPolicySetCommand), the expected format is openshell policy set --policy <policy-file> --wait <sandbox-name>.

Also applies to: 156-156

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/nemoclaw-manage-policy/SKILL.md at line 123, Update both
SKILL examples to match the implemented policy set CLI syntax used by
buildPolicySetCommand: change the command to include the --policy flag and the
required --wait argument, i.e., use the form "openshell policy set --policy
<policy-file> --wait <sandbox-name>" in the SKILL.md examples referenced (lines
near the current examples).
docs/network-policy/customize-network-policy.md (1)

84-84: ⚠️ Potential issue | 🔴 Critical

Include the required --wait flag in both policy set examples.

Both commands still omit --wait, but the implementation in bin/lib/policies.js (buildPolicySetCommand, Line 85-86 in the provided snippet) constructs openshell policy set --policy <policy-file> --wait <sandbox-name>.
Please update both examples to match runtime behavior.

Also applies to: 117-117

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/network-policy/customize-network-policy.md` at line 84, Docs examples
for "policy set" omit the required --wait flag; update both examples at the two
occurrences to match runtime behavior by adding --wait so they read "openshell
policy set --policy <policy-file> --wait <sandbox-name>". Reference
buildPolicySetCommand in bin/lib/policies.js which constructs the command with
--wait to ensure docs and implementation are consistent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In @.agents/skills/nemoclaw-manage-policy/SKILL.md:
- Line 123: Update both SKILL examples to match the implemented policy set CLI
syntax used by buildPolicySetCommand: change the command to include the --policy
flag and the required --wait argument, i.e., use the form "openshell policy set
--policy <policy-file> --wait <sandbox-name>" in the SKILL.md examples
referenced (lines near the current examples).

In `@docs/network-policy/customize-network-policy.md`:
- Line 84: Docs examples for "policy set" omit the required --wait flag; update
both examples at the two occurrences to match runtime behavior by adding --wait
so they read "openshell policy set --policy <policy-file> --wait
<sandbox-name>". Reference buildPolicySetCommand in bin/lib/policies.js which
constructs the command with --wait to ensure docs and implementation are
consistent.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9de1378a-ec59-42fb-a63d-1c3a91328edc

📥 Commits

Reviewing files that changed from the base of the PR and between 92bb317 and 27611e8.

📒 Files selected for processing (2)
  • .agents/skills/nemoclaw-manage-policy/SKILL.md
  • docs/network-policy/customize-network-policy.md

@wscurran

Copy link
Copy Markdown
Contributor

✨ Thanks for submitting this PR with a detailed summary, it proposes a fix to improve the documentation of NemoClaw, which could enhance the user experience.

@HagegeR HagegeR force-pushed the update-policy-docs branch from 27611e8 to 416467c Compare April 12, 2026 14:10
HagegeR added 2 commits April 13, 2026 09:11
Use \`openshell policy set --policy <file> <sandbox-name>\` in README, policy
docs, reference, and the nemoclaw-manage-policy skill so examples match the CLI.
@HagegeR HagegeR force-pushed the update-policy-docs branch from 416467c to bca6c0a Compare April 13, 2026 06:12
@prekshivyas

Copy link
Copy Markdown
Contributor

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Apr 14, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

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.

@cv cv merged commit f93e4f3 into NVIDIA:main Apr 14, 2026
11 of 12 checks passed
ColinM-sys pushed a commit to ColinM-sys/NemoClaw that referenced this pull request Apr 14, 2026
## Summary

Updates all `openshell policy set` examples to match the current CLI:
**`openshell policy set --policy <policy-file> <sandbox-name>`**
(instead of the outdated `openshell policy set <policy-file>` form).

## Related Issue

N/A (documentation alignment with OpenShell CLI).

## Changes

- `README.md` — dynamic policy row in the network-policy table
- `docs/network-policy/customize-network-policy.md` — apply policy and
preset examples
- `docs/reference/network-policies.md` — running-sandbox policy update
example
- `.agents/skills/nemoclaw-manage-policy/SKILL.md` — same examples for
agent workflows

## Type of Change

- [x] Doc only. Prose changes without code sample modifications.

## Checklist

- [x] I have read and followed the [contributing
guide](CONTRIBUTING.md).
- [x] I have read and followed the [style guide](docs/CONTRIBUTING.md).
- [x] No secrets, API keys, or credentials committed.
- [x] Doc pages updated for any user-facing behavior changes.

Signed-off-by: Ruben Hagege <rhagege@nvidia.com>

---------

Co-authored-by: Prekshi Vyas <34834085+prekshivyas@users.noreply.github.com>
Signed-off-by: ColinM-sys <cmcdonough@50words.com>
@wscurran wscurran added area: install Install, setup, prerequisites, or uninstall flow area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance and removed priority: high labels Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation, examples, guides, or docs build area: install Install, setup, prerequisites, or uninstall flow area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow chore Build, CI, dependency, or tooling maintenance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants