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

[sauravdev]

Summary

Introduces a centralized CLI logging facility with error, warn, info, and debug levels written exclusively to stderr. Logging can be configured with NEMOCLAW_LOG_LEVEL, NEMOCLAW_DEBUG, or hidden long-form --debug and --quiet flags on commands whose oclif parser owns those options.

The logger now uses NemoClaw's shared credential taxonomy as a non-throwing redaction boundary for messages, split arguments, structured values, and argv arrays. Parser-owned flags do not acquire host meaning after --, and raw passthrough commands preserve downstream arguments unchanged.

The generic DEBUG variable is intentionally not a NemoClaw logger control because oclif can emit raw argv before NemoClaw's redaction boundary. The command reference directs users to the NemoClaw-specific controls instead.

Replaces #6268, which was closed while it still carried unrelated changes. Existing console.* call sites remain unchanged so migration to leveled logging can proceed incrementally.

Changes

• Add src/lib/cli/logger.ts with leveled output, deterministic environment precedence, reversible configuration, and non-throwing serialization for circular values, BigInt, Error, Map, and Set.
• Add hidden, mutually exclusive --debug and --quiet base flags without claiming a global -q shorthand.
• Configure host logging from oclif parser output while preserving strict-false passthrough and -- argument ownership.
• Expand shared log redaction for canonical credential fields, uppercase environment keys, private/session keys, Basic/Digest/proxy authorization, cookies, split logger arguments, and inline or positional argv credentials. Public-key, author, and OAuth labels remain visible.
• Document logging controls, precedence, passthrough behavior, and the generic DEBUG risk in the canonical command reference and synchronized Hermes variant.
• Add unit and integration regressions for credential disclosure paths, serializer and sink failures, environment precedence, singleton reset, passthrough ownership, uninstall forwarding, existing quiet flags, and debug -q.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs 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: maintainer security review and requested changes in feat(cli): add structured logging with --debug and NEMOCLAW_LOG_LEVEL #6272 (review); fixes applied through a3ab263da and independently re-audited.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Verification detail:

• Pre-commit and pre-push hooks pass, including repository checks, environment-variable documentation, gitleaks, commitlint, and CLI TypeScript.
• npm run typecheck:cli and npm run build:cli pass.
• Focused logger, redaction, parser, passthrough, and command-adapter tests pass (104/104).
• Broader redaction consumers pass (94/94), and compiled diagnostic redaction passes (41/41).
• Both observed CI-shard regressions were reproduced locally and fixed: provenance now preserves line boundaries during redaction, while valid Basic/Bearer headers retain later same-line diagnostics. Exact split-label matching also preserves ordinary diagnostic prose while still redacting credential labels and flags. The final focused redaction/logger/provenance/inference set passes (66/66), broader redaction consumers pass (100/100), and compiled OpenClaw integration passes (13/13) after the latest merge from main.
• Adversarial probes cover uppercase/private/session fields, Basic/Digest/proxy authorization, cookies, split arguments, inline and positional argv, dash-prefixed opaque values, and safe public-key/author/OAuth exceptions.
• Debug CLI integration passes (11 passed, 1 platform-dependent test skipped).
• Test-size and test-title gates pass.
• npm run docs passes with 0 Fern errors and 2 pre-existing Fern warnings; documentation review found no additional pages requiring changes.

---

Signed-off-by: sauravdev saurava@nvidia.com
Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features
  • Introduced centralized CLI stderr logging with NEMOCLAW_LOG_LEVEL / NEMOCLAW_DEBUG, quiet/debug modes, and timestamped debug output.
  • Added structured debugObject output plus sequence-aware redaction for log-like values.
• Bug Fixes
  • Improved --debug/--quiet interactions with environment precedence and -- option boundaries; ensured stderr write failures don’t break commands.
• Security
  • Strengthened credential redaction for headers/cookies and sensitive CLI flag values, including “fails closed” handling.
• Documentation
  • Documented logging environment variables, precedence, and hidden flag behavior.
• Tests
  • Expanded coverage for parsing, robustness (complex serialization), redaction correctness, and mock isolation.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Introduces centralized CLI logging with environment and flag-driven level handling, expanded secret redaction, hidden --debug/--quiet command flags, and matching tests plus documentation.

Changes

CLI Logging Feature

