feat(cli): add structured logging with --debug and NEMOCLAW_LOG_LEVEL

docs/reference/commands.mdx

@@ -3019,6 +3019,26 @@ NemoClaw reads the following environment variables to configure service ports, o
 Set them before running `$$nemoclaw onboard` or any command that starts services.
 All ports must be non-privileged integers between 1024 and 65535.
 
+### CLI Logging
+
+The centralized CLI logger writes its output to `stderr` and uses `info` verbosity by default.
+These controls affect leveled logger output; they do not suppress command results or command-specific output that has not migrated to the centralized logger.
+
+| Variable | Accepted values | Effect |
+|----------|-----------------|--------|
+| `NEMOCLAW_LOG_LEVEL` | `error`, `warn`, `info`, or `debug` (case-insensitive; surrounding whitespace is ignored) | Sets the logging threshold. A valid value takes precedence over `NEMOCLAW_DEBUG`. An invalid, blank, or unset value falls through to `NEMOCLAW_DEBUG`. |
+| `NEMOCLAW_DEBUG` | `1`, `true`, `y`, or `yes` (case-insensitive) | Enables `debug` logging when `NEMOCLAW_LOG_LEVEL` does not contain a valid value. |
+
+The environment precedence is `NEMOCLAW_LOG_LEVEL`, then `NEMOCLAW_DEBUG`, followed by the default `info` level.
+The `error` level prints errors only, `warn` also prints warnings, `info` also prints informational messages, and `debug` prints all levels with timestamps.
+Use these NemoClaw-specific variables instead of the generic `DEBUG` variable. `DEBUG` is not a NemoClaw logger control and can enable dependency diagnostics that include raw command arguments.
+
+Commands whose parser owns the base logging options also accept the hidden long-form `--debug` and `--quiet` flags, even though these options do not appear in command help.
+The flags are mutually exclusive.
+`--debug` overrides the environment-derived threshold and selects `debug`, while `--quiet` caps verbosity at `warn` without increasing an environment-derived `error` threshold.
+There is no global `-q` logging shorthand.
+Passthrough commands do not consume flags intended for the downstream command as host logging options, so use the environment variables when you need unambiguous host logging around a passthrough invocation.
+
 | Variable | Default | Service |
 |----------|---------|---------|
 | `NEMOCLAW_GATEWAY_PORT` | 8080 | OpenShell gateway port |

src/commands/sandbox/agent.test.ts

@@ -8,6 +8,7 @@ vi.mock("../../lib/actions/sandbox/agent/passthrough", () => ({
   runAgentPassthrough: runAgentPassthroughMock,
 }));
 
+import { log } from "../../lib/cli/logger";
 import SandboxAgentCommand from "./agent";
 
 const rootDir = process.cwd();
@@ -21,7 +22,7 @@ describe("SandboxAgentCommand oclif parse path", () => {
   });
 
   afterEach(() => {
-    logSpy.mockRestore();
+    vi.restoreAllMocks();
   });
 
   it("forwards the OpenClaw argv verbatim to runAgentPassthrough", async () => {
@@ -31,6 +32,30 @@ describe("SandboxAgentCommand oclif parse path", () => {
     });
   });
 
