fix(cli): add update --fresh to reinstall when already up to date (#5960)

[jason-ma-nv]

Summary

nemoclaw update --fresh failed with Nonexistent flag: --fresh — the flag was never implemented, so users attempting a clean reinstall (e.g. to repair a broken-but-current install) got no functionality and no guidance. This adds --fresh to update, meaning "reinstall the maintained build even when already up to date".

Related Issue

Fixes #5960

Changes

• src/commands/update.ts: add the --fresh boolean flag (and document it in usage/examples/help), threaded into runUpdateAction.
• src/lib/actions/update.ts: add fresh?: boolean to RunUpdateOptions; when set, skip the "already up to date" short-circuit and run the maintained installer (which re-clones ~/.nemoclaw/source for a clean reinstall). Emits a clear "reinstalling anyway (--fresh)" note. Deliberately does not reset onboarding state, keeping it distinct from the installer's onboard-scoped --fresh/NEMOCLAW_FRESH.
• src/lib/actions/update.test.ts: tests for up-to-date-without---fresh (no installer), up-to-date-with---fresh (runs installer), and --fresh from a source checkout still refusing to reinstall.

The maintained-installer path (curl … nemoclaw.sh | bash) already wipes and re-clones ~/.nemoclaw/source, so --fresh simply lets that path run when the version check would otherwise short-circuit. Source checkouts still refuse (no destructive reinstall), and --check/--yes/non-interactive gating are unchanged.

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: new flag is self-documented via update --help (usage/examples/description); no dedicated docs page enumerates update flags.
• 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:

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)

---

Signed-off-by: Jason Ma jama@nvidia.com

Summary by CodeRabbit

• New Features

  • Added a new --fresh option to the update command to force a clean re-clone/reinstall even when already up to date.
  • Updated help text, examples, and command reference docs to include --fresh (not resetting onboarding state).

• Bug Fixes

  • Kept “already up to date” behavior by default, but --fresh now triggers reinstall as intended.
  • Ensured --fresh doesn’t affect developer/source checkouts and that installer environment is not polluted.

• Tests

  • Expanded coverage for --fresh vs non---fresh, plus updated help-output expectations.