Layer / File(s)	Summary
Logger implementation src/lib/cli/logger.ts	Defines shared log levels and config, environment-based resolution, safe serialization, stderr emission, and exported log.
Redaction implementation src/lib/security/redact.ts	Expands header and credential redaction, adds sequence redaction, and changes inline flag and array redaction behavior.
Command logging wiring src/lib/cli/nemoclaw-oclif-command.ts, src/commands/sandbox/agent.test.ts, src/commands/sandbox/exec.test.ts, src/commands/simple-global-oclif-adapters.test.ts, src/lib/cli/nemoclaw-oclif-command.test.ts	Adds hidden mutually exclusive logging flags, configures logging during parse/init, and updates command tests for host logging versus passthrough flag handling.
Logger and redaction tests src/lib/cli/logger.test.ts, src/lib/security/redact.test.ts, src/lib/security/credential-filter-secret-patterns.test.ts	Expands coverage for level precedence, runtime toggles, secret redaction, structured serialization, stderr failures, and credential-field matching.
CLI logging documentation docs/reference/commands.mdx	Adds CLI logging environment and flag behavior documentation.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main CLI logging feature and mentions the key user-facing controls.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/lib/cli/logger.ts (1)

85-114: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicate write logic across log methods; debugObject re-implements the prefix instead of reusing it.

error, warn, info, debug share identical prefix/join/write logic, and debugObject (Lines 110-113) duplicates the timestamp-prefix formatting rather than calling this.prefix("debug"). Consider extracting a private write(level, message) helper.

♻️ Proposed refactor

