feat(cli): add gateway-token command to retrieve sandbox auth token

[ericksoa]

Summary

Add nemoclaw <name> gateway-token so automation can capture the OpenClaw gateway auth token after onboarding without scraping /sandbox/.openclaw/openclaw.json by hand.

Related Issue

Closes #938

Changes

• Add src/lib/gateway-token-command.ts with a host-side handler that takes a fetchToken dependency plus log/error sinks, keeping it unit-testable in isolation.
• Reuse the existing host-side helper fetchGatewayAuthTokenFromSandbox from src/lib/onboard.ts (now exported) instead of duplicating token retrieval.
• Wire the new sandbox action into src/nemoclaw.ts dispatch, parse --quiet / -q, reject unknown flags, and silence EPIPE on stdout so consumers like ... | head -c 0 don't see a Node stack trace after the token has been written.
• Register the command in src/lib/command-registry.ts so it appears in nemoclaw --help automatically.
• Document the command under docs/reference/commands.md (skill page regenerated by the doc-to-skills hook).
• Add unit tests in src/lib/gateway-token-command.test.ts covering the success path, --quiet, fetch returning null, fetch throwing, and empty-string token.

Output contract:

• stdout: token only, no surrounding text (pipe-friendly).
• stderr: one-line security warning, suppressed by --quiet / -q.
• exit 0 when the token prints; exit 1 when the sandbox is unknown or the token cannot be retrieved (with a diagnostic on stderr).

Example:

TOKEN=$(nemoclaw my-assistant gateway-token --quiet)
export OPENCLAW_GATEWAY_TOKEN="$TOKEN"

Review Follow-ups

After the initial commit, an adversarial code review surfaced several issues. Addressed in commit 925673ec:

• Dead getSandbox check + latent unbound-this risk — the upstream recoverRegistryEntries guard at src/nemoclaw.ts:3651 already rejects unknown sandbox names before the action switch is reached, so the in-command "not registered" branch was unreachable from the CLI. Dropped the dependency entirely; the unknown-sandbox path now relies on the same guard every other sandbox subcommand uses.
• EPIPE on stdout — added a stdout error handler so nemoclaw foo gateway-token | head -c 0 no longer emits a Node stack trace after the token has been written.
• Em-dash → -- — the stderr security warning now uses ASCII so it renders cleanly on legacy Windows consoles.

Considered and explicitly skipped, with reasoning:

• TTY refusal / --print flag — issue Add CLI command to retrieve gateway auth token #938 carves out two commands: open to minimize TTY exposure, and gateway-token for the scripting use case. Adding TTY refusal here would depart from the issue's design.
• Audit logging on token read — sibling sandbox subcommands (including the credential-related ones) don't audit reads, and the existing onboard wizard prints the same token without auditing. Adding it only here would be inconsistent and out of scope for Add CLI command to retrieve gateway auth token #938.
• --help flag for the subcommand — no other sandbox subcommand accepts --help; matching convention.
• Surface the underlying fetch error — fetchGatewayAuthTokenFromSandbox swallows every failure to null today, so there is nothing to surface without a deeper refactor of the helper. Out of scope.

Type of Change

• Code change with doc updates

Verification

• npm run typecheck:cli passes
• npx vitest run --project cli passes for all tests except the four pre-existing slow-timeout flakes in test/onboard.test.ts (5 s timeout vs 7–12 s actual on slow hardware) that also fail on clean main and are unrelated to this change
• npx prek run --all-files passes apart from the same pre-existing test/onboard.test.ts flakes
• Tests added for new behavior
• No secrets, API keys, or credentials committed
• Docs updated for the new command

Summary by CodeRabbit

• New Features

  • Added nemoclaw <name> gateway-token CLI command to output a sandbox's OpenClaw gateway auth token to stdout; emits a one-line security warning to stderr unless suppressed with --quiet/-q; exits non-zero with diagnostics on failure.

• Documentation

  • Added command reference entry documenting usage, warning behavior, and failure semantics.

