fix(cli): guide deprecated global start (#9352)

## Summary

Make the deprecated global `nemoclaw start` command exit successfully
with migration guidance instead of attempting tunnel startup. The
command now directs users to the sandbox-scoped start command or the
explicit tunnel command without mutating either resource.

## Related Issue

Fixes #9303

## Changes

- Remove tunnel startup dispatch from the deprecated global command
while retaining Oclif deprecation output.
- Verify exit code zero, migration guidance, and the absence of a second
start dispatch.
- Update command and sandbox lifecycle documentation to match the
compatibility behavior.

## 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)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [ ] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [ ] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit:
- Station profile/scenario:
- Result:
- Supporting evidence:

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — `npx vitest run
src/commands/simple-global-oclif-adapters.test.ts
test/cli/tunnel-command.test.ts` (22 passed)
- [x] Applicable broad gate passed — `npm run test:changed` (12 passed);
`npm run build:cli`; `npm run typecheck:cli`; `npm run lint`
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [x] 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)

---
Signed-off-by: Deepak Jain <deepujain@gmail.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Updated the deprecated `nemoclaw start` command to exit successfully
without starting a sandbox or tunnel.
* Added migration guidance directing users to sandbox-specific or tunnel
start commands.

* **Documentation**
* Clarified the deprecated command’s non-mutating behavior and
recommended alternatives.

* **Tests**
* Added coverage confirming the command displays guidance, completes
successfully, and does not launch local services.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Deepak Jain <deepujain@gmail.com>
Signed-off-by: Prekshi Vyas <34834085+prekshivyas@users.noreply.github.com>
Co-authored-by: Prekshi Vyas <34834085+prekshivyas@users.noreply.github.com>

Author: deepujain

docs/manage-sandboxes/run-sandboxes.mdx

@@ -158,7 +158,8 @@ $$nemoclaw tunnel start
 ```
 
 `$$nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox.
-The older `$$nemoclaw start` still works as a deprecated alias.
+The older `$$nemoclaw start` now prints migration guidance and exits successfully without starting
+a sandbox or tunnel. Use `$$nemoclaw <name> start` or `$$nemoclaw tunnel start` explicitly.
 </AgentOnly>
 <AgentOnly variant="hermes">
 

docs/reference/commands.mdx