[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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f3a0864f-a385-4599-8ffd-3ec41cc333e4

📥 Commits

Reviewing files that changed from the base of the PR and between e3050b1 and 5a876e4.

📒 Files selected for processing (5)

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/lib/actions/update.test.ts
• src/lib/actions/update.ts
• src/lib/cli/public-display-defaults.ts

💤 Files with no reviewable changes (3)

• src/lib/cli/public-display-defaults.ts
• src/lib/actions/update.test.ts
• src/lib/actions/update.ts

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

• docs/reference/commands.mdx

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

• docs/reference/commands-nemohermes.mdx

---

📝 Walkthrough

Walkthrough

Adds --fresh support to the update command and update action. The flag is surfaced in CLI help and docs, forwarded into update execution, and covered by new tests for the already-up-to-date and source-checkout paths.

Changes

--fresh flag implementation

Layer / File(s)	Summary
RunUpdateOptions and reinstall logic src/lib/actions/update.ts	Adds fresh?: boolean to RunUpdateOptions, changes the available === false early-exit to skip only when fresh is unset, adds a reinstall log path, and removes NEMOCLAW_FRESH from installer env.
CLI flag, forwarding, and docs src/commands/update.ts, docs/reference/commands-nemohermes.mdx, docs/reference/commands.mdx, src/lib/cli/public-display-defaults.ts	Registers --fresh on UpdateCommand, updates usage and examples, forwards fresh into runUpdateAction, and documents the flag in command references and public display metadata.
Tests for fresh behavior src/lib/actions/update.test.ts, test/update.test.ts	Adds tests covering the no-reinstall path without --fresh, the reinstall path with fresh: true and yes: true, the cancelled prompt path, the source-checkout case, the installer-env sanitization case, and the updated help output for all update aliases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: docs

Suggested reviewers: ericksoa

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding the --fresh update option and its reinstall behavior.
Linked Issues check	✅ Passed	The PR implements --fresh for update, documents it, and adds tests for the clean reinstall behavior requested in #5960.
Out of Scope Changes check	✅ Passed	The added docs, help text, defaults, and tests are directly related to the new --fresh update behavior.

✨ 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 fix/5960-update-fresh-flag

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the fix/5960-update-fres... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	fix/5960-update-fres... 5a876e4	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/blueprint/ssrf.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the fix/5960-update-fres... branch is 69%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	fix/5960-update-fres... 5a876e4	+/-
src/lib/actions...dbox/rebuild.ts	—	82%	—
src/lib/actions...all/run-plan.ts	—	80%	—
src/lib/state/o...oard-session.ts	—	80%	—
src/lib/shields/index.ts	—	75%	—
src/lib/state/sandbox.ts	—	73%	—
src/lib/onboard...er-gpu-patch.ts	—	69%	—
src/lib/onboard/preflight.ts	—	69%	—
src/lib/policy/index.ts	—	67%	—
src/lib/actions...licy-channel.ts	—	59%	—
src/lib/onboard.ts	—	20%	—

---

_{Updated July 03, 2026 05:30 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor (Nemotron Ultra) — Changes requested

Merge posture: Do not merge yet
Primary next action: Resolve or justify PRA-1: Test file monolith growth approaching maintainability threshold.
Open items: 0 required · 2 warnings · 0 suggestions · 1 test follow-up
Since last review: 3 prior items resolved · 2 still apply · 0 new items found

Action checklist

• PRA-1 Resolve or justify: Test file monolith growth approaching maintainability threshold in src/lib/actions/update.test.ts:1
• PRA-2 Resolve or justify: New --fresh tests repeat identical vi.fn() boilerplate without shared helper in src/lib/actions/update.test.ts:66
• PRA-T1 Add or justify test follow-up: New --fresh tests repeat identical vi.fn() boilerplate without shared helper

Findings index

ID	Severity	Category	Location	Required action
PRA-1	Resolve/justify	architecture	src/lib/actions/update.test.ts:1	Extract a local makeDeps() factory for common test dependencies (spawnSyncImpl, log, error, prompt, env, isSourceCheckout) and/or split into nested describe blocks per behavior group (--check, --fresh, source-checkout, branding, env-sanitization). This keeps the file maintainable as more update scenarios are added.
PRA-2	Resolve/justify	tests	src/lib/actions/update.test.ts:66	Extract makeDeps() factory in this PR since the new tests are local to changed code. Can be a simple inline factory returning { spawnSyncImpl: vi.fn(...), log: vi.fn(), error: vi.fn(), prompt: vi.fn(), env: {...}, isSourceCheckout: () => false } with overrides for each test.

Review findings by urgency: 0 required fixes, 2 items to resolve/justify, 0 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

PRA-1 Resolve/justify — Test file monolith growth approaching maintainability threshold

• Location: src/lib/actions/update.test.ts:1
• Category: architecture
• Problem: update.test.ts grew from 397 to 490 lines (+93) with 4 new --fresh tests. File now has 20 test cases in a single describe block, all manually constructing vi.fn() mocks for spawnSyncImpl, log, error, prompt, env, isSourceCheckout without a shared factory. Other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness) use factory patterns.
• Impact: Future test additions compound cognitive load; harder to verify coverage and maintain consistency across test cases. Inconsistent boilerplate risks subtle test divergence.
• Recommended action: Extract a local makeDeps() factory for common test dependencies (spawnSyncImpl, log, error, prompt, env, isSourceCheckout) and/or split into nested describe blocks per behavior group (--check, --fresh, source-checkout, branding, env-sanitization). This keeps the file maintainable as more update scenarios are added.
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Read src/lib/actions/update.test.ts — note repeated vi.fn() boilerplate across 20 test cases in runUpdateAction describe block. Look for makeDeps() or similar helper pattern in other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness).
• Missing regression test: N/A — architecture finding
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Read src/lib/actions/update.test.ts — note repeated vi.fn() boilerplate across 20 test cases in runUpdateAction describe block. Look for makeDeps() or similar helper pattern in other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness).
• Evidence: File length 490 lines; 20 named test blocks; 4 new tests added in this PR (lines 66-160) all repeat spawnSyncImpl/log/env/isSourceCheckout setup manually.

PRA-2 Resolve/justify — New --fresh tests repeat identical vi.fn() boilerplate without shared helper