• Tests

  • Added tests covering argument parsing, success/failure behavior, and expected stdout/stderr outputs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new CLI command nemoclaw <name> gateway-token that retrieves a sandbox's OpenClaw gateway auth token, prints the token to stdout (no extra text), emits a one-line security warning to stderr unless --quiet/-q is set, and exits non‑zero with stderr diagnostics on failure.

Changes

Cohort / File(s)	Summary
Documentation ​.agents/skills/nemoclaw-user-reference/references/commands.md, docs/reference/commands.md	Adds reference entries describing nemoclaw <name> gateway-token, stdout token output, stderr security warning and failure semantics.
Command Registry & Tests src/lib/command-registry.ts, src/lib/command-registry.test.ts	Registers new visible sandbox usage nemoclaw <name> gateway-token and updates tests to expect one additional sandbox command and action token ("gateway-token").
Gateway Token Command & Tests src/lib/gateway-token-command.ts, src/lib/gateway-token-command.test.ts	Implements parseGatewayTokenArgs and runGatewayTokenCommand with quiet flag handling, token fetch/error handling, stdout/stderr behaviours, and comprehensive tests for success and failure cases.
Onboarding Export src/lib/onboard.ts	Exports fetchGatewayAuthTokenFromSandbox so it can be used by the new command.
CLI Integration src/nemoclaw.ts	Wires new action into CLI dispatcher, validates unknown flags, registers EPIPE handler for stdout, and lists gateway-token in valid actions.

Sequence Diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as nemoclaw.ts
    participant Parser as gateway-token-command.ts (parse)
    participant Runner as gateway-token-command.ts (run)
    participant Registry as command-registry
    participant Fetcher as onboard.ts (fetchGatewayAuthTokenFromSandbox)
    participant Stdout as stdout
    participant Stderr as stderr

    User->>CLI: nemoclaw <name> gateway-token [--quiet]
    CLI->>Parser: parseGatewayTokenArgs(args)
    Parser-->>CLI: { options, unknown }
    alt unknown flags
        CLI->>Stderr: Print "Unknown flag" + Usage
        CLI-->>User: Exit 1
    else valid
        CLI->>Runner: runGatewayTokenCommand(name, options, deps)
        Runner->>Registry: lookup sandbox
        alt sandbox missing
            Runner->>Stderr: Diagnostic lines (sandbox not registered)
            Runner-->>CLI: Exit 1
        else sandbox found
            Runner->>Fetcher: fetchGatewayAuthTokenFromSandbox(sandbox)
            Fetcher-->>Runner: token or null/empty/error
            alt token present
                Runner->>Stdout: Print token (only)
                alt not options.quiet
                    Runner->>Stderr: Print one-line security warning
                end
                Runner-->>CLI: Exit 0
            else token absent/error
                Runner->>Stderr: Two diagnostic lines (could not retrieve + status hint)
                Runner-->>CLI: Exit 1
            end
        end
    end
    CLI-->>User: exit code

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped into sandboxes, quiet and spry,

Pulled a tiny token and gave it a try.
"Treat it like treasure," I whisper, polite—
Quiet or not, keep it safe through the night.
🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% 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
Title check	✅ Passed	The title accurately summarizes the main change: adding a new CLI gateway-token command to retrieve sandbox auth token, which is the primary objective of the PR.
Linked Issues check	✅ Passed	The PR implements the gateway-token mechanism from issue #938: adds CLI command to fetch the token, reuses fetchGatewayAuthTokenFromSandbox, displays security warning, and makes command discoverable via --help.
Out of Scope Changes check	✅ Passed	All changes are in-scope: command implementation, documentation, registry updates, tests, and command dispatch are all directly related to the gateway-token feature.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/938-gateway-token-command

---

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

[coderabbitai]

🧹 Nitpick comments (2)

docs/reference/commands.md (1)

301-303: Use active voice and inline code for stream names.

Please rewrite these lines in active voice and format stdout / stderr as inline code.

As per coding guidelines, "Active voice required. Flag passive constructions." and "CLI commands, file paths, flags, parameter names, and values must use inline code formatting."

🤖 Prompt for AI Agents

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