@@ -3950,7 +3950,9 @@ export CLOUDFLARE_TUNNEL_TOKEN=<cloudflare-tunnel-token>
 $$nemoclaw tunnel start
 ```
 
-`$$nemoclaw start` remains as a deprecated alias that prints a warning and delegates to `tunnel start`.
+`$$nemoclaw start` remains as a deprecated compatibility command. It exits successfully after
+printing guidance for `$$nemoclaw <name> start` and `$$nemoclaw tunnel start`; it does not start
+either resource itself.
 
 ### `$$nemoclaw tunnel stop`
 
@@ -3985,10 +3987,12 @@ $$nemoclaw tunnel status
 ### `$$nemoclaw start`
 
 <Warning>
-Deprecated. Use `$$nemoclaw tunnel start` instead.
+Deprecated. Use `$$nemoclaw <name> start` for a stopped sandbox or `$$nemoclaw tunnel start` for
+the optional public-URL tunnel.
 </Warning>
 
-This command remains as a compatibility alias to `$$nemoclaw tunnel start`.
+This compatibility command prints migration guidance and exits successfully without changing
+sandbox or tunnel state.
 
 ### `$$nemoclaw stop`
 

src/commands/simple-global-oclif-adapters.test.ts

@@ -289,11 +289,12 @@ describe("simple global oclif adapters", () => {
 
   it("maps tunnel and deprecated service commands to service actions", async () => {
     await TunnelStartCommand.run([], rootDir);
+    expect(mocks.runStartCommand).toHaveBeenCalledTimes(1);
     await TunnelStopCommand.run([], rootDir);
     await DeprecatedStartCommand.run([], rootDir);
+    expect(mocks.runStartCommand).toHaveBeenCalledTimes(1);
     await DeprecatedStopCommand.run([], rootDir);
 
-    expect(mocks.runStartCommand).toHaveBeenCalledTimes(2);
     expect(mocks.runStopCommand).toHaveBeenCalledTimes(2);
     expect(mocks.runStartCommand).toHaveBeenCalledWith(
       expect.objectContaining({ listSandboxes: expect.any(Function), startAll: mocks.startAll }),

src/commands/start.ts

@@ -2,26 +2,25 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { NemoClawCommand } from "../lib/cli/nemoclaw-oclif-command";
-import { serviceDeps } from "../lib/tunnel/command-support";
-import { runStartCommand } from "../lib/tunnel/service-command";
-import { startAll } from "../lib/tunnel/services";
+
+const DEPRECATED_START_MESSAGE =
+  "Deprecated: 'nemoclaw start' no longer starts a resource. Use 'nemoclaw <name> start' for a stopped sandbox or 'nemoclaw tunnel start' for the optional public-URL tunnel.";
 
 export default class DeprecatedStartCommand extends NemoClawCommand {
   static id = "start";
   static strict = true;
-  static summary = "Deprecated alias for 'tunnel start'";
-  static description = "Deprecated alias for tunnel start.";
+  static summary = "Deprecated command that prints start migration guidance";
+  static description =
+    "Use 'nemoclaw <name> start' or 'nemoclaw tunnel start'; this command does not start a sandbox or public-URL tunnel.";
   static usage = ["start"];
   static examples = ["<%= config.bin %> start"];
   static state = "deprecated" as const;
   static deprecationOptions = {
-    message:
-      "Deprecated: 'nemoclaw start' is now 'nemoclaw tunnel start'. To start a stopped sandbox container instead, use 'nemoclaw <name> start'. See 'nemoclaw help'.",
+    message: DEPRECATED_START_MESSAGE,
   };
   static flags = {};
 
   public async run(): Promise<void> {
     await this.parse(DeprecatedStartCommand);
-    await runStartCommand({ ...serviceDeps(), startAll });
   }
 }

test/cli/dispatch-basics.test.ts

@@ -75,7 +75,7 @@ describe("CLI dispatch", () => {
   });
 
   it(
-    "start does not prompt for NVIDIA_INFERENCE_API_KEY before launching local services",
+    "deprecated start does not prompt for NVIDIA_INFERENCE_API_KEY or launch local services",
     testTimeoutOptions(35_000),
     () => {
       const home = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-cli-start-no-key-"));
@@ -112,7 +112,7 @@ describe("CLI dispatch", () => {
       );
 
       const r = runWithEnv(
-        "start",
+        "start 2>&1",
         {
           HOME: home,
           PATH: `${localBin}:${process.env.PATH || ""}`,
@@ -124,8 +124,9 @@ describe("CLI dispatch", () => {
 
       expect(r.code).toBe(0);
       expect(r.out).not.toContain("NVIDIA API Key required");
-      // Services module now runs in-process (no bash shelling)
-      expect(r.out).toContain("NemoClaw Services");
+      expect(r.out).toContain("nemoclaw <name> start");
+      expect(r.out).toContain("nemoclaw tunnel start");
+      expect(fs.existsSync(markerFile)).toBe(false);
     },
   );
 

test/cli/tunnel-command.test.ts

@@ -30,11 +30,20 @@ describe("tunnel CLI dispatch", () => {
     expect(r.out).toContain("Start the cloudflared public-URL tunnel");
   });
 
-  it("deprecated start --help exits 0 and shows alias usage", () => {
+  it("deprecated start --help exits 0 and describes migration-only behavior", () => {
     const r = run("start --help");
     expect(r.code).toBe(0);
-    expect(r.out).toContain("start");
-    expect(r.out).toContain("Deprecated alias");
+    expect(r.out).toContain("this command does not");
+    expect(r.out).toContain("start a sandbox or public-URL tunnel");
+    expect(r.out).toContain("nemoclaw <name> start");
+    expect(r.out).toContain("nemoclaw tunnel start");
+  });
+
+  it("deprecated start exits 0 with sandbox-scoped migration guidance (#9303)", () => {
+    const r = run("start 2>&1");
+    expect(r.code).toBe(0);
+    expect(r.out).toContain("nemoclaw <name> start");
+    expect(r.out).toContain("nemoclaw tunnel start");
   });
 
   it("tunnel stop --help exits 0 and shows tunnel usage", () => {