docs: clarify update/lifecycle entry points via help text (BE-3001)

[mattmillerai]

ELI-5

comfy has four commands that sound like they might all "update" things, and it's confusing which does what:

• comfy update — updates ComfyUI itself (or comfy-cli).
• comfy node update — updates custom nodes.
• comfy manager — turns ComfyUI-Manager on/off and configures it. Not an updater.
• comfy standalone — downloads a standalone Python interpreter bundle. Not an updater.

This PR is help-text only — no renames, no aliases, no behavior change. It adds cross-references so --help steers you to the right command, and relabels the two that were mislabeled as "update-ish".

What changed

Command	Before	After
comfy update	Update ComfyUI Environment [all|comfy|cli]	+ To update custom nodes, use comfy node update.
comfy node update	Update custom nodes or ComfyUI	+ To update ComfyUI itself or the CLI, use comfy update.
comfy manager	Manage ComfyUI-Manager.	Enable/disable and configure ComfyUI-Manager (lifecycle, not updates).
comfy standalone	Download a standalone Python interpreter…	+ This bundles an interpreter; it does not update ComfyUI or custom nodes.

Notes / judgment calls

• node update kept its "or ComfyUI" wording (appended, not replaced). comfy node update all dispatches the same CM-CLI update all call that comfy update all uses, so "or ComfyUI" is factually accurate — removing it would be a regression. Followed the ticket's "append" instruction rather than rewording.
• No snapshot to regenerate. The comfy discover self-describing surface builds its command tree from the live Typer app at runtime (build_help_json), and its tests validate against JSON schemas, not exact help strings — so the new text flows through automatically. Full unit suite is green (2471 passed, 13 skipped).
• No confusing docs to fix. README already documents these commands in separate sections; none group them under a single "update" heading.
• Not a capability denial. The "lifecycle, not updates" / "does not update" phrasings are clarifications, not dead-ends — both real update paths (comfy update, comfy node update) exist and are explicitly cross-referenced.

Testing

• ruff format + ruff check clean on both touched files.
• comfy update|node update|manager|standalone --help render the new strings correctly.
• pytest tests/comfy_cli → 2471 passed, 13 skipped.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request clarifies help text for update, standalone, and manager commands. It distinguishes ComfyUI, CLI, and custom-node updates and describes standalone downloads and manager lifecycle operations.

Changes

Command help clarification

Layer / File(s)	Summary
Command responsibility help comfy_cli/cmdline.py, comfy_cli/command/custom_nodes/command.py	Help text directs ComfyUI and CLI updates to comfy update, custom-node updates to comfy node update, and describes standalone downloads and manager lifecycle operations.

Suggested reviewers: bigcat88, robinjhuang

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
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
• Commit unit tests in branch matt/be-3001-clarify-update-lifecycle-help

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch matt/be-3001-clarify-update-lifecycle-help

---

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

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

✅ No high-signal findings.

Panel: 6/8 reviewers contributed findings.

Reviewers that did not contribute: kimi-k2.5:adversarial (empty), kimi-k2.5:edge-case (empty)

[mattmillerai]

The failing Windows Specific Commands / test check is a pre-existing Windows-runner infra flake, not caused by this PR. It dies in the Install Dependencies step — uv fails to remove a locked pydantic_core.cp312-win_amd64.pyd (Access is denied. (os error 5)) — before any of this PR's code runs. It reproduces identically on rerun and this PR only edits Typer help= strings (docs-only), so it can't be the cause. All other checks (including the windows-latest platform matrix, ruff, and the Cursor review panel) are green; no review threads outstanding.

[mattmillerai]

🤖 The reviews loop filed Linear follow-up ticket(s) for review thread(s) deferred as out of scope for this PR:

• https://linear.app/comfyorg/issue/BE-3280|BE-3280 — Fix repo-wide 'Windows Specific Commands' CI failure (pydantic_core import / uv pip install)

[mattmillerai]

