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]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 55 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c4e3a6ce-a2d5-4f53-b4af-cf4f2f6105e4

📥 Commits

Reviewing files that changed from the base of the PR and between a732f5c and d97d9d4.

📒 Files selected for processing (2)

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

✨ 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.