-  error(message: string, ...args: unknown[]): void {
-    if (!this.shouldLog("error")) return;
-    const parts = [this.prefix("error") + message, ...args.map(String)].join(" ");
-    process.stderr.write(parts + "\n");
-  }
-
-  warn(message: string, ...args: unknown[]): void {
-    if (!this.shouldLog("warn")) return;
-    const parts = [this.prefix("warn") + message, ...args.map(String)].join(" ");
-    process.stderr.write(parts + "\n");
-  }
-
-  info(message: string, ...args: unknown[]): void {
-    if (!this.shouldLog("info")) return;
-    const parts = [this.prefix("info") + message, ...args.map(String)].join(" ");
-    process.stderr.write(parts + "\n");
-  }
-
-  debug(message: string, ...args: unknown[]): void {
-    if (!this.shouldLog("debug")) return;
-    const parts = [this.prefix("debug") + message, ...args.map(String)].join(" ");
-    process.stderr.write(parts + "\n");
-  }
+  private write(level: LogLevel, message: string, args: unknown[]): void {
+    if (!this.shouldLog(level)) return;
+    const parts = [this.prefix(level) + message, ...args.map(String)].join(" ");
+    process.stderr.write(parts + "\n");
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    this.write("error", message, args);
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    this.write("warn", message, args);
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    this.write("info", message, args);
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    this.write("debug", message, args);
+  }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/cli/logger.ts` around lines 85 - 114, The logger methods duplicate
the same prefix/join/write behavior, and debugObject also re-implements
timestamp prefixing instead of reusing the shared formatting. Refactor
src/lib/cli/logger.ts by extracting a private helper used by error, warn, info,
and debug to centralize message writing, and update debugObject to build its
output through the same prefix logic (via prefix("debug") or the new helper) so
formatting stays consistent.

src/lib/cli/nemoclaw-oclif-command.ts (1)

39-41: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Manual flag casts instead of relying on inferred flag types.

(flags as { debug?: boolean }) / (flags as { quiet?: boolean }) bypass whatever type this.parse() already infers from NemoClawCommand.baseFlags. Per oclif's documented base-command pattern, typed InferredFlags<typeof NemoClawCommand['baseFlags']> should give flags.debug/flags.quiet as boolean without casting. Worth confirming whether this.parse(this.constructor as typeof NemoClawCommand) is producing well-typed output; if not, a typed parse signature would remove the need for these casts.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/cli/nemoclaw-oclif-command.ts` around lines 39 - 41, The debug/quiet
checks in NemoClawCommand are using manual casts on the parsed flags instead of
the inferred oclif types. Update the parsing in NemoClawCommand so
`this.parse(this.constructor as typeof NemoClawCommand)` returns properly typed
`flags` from `baseFlags` (for example via `InferredFlags<typeof
NemoClawCommand['baseFlags']>` or a typed parse signature), then access
`flags.debug` and `flags.quiet` directly without casts.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/cli/nemoclaw-oclif-command.ts`:
- Around line 37-42: The flag handling in NemoClawCommand.init currently applies
setDebug before setQuiet, so passing both --debug and --quiet causes quiet mode
to override debug output via logger.ts. Update the precedence in init so the
intended behavior is explicit: either apply setQuiet first and let setDebug win,
or add conditional logic that prevents quiet from downgrading an already-enabled
debug level. Use the existing symbols NemoClawCommand.init, log.setDebug, and
log.setQuiet to locate and adjust the flag order.

---

Nitpick comments:
In `@src/lib/cli/logger.ts`:
- Around line 85-114: The logger methods duplicate the same prefix/join/write
behavior, and debugObject also re-implements timestamp prefixing instead of
reusing the shared formatting. Refactor src/lib/cli/logger.ts by extracting a
private helper used by error, warn, info, and debug to centralize message
writing, and update debugObject to build its output through the same prefix
logic (via prefix("debug") or the new helper) so formatting stays consistent.

In `@src/lib/cli/nemoclaw-oclif-command.ts`:
- Around line 39-41: The debug/quiet checks in NemoClawCommand are using manual
casts on the parsed flags instead of the inferred oclif types. Update the
parsing in NemoClawCommand so `this.parse(this.constructor as typeof
NemoClawCommand)` returns properly typed `flags` from `baseFlags` (for example
via `InferredFlags<typeof NemoClawCommand['baseFlags']>` or a typed parse
signature), then access `flags.debug` and `flags.quiet` directly without casts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bba386e9-24ba-42ac-8661-4198f97b7147

📥 Commits

Reviewing files that changed from the base of the PR and between 06b78aa and 564bbb5.

📒 Files selected for processing (3)

• src/lib/cli/logger.test.ts
• src/lib/cli/logger.ts
• src/lib/cli/nemoclaw-oclif-command.ts

[cv]

The eager base init parsing breaks strict=false passthrough commands: CI shows uninstall --yes and sandbox --agent or -m rejected. Global -q also conflicts with debug --quick; quiet behavior does not match the documented warn-plus-error contract; and the new env vars are undocumented. Restore CLI compatibility, resolve the flag collision and docs parity, and return CI to green.

[wscurran]

✨ Thanks for the PR. This adds structured logging with --debug/--quiet flags and NEMOCLAW_LOG_LEVEL environment variable support — a new user-visible capability for CLI debugging. Ready for maintainer review.

---

Related open PRs:

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

[apurvvkumaria]

Requesting changes on current head 6aad9731c.

The earlier eager-parse and debug -q collision regressions are improved, but this head still introduces unsafe logging behavior, crosses passthrough argument ownership, fails a required documentation gate, and lacks regression coverage for the new initialization path. Please address the inline findings and run the required CI before reconsidering.

[apurvvkumaria]

/ok to test 32d8bad

[apurvvkumaria]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[apurvvkumaria]

Re-reviewed head 32d8bad. The requested redaction boundary, non-throwing serialization, passthrough argument ownership, user-facing documentation, and idempotent logger configuration are implemented with regression coverage. Targeted validation and the full GitHub Actions matrix are green.

[coderabbitai]

🧹 Nitpick comments (2)

src/commands/sandbox/exec.test.ts (1)

37-49: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Strengthen the assertion to prove the baseline was actually applied.

Only negative assertions are made on configure. If log.configure were never called at all (e.g., a regression removing the init()/parse() wiring), this test would still pass. Add the positive assertion, mirroring agent.test.ts.

♻️ Suggested addition

+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
     expect(configure).not.toHaveBeenCalledWith({ debug: true, quiet: false });
     expect(configure).not.toHaveBeenCalledWith({ debug: false, quiet: true });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/sandbox/exec.test.ts` around lines 37 - 49, The test around
SandboxExecCommand.run only checks that log.configure is not called with the
flag values, so it can still pass if configuration is never invoked at all.
Update the assertion in this spec to explicitly verify the baseline call to
log.configure, matching the pattern used in agent.test.ts, while keeping the
existing negative checks for the post--- logging flags.

Source: Path instructions

src/commands/simple-global-oclif-adapters.test.ts (1)