🤖 Self-review pass — one real finding, fixed in d97d9d4.

Rich was eating this PR's own help text. Square brackets in a Typer help= string are parsed as Rich console markup, so [all|comfy|cli] was being silently stripped. Appending the cross-reference sentence made the damage visible — comfy update --help rendered as:

Update ComfyUI Environment . To update custom nodes, use `comfy node update`.

…target list gone, stray . left behind. Escaping the opening bracket (\\[all|comfy|cli]) makes it render literally:

Update ComfyUI Environment [all|comfy|cli]. To update custom nodes, use `comfy node update`.

Verified by rendering the real --help for all four touched commands, not just by reading the diff.

Also verified the negative claims are accurate, since two of them deny a capability:

• comfy manager → "lifecycle, not updates": its subcommands are disable, enable-gui, disable-gui, enable-legacy-gui, migrate-legacy, uv-compile-default, clear — no updater. Accurate.
• comfy standalone → "does not update ComfyUI or custom nodes": accurate.
• Neither is a dead-end: both redirect to real, existing commands (comfy update, comfy node update), both confirmed to run.

Deferred to a follow-up: 16 other help="[...]" strings across custom_nodes/command.py and cmdline.py hit the same stripping — e.g. comfy node show --help shows --mode TEXT with no help at all, hiding [remote|local|cache] entirely. Pre-existing on main and argument-level rather than command-level, so out of scope for a four-string docs PR. Recorded for the fleet to file.

Status: ruff format/check clean, pytest tests/comfy_cli → 2471 passed / 13 skipped. No review threads outstanding; Cursor panel clean. The failing Windows Specific Commands check remains a pre-existing repo-wide infra break (fails on nearly every branch right now; tracked in BE-3280), unrelated to this docs-only diff.

[mattmillerai]

🤖 The reviews loop filed Linear follow-up ticket(s) for review thread(s) deferred as out of scope for this PR:

• https://linear.app/comfyorg/issue/BE-3321|BE-3321 — Escape square brackets in Typer help strings so choice lists actually render

[mattmillerai]

ℹ️ Reviews-loop triage pass — no code change made; both red checks are pre-existing infra, not this PR.

This PR is help-text-only (4 Typer help= strings in cmdline.py + custom_nodes/command.py). Locally on this branch: ruff format/check clean, pytest tests/comfy_cli → 2471 passed, 13 skipped. All four --help outputs re-verified as rendering correctly, including the escaped \[all|comfy|cli] from d97d9d4. No review threads outstanding; CodeRabbit + Cursor panel clean.

build — NEW breakage, repo-wide (not previously tracked). 9 tests fail with ValueError: Comment cannot contain line breaks in test_config_parser.py / test_node_init.py — files this PR does not touch. Root cause: pyproject.toml:49 declares tomlkit unpinned, and tomlkit 0.15.1 (just released) added validation rejecting multi-line comments. CI resolves 0.15.1; uv.lock still pins 0.13.3, which is why it is green locally and red in CI. The two offending call sites are config_parser.py:75 and :250, which pass triple-quoted multi-line strings to .comment(). Reproduced directly:

uv run --with 'tomlkit==0.15.1' python -c "
import tomlkit
d = tomlkit.document(); d['x'] = tomlkit.string('v')
d['x'].comment('''
line1
line2''')"
# ValueError: Comment cannot contain line breaks

Confirmed red on #541, #543, #544, #545 as well. Deferred to a follow-up rather than fixed here — it is a cross-cutting dependency fix in an unrelated module, and folding it into a docs PR would bury it (and race the other open PRs hitting the same check).

Windows Specific Commands / test — same pre-existing runner flake already tracked in BE-3280: dies in Install Dependencies with failed to remove ...pydantic_core.cp312-win_amd64.pyd: Access is denied. (os error 5), before any of this PR's code runs.

Neither failure is attributable to this diff. Ready to merge once the build fix lands separately.