• Location: src/lib/actions/update.test.ts:66
• Category: tests
• Problem: Four new tests for --fresh flag (lines 66-160) each manually construct spawnSyncImpl, log, error, isSourceCheckout mocks with nearly identical code. No shared test helper despite all being added in this PR.
• Impact: Test maintenance burden increases; inconsistency risk if boilerplate diverges across test cases. The 4 tests cover distinct --fresh behaviors but share 80% identical setup.
• Recommended action: Extract makeDeps() factory in this PR since the new tests are local to changed code. Can be a simple inline factory returning { spawnSyncImpl: vi.fn(...), log: vi.fn(), error: vi.fn(), prompt: vi.fn(), env: {...}, isSourceCheckout: () => false } with overrides for each test.
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Read the four new --fresh tests (lines 66-160) — each manually constructs spawnSyncImpl, log, error, isSourceCheckout with nearly identical code. Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.
• Missing regression test: N/A — test architecture improvement
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the four new --fresh tests (lines 66-160) — each manually constructs spawnSyncImpl, log, error, isSourceCheckout with nearly identical code. Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.
• Evidence: Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

• None.

Simplification opportunities: 2 possible cuts, net -140 lines possible

These are safe simplification checks only. Do not remove validation, security controls, data-loss prevention, or required tests.

• PRA-1 shrink (src/lib/actions/update.test.ts:1): Repeated vi.fn() boilerplate in each test case for spawnSyncImpl, log, error, prompt, env, isSourceCheckout
  • Replacement: Inline makeDeps(overrides?) factory returning { spawnSyncImpl: vi.fn(() => ({ status: 0, stdout: '', stderr: '', signal: null })), log: vi.fn(), error: vi.fn(), prompt: vi.fn(async () => 'y'), env: { ...process.env }, isSourceCheckout: () => false } with per-test overrides
  • Net: -80 lines
  • Safety boundary: Must not weaken security test coverage — the env-sanitization test (lines 330-355) must continue to verify NEMOCLAW_FRESH is stripped
• PRA-2 shrink (src/lib/actions/update.test.ts:66): Duplicate mock construction in 4 new --fresh tests (lines 66-160)
  • Replacement: Shared makeDeps() factory defined once before the 4 tests, called with per-test overrides
  • Net: -60 lines
  • Safety boundary: Test behavior must remain identical — each test still verifies its specific --fresh path (no installer when up-to-date without --fresh, installer runs with --fresh, no announcement before confirmation, source checkout refused)

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 New --fresh tests repeat identical vi.fn() boilerplate without shared helper — Extract makeDeps() factory in this PR since the new tests are local to changed code. Can be a simple inline factory returning { spawnSyncImpl: vi.fn(...), log: vi.fn(), error: vi.fn(), prompt: vi.fn(), env: {...}, isSourceCheckout: () => false } with overrides for each test.

Since last review details

Current findings, using the urgency labels above:

PRA-1 Resolve/justify — Test file monolith growth approaching maintainability threshold

• Location: src/lib/actions/update.test.ts:1
• Category: architecture
• Problem: update.test.ts grew from 397 to 490 lines (+93) with 4 new --fresh tests. File now has 20 test cases in a single describe block, all manually constructing vi.fn() mocks for spawnSyncImpl, log, error, prompt, env, isSourceCheckout without a shared factory. Other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness) use factory patterns.
• Impact: Future test additions compound cognitive load; harder to verify coverage and maintain consistency across test cases. Inconsistent boilerplate risks subtle test divergence.
• Recommended action: Extract a local makeDeps() factory for common test dependencies (spawnSyncImpl, log, error, prompt, env, isSourceCheckout) and/or split into nested describe blocks per behavior group (--check, --fresh, source-checkout, branding, env-sanitization). This keeps the file maintainable as more update scenarios are added.
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Read src/lib/actions/update.test.ts — note repeated vi.fn() boilerplate across 20 test cases in runUpdateAction describe block. Look for makeDeps() or similar helper pattern in other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness).
• Missing regression test: N/A — architecture finding
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Read src/lib/actions/update.test.ts — note repeated vi.fn() boilerplate across 20 test cases in runUpdateAction describe block. Look for makeDeps() or similar helper pattern in other test files (e.g., src/lib/actions/sandbox/connect-flow.test.ts createConnectHarness).
• Evidence: File length 490 lines; 20 named test blocks; 4 new tests added in this PR (lines 66-160) all repeat spawnSyncImpl/log/env/isSourceCheckout setup manually.

