From 4efdf9f9dc29c204ed07a6c4d425b3061967e62e Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Thu, 21 May 2026 04:28:56 +0000 Subject: [PATCH 1/2] docs(commands): document nemoclaw internal:* command family (#3782) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an Internal Commands section to docs/reference/commands.mdx listing the nine `nemoclaw internal ` commands. The commands are already registered as hidden in oclif (static hidden = true), so they do not appear in `nemoclaw --help`, but they were not documented anywhere — including the CLI Reference — so operators who became aware of them had no canonical description of what they do or who calls them. The new section maps each command to its calling wrapper (uninstall.sh, fix-coredns.sh, setup-dns-proxy.sh, npm-link-or-shim.sh, or install.sh planning steps) and a one-line purpose, and states up front that the internal family is not part of the supported public CLI surface and that flags/output/exit codes may change without notice. Signed-off-by: Tinson Lai --- docs/reference/commands.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 373b831e8d..710f7ef110 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -1123,6 +1123,25 @@ Use the hosted `curl … | bash` form only when the CLI is broken or already par | **Robustness** | Requires the npm package to be discoverable so the CLI can find the local script. | Works even if the `nemoclaw` CLI is missing, broken, or partially uninstalled. | | **Recommended for** | Routine uninstalls. | Recovery when the CLI is unavailable. | +## Internal Commands + +NemoClaw registers a small family of `nemoclaw internal ` commands that the installer, uninstaller, and a few wrapper scripts (`uninstall.sh`, `scripts/npm-link-or-shim.sh`, `scripts/fix-coredns.sh`, `scripts/setup-dns-proxy.sh`) invoke under the hood. +They are intentionally omitted from `nemoclaw --help` via `static hidden = true` and are not part of the supported public CLI surface. +Their flags, output, and exit codes may change without notice between releases. +Operators should not invoke them directly; use the user-facing commands or wrapper scripts above instead. + +| Command | Caller | Purpose | +|---|---|---| +| `nemoclaw internal dev npm-link-or-shim` | `scripts/npm-link-or-shim.sh` | Run `npm link`, falling back to a user-local NemoClaw development shim. | +| `nemoclaw internal dns fix-coredns` | `scripts/fix-coredns.sh` | Patch CoreDNS to use a non-loopback upstream resolver. | +| `nemoclaw internal dns setup-proxy` | `scripts/setup-dns-proxy.sh` | Configure the DNS forwarder bridge inside a sandbox pod. | +| `nemoclaw internal installer plan` | `install.sh` planning step | Build a deterministic installer plan from environment and probe inputs without applying it. | +| `nemoclaw internal installer resolve-release-tag` | `install.sh` planning step | Resolve the installer ref using the same precedence as `install.sh`. | +| `nemoclaw internal installer normalize-env` | `install.sh` planning step | Normalize installer ref and provider environment values without applying any installation changes. | +| `nemoclaw internal uninstall plan` | `uninstall.sh` planning step | Build a deterministic uninstall plan without applying it. | +| `nemoclaw internal uninstall classify-shim` | `uninstall.sh` planning step | Classify whether a NemoClaw shim path is safe to remove. | +| `nemoclaw internal uninstall run-plan` | `uninstall.sh` | Execute the host-side uninstall plan. | + ## Environment Variables NemoClaw reads the following environment variables to configure service ports, onboarding behavior, and lifecycle defaults. From f20f89e0953e9e570571ff0f15530441b2a9cc1b Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Thu, 21 May 2026 04:35:29 +0000 Subject: [PATCH 2/2] docs(commands): correct internal:* caller mapping per Codex review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous version of the Internal Commands section attributed three `nemoclaw internal installer ...` commands to `install.sh` planning steps, but install.sh and scripts/install.sh keep their own Bash implementations (resolve_release_tag, resolve_installer_version) and do not invoke the TS planning commands. Similarly, `internal uninstall plan` and `internal uninstall classify-shim` are not invoked by any shell script — the runtime path calls the underlying lib functions directly via run-plan. Rewrite each of those rows as an internal planning/inspection helper with a brief note that they expose the logic for external tooling and inspection but are not part of the active runtime flow. Also switch the imperative voice ("Operators should not invoke them directly") to the second-person form ("You should not invoke these directly") per docs style. Signed-off-by: Tinson Lai --- docs/reference/commands.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 710f7ef110..252584b027 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -1125,21 +1125,21 @@ Use the hosted `curl … | bash` form only when the CLI is broken or already par ## Internal Commands -NemoClaw registers a small family of `nemoclaw internal ` commands that the installer, uninstaller, and a few wrapper scripts (`uninstall.sh`, `scripts/npm-link-or-shim.sh`, `scripts/fix-coredns.sh`, `scripts/setup-dns-proxy.sh`) invoke under the hood. +NemoClaw registers a small family of `nemoclaw internal ` commands that wrapper scripts (`uninstall.sh`, `scripts/npm-link-or-shim.sh`, `scripts/fix-coredns.sh`, `scripts/setup-dns-proxy.sh`) invoke under the hood, plus a few internal planning and inspection helpers that mirror logic used elsewhere in the CLI. They are intentionally omitted from `nemoclaw --help` via `static hidden = true` and are not part of the supported public CLI surface. Their flags, output, and exit codes may change without notice between releases. -Operators should not invoke them directly; use the user-facing commands or wrapper scripts above instead. +You should not invoke these directly; use the user-facing commands or wrapper scripts above instead. | Command | Caller | Purpose | |---|---|---| | `nemoclaw internal dev npm-link-or-shim` | `scripts/npm-link-or-shim.sh` | Run `npm link`, falling back to a user-local NemoClaw development shim. | | `nemoclaw internal dns fix-coredns` | `scripts/fix-coredns.sh` | Patch CoreDNS to use a non-loopback upstream resolver. | | `nemoclaw internal dns setup-proxy` | `scripts/setup-dns-proxy.sh` | Configure the DNS forwarder bridge inside a sandbox pod. | -| `nemoclaw internal installer plan` | `install.sh` planning step | Build a deterministic installer plan from environment and probe inputs without applying it. | -| `nemoclaw internal installer resolve-release-tag` | `install.sh` planning step | Resolve the installer ref using the same precedence as `install.sh`. | -| `nemoclaw internal installer normalize-env` | `install.sh` planning step | Normalize installer ref and provider environment values without applying any installation changes. | -| `nemoclaw internal uninstall plan` | `uninstall.sh` planning step | Build a deterministic uninstall plan without applying it. | -| `nemoclaw internal uninstall classify-shim` | `uninstall.sh` planning step | Classify whether a NemoClaw shim path is safe to remove. | +| `nemoclaw internal installer plan` | Internal planning helper | Build a deterministic installer plan from environment and probe inputs without applying it. Not currently invoked by `install.sh` (which has its own Bash equivalents); exposed for external tooling and inspection. | +| `nemoclaw internal installer resolve-release-tag` | Internal planning helper | Resolve the installer ref using the same precedence as `install.sh`. Not currently invoked by `install.sh`; exposed for external tooling and inspection. | +| `nemoclaw internal installer normalize-env` | Internal planning helper | Normalize installer ref and provider environment values without applying any installation changes. Not currently invoked by `install.sh`; exposed for external tooling and inspection. | +| `nemoclaw internal uninstall plan` | Internal inspection helper | Build a deterministic uninstall plan without applying it. The runtime path (`uninstall.sh` → `internal uninstall run-plan`) calls the underlying plan logic directly, not via this command. | +| `nemoclaw internal uninstall classify-shim` | Internal inspection helper | Classify whether a NemoClaw shim path is safe to remove. Called as a library function by `internal uninstall run-plan`, not via this command. | | `nemoclaw internal uninstall run-plan` | `uninstall.sh` | Execute the host-side uninstall plan. | ## Environment Variables