From 1caa6dfd94ab709266219a0c4058c37cd8abe545 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 14 Jul 2026 12:30:59 -0700
Subject: [PATCH] docs: document the Comfy Cloud run path in the README +
 --help epilog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a compact cloud quickstart (login → run → jobs wait → download) plus
credits/subscription guidance to the README, and mirror the same decision
path in the root --help epilog. Command names validated against the actual
registered CLI surface.
---
 README.md            | 15 +++++++++++++++
 comfy_cli/cmdline.py | 12 +++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f238b13e..f7620ab0 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,21 @@ comfy setup
 
 `comfy setup` walks you through everything — local or cloud routing, authentication, and agent skill installation — in one interactive wizard. Pass `-y` for non-interactive (CI/scripted) installs.
 
+## Run a workflow in the cloud
+
+No local GPU? Route any API-format workflow to [Comfy Cloud](https://www.comfy.org/) with `--where cloud`:
+
+```bash
+comfy cloud login                                        # sign in via your browser (OAuth)
+comfy run --workflow ./workflow.json --where cloud       # submits, prints a prompt_id, returns immediately
+comfy jobs wait <prompt_id> --where cloud                # block until the job finishes (or: jobs status for a one-shot check)
+comfy download <prompt_id> --where cloud -o ./outputs    # save the results locally
+```
+
+`comfy run` submits asynchronously and prints the `prompt_id` you feed to `jobs`/`download`; add `--wait` to block inline instead. Check your sign-in anytime with `comfy cloud whoami`. Export the workflow JSON from ComfyUI via **File → Export (API)** (UI-format JSON is auto-converted). Set cloud as your default target so you can drop the flag: `comfy set-default --where cloud`.
+
+**Credits:** cloud generation (`comfy run --where cloud`, `comfy generate`) consumes Comfy Cloud credits and needs an active subscription. Discovery and inspection commands — `comfy cloud whoami`, `comfy jobs status/ls`, `comfy templates ls`, `comfy generate list` — don't.
+
 ## Installation
 
 1. (Recommended) Activate a virtual environment ([venv](https://docs.python.org/3/library/venv.html) or [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)).
diff --git a/comfy_cli/cmdline.py b/comfy_cli/cmdline.py
index 4662b788..e8518e15 100644
--- a/comfy_cli/cmdline.py
+++ b/comfy_cli/cmdline.py
@@ -153,7 +153,17 @@ def _maybe_nudge_setup(ctx: typer.Context, renderer) -> None:
         pass
 
 
-@app.callback(invoke_without_command=True)
+@app.callback(
+    invoke_without_command=True,
+    epilog=(
+        "Cloud quickstart (no local GPU required):\n\n"
+        "comfy cloud login  →  comfy run --workflow wf.json --where cloud  "
+        "(prints a prompt_id)  →  comfy jobs wait <prompt_id> --where cloud  →  "
+        "comfy download <prompt_id> --where cloud\n\n"
+        "Cloud generation consumes Comfy Cloud credits (needs an active subscription); "
+        "discovery commands (jobs status, templates ls, generate list) don't. See the README."
+    ),
+)
 def entry(
     ctx: typer.Context,
     workspace: Annotated[