PRA-2 Resolve/justify — New --fresh tests repeat identical vi.fn() boilerplate without shared helper

• Location: src/lib/actions/update.test.ts:66
• Category: tests
• Problem: Four new tests for --fresh flag (lines 66-160) each manually construct spawnSyncImpl, log, error, isSourceCheckout mocks with nearly identical code. No shared test helper despite all being added in this PR.
• Impact: Test maintenance burden increases; inconsistency risk if boilerplate diverges across test cases. The 4 tests cover distinct --fresh behaviors but share 80% identical setup.
• Recommended action: Extract makeDeps() factory in this PR since the new tests are local to changed code. Can be a simple inline factory returning { spawnSyncImpl: vi.fn(...), log: vi.fn(), error: vi.fn(), prompt: vi.fn(), env: {...}, isSourceCheckout: () => false } with overrides for each test.
• Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
• Verification: Read the four new --fresh tests (lines 66-160) — each manually constructs spawnSyncImpl, log, error, isSourceCheckout with nearly identical code. Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.
• Missing regression test: N/A — test architecture improvement
• Done when: The risk is fixed or explicitly justified in the PR. Verification: Read the four new --fresh tests (lines 66-160) — each manually constructs spawnSyncImpl, log, error, isSourceCheckout with nearly identical code. Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.
• Evidence: Test 1 (line 66): spawnSyncImpl=vi.fn(), log=vi.fn(). Test 2 (line 90): spawnSyncImpl=vi.fn(()=>...), log=vi.fn(). Test 3 (line 114): spawnSyncImpl=vi.fn(), error=vi.fn(). Test 4 (line 138): spawnSyncImpl=vi.fn(). All repeat isSourceCheckout: () => false/true.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

E2E Advisor Recommendation

Required E2E: spark-install, docs-validation
Optional E2E: launchable-smoke

Dispatch hint: spark-install,docs-validation

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• spark-install (medium): Closest existing E2E coverage for the maintained installer path. The changed update command can now force a clean reinstall and controls installer-shell environment sanitization, so the live installer smoke should prove the installer path remains usable after these changes.
• docs-validation (low): The PR changes update-command public flags in docs, root help display, and command help. This E2E validates CLI/docs parity and local documentation links from a built CLI.

Optional E2E

• launchable-smoke (medium): Additional confidence for the public launchable/user install path after changing the CLI update wrapper around the maintained installer flow, but it does not specifically exercise nemoclaw update --fresh.

New E2E recommendations

• installer/update CLI flow (high): No existing live E2E appears to execute nemoclaw update itself, verify the already-up-to-date no-op path, or verify nemoclaw update --fresh --yes invokes the maintained installer while stripping the installer's onboarding-scoped NEMOCLAW_FRESH environment variable.
  • Suggested test: Add a live or hermetic free-standing E2E target for nemoclaw update: stub or controlled-install the maintained installer command, cover --check, up-to-date without --fresh, up-to-date with --fresh --yes, source-checkout refusal, and installer environment sanitization.

Dispatch hint

• Workflow: .github/workflows/e2e.yaml
• jobs input: spark-install,docs-validation

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: None
Optional Vitest E2E scenarios: None

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• None. No Vitest E2E scenario dispatch is required: this PR changes the host-side update command/action, docs, and non-scenario tests, but does not touch test/e2e-scenario/, the Vitest scenario workflow, registry/runtime support, shared fixtures, or a surface currently covered by a wired Vitest E2E scenario.

Optional Vitest E2E scenarios

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 2 test follow-ups
Since last review: 1 prior item resolved · 0 still apply · 0 new items found

Action checklist

