Reference

CLI Selection Guide

View as Markdown

NemoClaw uses two host-side CLIs. Use nemoclaw for NemoClaw-managed workflows. Use openshell when you need a lower-level OpenShell operation that NemoClaw intentionally exposes.

Rule of Thumb

If the task changes how NemoClaw creates, rebuilds, preserves, or configures a sandbox, start with nemoclaw.

If the task inspects or changes the live OpenShell gateway, TUI, raw policy, port forwarding, inference route, or sandbox file transfer, use openshell.

Do not create or recreate NemoClaw-managed sandboxes directly with openshell sandbox create unless you intend to manage OpenShell yourself. Run nemoclaw onboard afterward if you need to return to a NemoClaw-managed environment.

Use nemoclaw For NemoClaw Workflows

Use nemoclaw for operations where NemoClaw adds product-specific state, safety checks, backup behavior, credential handling, or OpenClaw configuration.

  • Install, onboard, or recreate a NemoClaw sandbox:

    1$ nemoclaw onboard
    2$ nemoclaw onboard --resume --recreate-sandbox

  • List, connect to, check, or delete NemoClaw-managed sandboxes:

    1$ nemoclaw list
    2$ nemoclaw my-assistant connect
    3$ nemoclaw my-assistant status
    4$ nemoclaw my-assistant logs --follow
    5$ nemoclaw my-assistant destroy

  • Rebuild or upgrade while preserving workspace state:

    1$ nemoclaw my-assistant rebuild
    2$ nemoclaw upgrade-sandboxes --check

  • Snapshot, restore, or mount sandbox state:

    1$ nemoclaw my-assistant snapshot create --name before-change
    2$ nemoclaw my-assistant snapshot restore before-change
    3$ nemoclaw my-assistant share mount

  • Add or remove NemoClaw policy presets:

    1$ nemoclaw my-assistant policy-add pypi --yes
    2$ nemoclaw my-assistant policy-list
    3$ nemoclaw my-assistant policy-remove pypi --yes

  • Manage NemoClaw messaging channels, credentials, diagnostics, and cleanup:

    1$ nemoclaw my-assistant channels add slack
    2$ nemoclaw credentials list
    3$ nemoclaw credentials reset nvidia-prod
    4$ nemoclaw debug --sandbox my-assistant
    5$ nemoclaw gc --dry-run

Use openshell For OpenShell Operations

Use openshell when the docs explicitly call for a live OpenShell gateway operation or when you need a lower-level view beneath the NemoClaw wrapper.

  • Open the OpenShell TUI for network approvals and live activity:

    1$ openshell term

  • Manage dashboard or service port forwards:

    1$ openshell forward start --background <port> <sandbox-name>
    2$ openshell forward list

  • Inspect the underlying sandbox state:

    1$ openshell sandbox list
    2$ openshell sandbox get <sandbox-name>
    3$ openshell logs <sandbox-name> --tail

  • Run one-off commands or move files without starting a NemoClaw chat session:

    1$ openshell sandbox exec -n <sandbox-name> -- ls -la /sandbox
    2$ openshell sandbox upload <sandbox-name> ./local-file /sandbox/
    3$ openshell sandbox download <sandbox-name> /sandbox/output ./output

  • Inspect or replace raw OpenShell policy:

    1$ openshell policy get --full <sandbox-name> > live-policy.yaml
    2$ openshell policy update <sandbox-name> --add-endpoint api.example.com:443:read-only:rest:enforce
    3$ openshell policy set --policy live-policy.yaml <sandbox-name>

openshell policy update merges specific endpoint and rule changes into the live sandbox policy. openshell policy set replaces the live policy with the file you provide. For normal NemoClaw network access changes, prefer nemoclaw <name> policy-add so NemoClaw preserves presets and records the change for rebuilds.

Common Decisions

This section covers common decisions when using the NemoClaw CLI and the OpenShell CLI.

First Setup or Full Recreate

Use nemoclaw onboard. It starts the OpenShell gateway when needed, registers providers, builds the OpenClaw sandbox image, applies NemoClaw policy choices, and creates the sandbox.

Avoid running openshell gateway start --recreate or openshell sandbox create directly for NemoClaw-managed sandboxes. Those commands do not update NemoClaw’s registry, session metadata, workspace-preservation flow, or OpenClaw-specific configuration.

Connect to the Sandbox

Use nemoclaw <name> connect for an interactive NemoClaw sandbox shell. It waits for readiness, handles stale SSH host keys after gateway restarts, and prints agent-specific hints.

Use openshell sandbox connect <name> only when you intentionally want the raw OpenShell connection path.

For a one-off command, use openshell sandbox exec instead of opening an interactive shell.

1$ openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log

Check Health or Logs

Use nemoclaw <name> status and nemoclaw <name> logs first. They combine NemoClaw registry data, OpenShell state, OpenClaw process health, inference health, policy details, and messaging-channel warnings.

Use openshell sandbox list, openshell sandbox get, or openshell logs when debugging lower-level OpenShell behavior.

Approve Blocked Network Requests

Use openshell term. The OpenShell TUI owns live network activity and operator approval prompts.

Approved endpoints are session-scoped unless you also add them to the policy through a NemoClaw preset or raw OpenShell policy update.

Change Models or Providers

Use the NemoClaw commands for model or provider inspection and switches so the OpenShell route and the running agent config stay consistent:

1$ nemoclaw inference get
2$ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b

For Hermes sandboxes, use the alias; it updates the route and /sandbox/.hermes/config.yaml without a rebuild or restart:

1$ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini

For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently:

1$ nemoclaw onboard --resume --recreate-sandbox

Verify either path with:

1$ nemoclaw <name> status

Update Network Policy

Use nemoclaw <name> policy-add or policy-remove for NemoClaw presets and custom preset files. NemoClaw merges the new policy with the live policy and reapplies presets during rebuilds.

Use openshell policy update for precise live endpoint or REST rule changes. Use openshell policy get --full and openshell policy set only when you need to edit and replace the raw policy file.

Move Workspace Files

Use nemoclaw <name> snapshot create, snapshot restore, or share mount for normal workspace preservation and editing.

Use openshell sandbox upload and openshell sandbox download for manual file copies when you need exact control over source and destination paths.