[mattmillerai]

✏️ Correction to my previous comment: the build / tomlkit-0.15.1 breakage is already fixed in #536 (BE-3290, branch matt/be-3290-tomlkit-comment-fix) — same root cause, same two config_parser.py call sites, plus the tomlkit>=0.13,<0.16 pin I suggested. It was already tracked; I missed it on first sweep. No follow-up ticket filed — that would have been a duplicate.

So the triage for #520 stands unchanged, with both red checks tracked elsewhere and neither caused by this diff:

• build → fixed by fix(registry): emit pyproject hints as standalone comments for tomlkit 0.15 #536; this PR goes green once that merges and this branch picks up main.
• Windows Specific Commands / test → pre-existing runner flake, BE-3280.

Nothing actionable remains on this PR: no code change, no new ticket.

[bigcat88]

This PR currently conflicts with main — GitHub reports mergeable: CONFLICTING, so it needs a rebase before I can review it and I'm skipping it in the current review sweep.

Please rebase (or merge main in) and I'll pick it up on the next pass. main moved a fair bit in the last day, including #614 (ANSI sanitisation across the pretty-print call sites) and #628 (the duplicate server_died error-code fix that had main red), so a refresh may also clear unrelated CI noise on this branch.

[mattmillerai]

Rebased on `main` in 6b5b23a — the only conflict was in `cmdline.py` (main's new `_switch_comfy_version`/`comfy update comfy --version X` path vs. this branch's escaped Typer help-string brackets on the same `update` command decorator); both are preserved.

Verified post-merge: full suite green (3410 passed, 37 skipped), `ruff format`/`check` clean on the touched file, and all four `--help` outputs re-rendered correctly (brackets show literally, e.g. `Update ComfyUI Environment [all|comfy|cli]. ...`). No unresolved review threads. Ready for another pass.

[skishore23]

The cross-references are a genuine improvement and I want them in. But there's a one-character regression in the comfy update help that's worth fixing first — in a help-text-only PR, the rendered output is the deliverable.