In `@docs/reference/commands.md` around lines 301 - 303, Rewrite the three
sentences using active voice and format the stream names and flags as inline
code: change "The token is written to stdout with no surrounding text." to
something like "Write the token to `stdout` with no surrounding text."; change
"A one-line security warning is written to stderr; pass `--quiet` (or `-q`) to
suppress it." to an active form like "Write a one-line security warning to
`stderr`; pass `--quiet` (or `-q`) to suppress it."; and change "The command
exits non-zero with a diagnostic on stderr when the sandbox is not registered or
when the token cannot be retrieved (for example, if the sandbox is not
running)." to an active form that formats the stream inline, e.g. "Exit with a
non-zero status and write a diagnostic to `stderr` when the sandbox is not
registered or when the token cannot be retrieved (for example, if the sandbox is
not running)." Ensure `stdout` and `stderr` and the flags remain inline code.

src/nemoclaw.ts (1)

3705-3708: Surface all unknown arguments in one diagnostic.

You currently report only the first unknown token. Printing all unknown inputs makes scripted failures easier to debug.

♻️ Proposed tweak

-        if (gatewayTokenUnknown.length > 0) {
-          console.error(`  Unknown flag: ${gatewayTokenUnknown[0]}`);
+        if (gatewayTokenUnknown.length > 0) {
+          console.error(`  Unknown argument(s): ${gatewayTokenUnknown.join(", ")}`);
           console.error("  Usage: nemoclaw <name> gateway-token [--quiet|-q]");
           process.exit(1);
         }

🤖 Prompt for AI Agents

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

In `@src/nemoclaw.ts` around lines 3705 - 3708, The current handler prints only
the first unknown token (gatewayTokenUnknown[0]); update the block that checks
gatewayTokenUnknown in src/nemoclaw.ts to surface all unknown arguments by
joining or iterating gatewayTokenUnknown (e.g., gatewayTokenUnknown.join(', ')
or loop and print each) when logging the error, keep the same usage message and
exit call (process.exit(1)), and ensure you reference the gatewayTokenUnknown
variable and the surrounding conditional that currently prints the single token
so the diagnostics show every unknown input.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@docs/reference/commands.md`:
- Around line 301-303: Rewrite the three sentences using active voice and format
the stream names and flags as inline code: change "The token is written to
stdout with no surrounding text." to something like "Write the token to `stdout`
with no surrounding text."; change "A one-line security warning is written to
stderr; pass `--quiet` (or `-q`) to suppress it." to an active form like "Write
a one-line security warning to `stderr`; pass `--quiet` (or `-q`) to suppress
it."; and change "The command exits non-zero with a diagnostic on stderr when
the sandbox is not registered or when the token cannot be retrieved (for
example, if the sandbox is not running)." to an active form that formats the
stream inline, e.g. "Exit with a non-zero status and write a diagnostic to
`stderr` when the sandbox is not registered or when the token cannot be
retrieved (for example, if the sandbox is not running)." Ensure `stdout` and
`stderr` and the flags remain inline code.

In `@src/nemoclaw.ts`:
- Around line 3705-3708: The current handler prints only the first unknown token
(gatewayTokenUnknown[0]); update the block that checks gatewayTokenUnknown in
src/nemoclaw.ts to surface all unknown arguments by joining or iterating
gatewayTokenUnknown (e.g., gatewayTokenUnknown.join(', ') or loop and print
each) when logging the error, keep the same usage message and exit call
(process.exit(1)), and ensure you reference the gatewayTokenUnknown variable and
the surrounding conditional that currently prints the single token so the
diagnostics show every unknown input.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f01a78f1-d7b4-4ad8-a490-539c13e0590d

📥 Commits

Reviewing files that changed from the base of the PR and between 1f615e2 and f446a25.

📒 Files selected for processing (8)

• .agents/skills/nemoclaw-user-reference/references/commands.md
• docs/reference/commands.md
• src/lib/command-registry.test.ts
• src/lib/command-registry.ts
• src/lib/gateway-token-command.test.ts
• src/lib/gateway-token-command.ts
• src/lib/onboard.ts
• src/nemoclaw.ts