+  it("forwards downstream logging flags without changing host logging", async () => {
+    const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
+
+    await SandboxAgentCommand.run(["alpha", "--debug", "-m", "hi"], rootDir);
+
+    expect(runAgentPassthroughMock).toHaveBeenCalledWith("alpha", {
+      extraArgs: ["--debug", "-m", "hi"],
+    });
+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: true, quiet: false });
+  });
+
+  it("preserves the option boundary without treating later flags as host flags", async () => {
+    const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
+
+    await SandboxAgentCommand.run(["alpha", "--", "--quiet"], rootDir);
+
+    expect(runAgentPassthroughMock).toHaveBeenCalledWith("alpha", {
+      extraArgs: ["--", "--quiet"],
+    });
+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: false, quiet: true });
+  });
+
   it("passes --help after the sandbox name to agent-aware dispatch (#5790)", async () => {
     await SandboxAgentCommand.run(["alpha", "--help"], rootDir);
     expect(runAgentPassthroughMock).toHaveBeenCalledWith("alpha", {

src/commands/sandbox/exec.test.ts

@@ -1,13 +1,14 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const execSandboxMock = vi.hoisted(() => vi.fn(async () => {}));
 vi.mock("../../lib/actions/sandbox/exec", () => ({
   execSandbox: execSandboxMock,
 }));
 
+import { log } from "../../lib/cli/logger";
 import SandboxExecCommand from "./exec";
 
 const rootDir = process.cwd();
@@ -17,6 +18,10 @@ describe("SandboxExecCommand oclif parse path", () => {
     execSandboxMock.mockReset();
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it("forwards everything after -- as the inner command argv", async () => {
     await SandboxExecCommand.run(
       ["alpha", "--", "openclaw", "agent", "--agent", "main", "-m", "hi"],
@@ -29,6 +34,21 @@ describe("SandboxExecCommand oclif parse path", () => {
     );
   });
 
+  it("does not assign host meaning to logging flags after --", async () => {
+    const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
+
+    await SandboxExecCommand.run(["alpha", "--", "agent-cli", "--debug", "--quiet"], rootDir);
+
+    expect(execSandboxMock).toHaveBeenCalledWith("alpha", ["agent-cli", "--debug", "--quiet"], {
+      workdir: undefined,
+      tty: null,
+      timeoutSeconds: undefined,
+    });
+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: true, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: false, quiet: true });
+  });
+
   it("preserves repeated flag/value pairs after -- in their original order", async () => {
     await SandboxExecCommand.run(
       [
@@ -75,7 +95,7 @@ describe("SandboxExecCommand oclif parse path", () => {
         "-c",
         "pass",
       ],
-      { workdir: undefined, tty: null, timeoutSeconds: undefined },
+      { workdir: undefined, tty: null, timeoutSeconds: undefined, stdin: undefined },
     );
   });
 

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

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => {
   class GatewayTokenCommandError extends Error {
@@ -87,6 +87,7 @@ vi.mock("../lib/uninstall-command", () => ({
 }));
 vi.mock("../lib/core/version", () => ({ getVersion: mocks.getVersion }));
 
+import { log } from "../lib/cli/logger";
 import DebugCliCommand from "./debug";
 import DeployCliCommand from "./deploy";
 import RootHelpCommand from "./root/help";
@@ -110,6 +111,10 @@ describe("simple global oclif adapters", () => {
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it("maps debug and deploy parser output to actions", async () => {
     await DebugCliCommand.run(
       ["--quick", "--output", "/tmp/debug.tar.gz", "--sandbox", "alpha"],
@@ -127,6 +132,19 @@ describe("simple global oclif adapters", () => {
     expect(mocks.runDeployAction).toHaveBeenCalledWith("gpu-alpha");
   });
 
+  it("keeps debug -q scoped to quick diagnostics instead of global quiet mode", async () => {
+    const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
+
+    await DebugCliCommand.run(["-q"], rootDir);
+
+    expect(mocks.runDebugCommandWithOptions).toHaveBeenCalledWith(
+      { quick: true },
+      expect.objectContaining({ runDebug: expect.any(Function) }),
+    );
+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: false, quiet: true });
+  });
+
   it("builds debug defaults from the sandbox registry and OpenShell liveness", async () => {
     mocks.listSandboxes.mockReturnValue({
       defaultSandbox: "alpha",
@@ -309,4 +327,16 @@ describe("simple global oclif adapters", () => {
       }),
     );
   });
+
+  it("forwards uninstall flags without assigning host logging semantics", async () => {
+    const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
+
+    await UninstallCliCommand.run(["--yes", "--debug"], rootDir);
+
+    expect(mocks.runUninstallCommand).toHaveBeenCalledWith(
+      expect.objectContaining({ args: ["--yes", "--debug"] }),
+    );
+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
+    expect(configure).not.toHaveBeenCalledWith({ debug: true, quiet: false });
+  });
 });