The \[ escape renders literally in this app

This line adds an escape that wasn't there before:

-@app.command(help="Update ComfyUI Environment [all|comfy|cli]")
+@app.command(help="Update ComfyUI Environment \\[all|comfy|cli]. To update custom nodes, use `comfy node update`.")

Rendered comfy --help, before and after (merged origin/main into the head first):

main:  │ update    Update ComfyUI Environment [all|comfy|cli]
this:  │ update    Update ComfyUI Environment \[all|comfy|cli]. To update custom

The backslash reaches the user. This app runs typer 0.16.0 with rich_markup_mode never set (grepped — no occurrence anywhere in comfy_cli/), so Rich markup is not parsed in help strings and \[ is emitted verbatim rather than collapsing to [. The unescaped form on main renders correctly today.

Fix: drop the \\, keeping the rest of the sentence:

@app.command(help="Update ComfyUI Environment [all|comfy|cli]. To update custom nodes, use `comfy node update`.")

Why the precedent is misleading

There is prior art for \\[ in the codebase — 17 occurrences — so I want to be clear it wasn't an unreasonable thing to copy. But those live on typer.Argument/typer.Option help, not @app.command(help=…), and they're broken too. Same file, current main, comfy update --help:

 Update ComfyUI Environment [all|comfy|cli]          <- command help, unescaped, correct
╭─ Arguments ─────────────────────────────────────╮
│   target   [TARGET]  \[all|comfy|cli] ...        <- argument help, escaped, stray backslash
╰─────────────────────────────────────────────────╯

So the escape is a latent cosmetic bug throughout (cmdline.py ×2, custom_nodes/command.py ×15), and this PR would propagate it into the one place that was still right.

Bonus, entirely optional: since this PR is already about help-text quality, stripping all 17 \\[ → [ would be a tidy, mechanical follow-up (or an extra commit here). Every one of them currently shows a stray backslash. Your call whether to scope it in — the blocking ask is just the single line above.

Everything else checks out

• The other three strings are correct and render cleanly (standalone, manager, node update) — verified in comfy --help.
• Clean merge with origin/main; CI green.
• Your judgment call on keeping "or ComfyUI" in node update is right — comfy node update all does dispatch the same CM-CLI update all path, so removing it would have made the help less accurate.
• Agreed there's no snapshot to regenerate: comfy discover builds from the live Typer tree via build_help_json, and test_command_mentions.py resolves the new backticked comfy node update / comfy update mentions against the real tree — both are real commands, so the lint stays green.

Happy to approve as soon as the backslash comes off.

[mattmillerai]

Re-checked this against the repo's actual locked dependency, and the escape is correct — please don't drop it.

uv.lock (and CI, via uv sync --frozen) resolves typer to 0.21.1, not 0.16.0. I reproduced both versions side by side with the same help= string:

typer==0.16.0, help="...\[all|comfy|cli]..."   -> "...\[all|comfy|cli]..."   (literal backslash — bug, matches your finding)
typer==0.16.0, help="...[all|comfy|cli]..."    -> "...[all|comfy|cli]..."    (correct)

typer==0.21.1, help="...\[all|comfy|cli]..."   -> "...[all|comfy|cli]..."    (correct — this is what's in the PR now)
typer==0.21.1, help="...[all|comfy|cli]..."    -> "...."                    (brackets eaten — regression)

Typer's default rich_markup_mode changed between those two releases (this app never sets it explicitly — still true, grepped again), so which form is correct flipped along with it. Ran the actual CLI too, not just the isolated repro:

$ uv run comfy update --help
 Update ComfyUI Environment [all|comfy|cli]. To update custom nodes, use `comfy
 node update`.

No stray backslash, target list intact — same as what merged in d97d9d4. If your test environment resolved typer 0.16.0, that's likely a stale/unlocked install (pip install -e re-resolving from PyPI instead of uv sync --frozen against the committed lockfile) rather than what CI or a uv sync actually runs.

Keeping the escape as-is. Happy to be wrong if you're seeing something different — if so, could you share your pip show typer / python -c "import typer; print(typer.__version__)" output?

[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 `@comfy_cli/command/custom_nodes/command.py`:
- Line 790: Update the help text on the custom-node update command decorator to
describe only updating custom nodes; remove the claim that it updates ComfyUI
while retaining the guidance to use `comfy update` for ComfyUI or CLI updates.

🪄 Autofix

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bd174bb1-5d2e-4f5b-8532-6d21d0807c38

📥 Commits

Reviewing files that changed from the base of the PR and between a6a62cf and ee67c5f.

📒 Files selected for processing (2)

• comfy_cli/cmdline.py
• comfy_cli/command/custom_nodes/command.py

[mattmillerai]

Rebased onto current main in ee67c5f (only conflict was again in cmdline.py, cleanly resolved — both this PR's escaped help-string bracket and main's new _refresh_node_id_cache helper preserved). All CI green (build, both test jobs, all three platform matrices, GPU runners, ruff, CodeQL, CodeRabbit).

Re-verified the \[all|comfy|cli] escape independently against this branch's actual locked typer==0.21.1 (uv sync --frozen): comfy update --help renders Update ComfyUI Environment [all|comfy|cli]. ... correctly, brackets intact, no stray backslash — confirms the evidence already posted on 2026-08-05. Full local suite: 4337 passed, 36 skipped.

Also replied to and resolved the new CodeRabbit thread on custom_nodes/command.py:790 — the suggested rewrite would have made the help text less accurate (comfy node update all genuinely does update ComfyUI via CM-CLI, which is why that wording was deliberately kept).

@skishore23 re-requesting your review — the merge conflict that was blocking you is resolved and CI is clean; the one open ask (the escape) is addressed above with reproducible evidence. Let me know if you're still seeing the backslash on your end and I'll dig into the env difference.