• PRA-T1 Add or justify test follow-up: Runtime validation
• PRA-T2 Add or justify test follow-up: Runtime validation

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 Runtime validation — Add or identify a command-boundary test that invokes `node bin/nemoclaw.js update --fresh --check` and asserts it exits through the check path without `Nonexistent flag: --fresh` and without spawning the maintained installer.. The changed behavior is a public CLI parser boundary for a high-risk installer path. The action-level and help/root-help coverage is strong, but a focused command-boundary parser invocation would directly lock the originally reported `Nonexistent flag: --fresh` failure without running the installer.
• PRA-T2 Runtime validation — If practical in the existing alias suite, mirror that parser-boundary check for `nemohermes update --fresh --check` or document why the shared oclif command metadata plus existing alias help tests are sufficient.. The changed behavior is a public CLI parser boundary for a high-risk installer path. The action-level and help/root-help coverage is strong, but a focused command-boundary parser invocation would directly lock the originally reported `Nonexistent flag: --fresh` failure without running the installer.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[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/actions/update.ts`:
- Around line 278-283: The update flow in update() logs that it is “reinstalling
anyway” before the confirmation gate, which can mislead users if they decline.
Move or defer the log in the available === false && options.fresh branch so it
only runs after the --yes / prompt check succeeds, keeping the status message
aligned with the actual action taken.

🪄 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: 05a1015b-08c3-470b-89e8-cb9fd395abe4

📥 Commits

Reviewing files that changed from the base of the PR and between c6113be and 30d7a2d.

📒 Files selected for processing (3)

• src/commands/update.ts
• src/lib/actions/update.test.ts
• src/lib/actions/update.ts

[jason-ma-nv]

Added 83c7b1be2 documenting --fresh in docs/reference/commands.mdx + commands-nemohermes.mdx — cli-parity requires every CLI flag to appear in the reference docs. Local check-docs.sh --only-cli and npm run docs (0 errors) now pass.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5963.docs.buildwithfern.com/nemoclaw

[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 `@docs/reference/commands.mdx`:
- Around line 1585-1586: The new `--check` and `--fresh` command descriptions in
the commands reference are written as full sentences but do not end with
periods. Update the table rows in the documentation so both descriptions follow
the existing docs style rule by ending with periods, keeping the wording
otherwise unchanged.

🪄 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: 83c68f57-50f8-4787-b74c-8afbad2b1bfc

📥 Commits

Reviewing files that changed from the base of the PR and between 30d7a2d and 83c7b1b.

📒 Files selected for processing (2)

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

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

• docs/reference/commands-nemohermes.mdx

[wscurran]

✨
Related open issues:

• #5960 [DGX Spark][CLI&UX] nemoclaw update --fresh reports "Nonexistent flag: --fresh" — flag not implemented

[github-actions]

E2E Target Recommendation

Required E2E targets: docs-validation
Optional E2E targets: None

Dispatch required E2E targets:

• gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=docs-validation

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

• docs-validation: The PR changes public command documentation plus CLI update help/display metadata. The docs-validation free-standing E2E job is wired in e2e.yaml and validates checkout-local CLI/docs parity and local documentation links for these surfaces.
  • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=docs-validation

Optional E2E targets

• None.

Relevant changed files

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/commands/update.ts
• src/lib/actions/update.ts
• src/lib/cli/public-display-defaults.ts

[cv]

Maintainer rationale for the exact-head advisor follow-ups:

• Nemotron PRA-1, PRA-2, and PRA-T1: keeping the four fresh-path cases explicit is intentional in this narrow salvage. Each case exposes a different dependency seam and outcome: no-op, successful installer spawn, declined prompt, and source-checkout refusal. A factory with permissive defaults would hide those interaction differences more than it would simplify them. The full pre-commit suite, source-shape gate, and test-size budget pass, so no broad test-file refactor is warranted here.
• GPT PRA-T1 and PRA-T2: test/update.test.ts executes the real NemoClaw, NemoHermes, and NemoDeepAgents binaries and verifies that their shared Oclif update metadata exposes fresh. src/lib/actions/update.test.ts separately proves the check path exits without spawning the installer. A direct fresh-plus-check process test would require a git-ls-remote network or PATH-stub harness and would duplicate the shared command metadata already exercised across all three aliases. The existing command-boundary plus action-level coverage is sufficient for this repair.

No correctness, security, or acceptance finding remains open; this rationale accepts only the test-structure follow-ups.

[github-actions]

Vitest E2E Target Results — ✅ All requested jobs passed

Run: 28640285379
Workflow ref: fix/5960-update-fresh-flag
Requested targets: (default — all supported)
Requested jobs: cloud-onboard
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
cloud-onboard	✅ success

[github-actions]

Vitest E2E Target Results — ✅ All requested jobs passed

Run: 28640391541
Workflow ref: fix/5960-update-fresh-flag
Requested targets: (default — all supported)
Requested jobs: spark-install,docs-validation
Summary: 2 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
docs-validation	✅ success
spark-install	✅ success