135-146: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Same vacuous-assertion gap as noted in exec.test.ts.

Only a negative assertion on configure is made; add the positive baseline assertion so the test can't pass if configure is never invoked.

♻️ Suggested addition

+    expect(configure).toHaveBeenCalledWith({ debug: false, quiet: false });
     expect(configure).not.toHaveBeenCalledWith({ debug: false, quiet: true });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/simple-global-oclif-adapters.test.ts` around lines 135 - 146,
The test in DebugCliCommand only checks that log.configure is not called with
the quiet-mode options, so it can still pass if configure is never called at
all. Update the assertion around the configure spy in the DebugCliCommand.run
path to include a positive baseline call expectation, alongside the existing
negative check, so the test verifies configure is actually invoked and scoped
correctly for quick diagnostics.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/sandbox/exec.test.ts`:
- Around line 37-49: The test around SandboxExecCommand.run only checks that
log.configure is not called with the flag values, so it can still pass if
configuration is never invoked at all. Update the assertion in this spec to
explicitly verify the baseline call to log.configure, matching the pattern used
in agent.test.ts, while keeping the existing negative checks for the post---
logging flags.

In `@src/commands/simple-global-oclif-adapters.test.ts`:
- Around line 135-146: The test in DebugCliCommand only checks that
log.configure is not called with the quiet-mode options, so it can still pass if
configure is never called at all. Update the assertion around the configure spy
in the DebugCliCommand.run path to include a positive baseline call expectation,
alongside the existing negative check, so the test verifies configure is
actually invoked and scoped correctly for quick diagnostics.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7b6c8ea7-5fd8-4ec1-9441-d871e7634c71

📥 Commits

Reviewing files that changed from the base of the PR and between c2b51cf and 32d8bad.

📒 Files selected for processing (11)

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/commands/sandbox/agent.test.ts
• src/commands/sandbox/exec.test.ts
• src/commands/simple-global-oclif-adapters.test.ts
• src/lib/cli/logger.test.ts
• src/lib/cli/logger.ts
• src/lib/cli/nemoclaw-oclif-command.test.ts
• src/lib/cli/nemoclaw-oclif-command.ts
• src/lib/security/redact.test.ts
• src/lib/security/redact.ts

💤 Files with no reviewable changes (2)

• src/lib/security/redact.test.ts
• src/lib/security/redact.ts

✅ Files skipped from review due to trivial changes (2)

• docs/reference/commands.mdx
• docs/reference/commands-nemohermes.mdx

[apurvvkumaria]

/ok to test 5ac42be

[apurvvkumaria]

@coderabbitai review

[apurvvkumaria]

/ok to test 935aa56

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/security/redact.ts`:
- Around line 314-317: Update isSensitiveKey so it also treats run-together API
key variants like APIKEY and apikey as sensitive, not just separate api/key
tokens. Add an explicit combined-name check or reuse the existing env-name
matching logic inside redact.ts so values stored under those keys are redacted
by the same path as the current SENSITIVE_KEY_WORDS and
words.includes("api")/words.includes("key") checks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4400dfd9-b623-4708-81bc-36df0ba2a4be

📥 Commits

Reviewing files that changed from the base of the PR and between eed7d52 and bff0386.

📒 Files selected for processing (2)

• src/lib/security/redact.test.ts
• src/lib/security/redact.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/security/redact.test.ts

[apurvvkumaria]

@coderabbitai review

[apurvvkumaria]

/ok to test 844fcf0

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[apurvvkumaria]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[apurvvkumaria]

/ok to test 7f9411a

[apurvvkumaria]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[apurvvkumaria]

@coderabbitai review

[apurvvkumaria]

Maintainer note: please do not force-push this branch. The force-pushes at 04:01 and 04:59 UTC dropped resolved security and correctness fixes and invalidated green exact-head CI. I restored the reviewed history append-only without rewriting your commits. Please use normal pushes, or coordinate with maintainers before rewriting this branch again.

[apurvvkumaria]

/ok to test a488c8c

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Resolved on exact tree a488c8c: parser-owned flags respect strict-false and -- passthrough ownership; debug/quiet are mutually exclusive without the -q collision; environment controls are documented; redaction/serialization/reset coverage is present; all review threads are resolved; and the exact-tree security audit plus 205 focused/integration tests passed. Approval remains withheld pending exact-head CI and advisor disposition.