comfy

name	comfy
description	Generate images, videos, audio, and 3D via ComfyUI — CLI surface, workflow creation hierarchy (template → fragment → raw JSON), domain gotchas, cloud auth, multi-stage orchestration.

You have access to comfy, a local CLI that drives ComfyUI (local install or Comfy Cloud).

The surface splits cleanly in two:

• Discovery — read-only commands that answer "what's here?" (nodes, schemas, workflow slots, auth state, env). Safe to call freely.
• Execution — state-changing commands that submit work, edit files, sign in, or install software.

Read the Ground rules first; they cross both halves. Then the two halves are independent — you can scan only what's relevant to the task.

This is one of a skill family — skim the siblings before a big task so you know what exists, and reach for the right one rather than improvising its job: comfy-director (multi-shot narrative video — story, continuity, conform), comfy-build (build a custom ComfyUI environment on the developer platform), comfy-deploy (run a build release as a serverless deployment, and stop it costing money), comfy-debug (any failed job: error code → fix), comfy-relay (surface a workflow/result in chat, never leave it in /tmp). When a task spans several, load them up front instead of discovering the gap mid-render.

---

Ground rules

Output contract (the envelope)

Every command emits the same JSON shape:

{
  "ok": true,
  "command": "...",
  "version": "0.0.0",
  "where": "local" | "cloud" | null,
  "data": { ... },
  "error": null | { "code": "...", "message": "...", "hint": "...", "details": {...} }
}

When error is present, read the hint and act on it. Don't guess.

Curated knowledge (data.knowledge)

Discovery commands (generate schema|list, templates ls|show|get, nodes search|ls, models search) may carry a knowledge object inside data: models[] (per-model status, tier, route, best_for, pitfalls, routing, warnings, superseded_by), picks[] (ranked models per capability, rank 1 first), capabilities_available[], and on a query that matched nothing a nudge. Enrichment reads the cached bundle only, so a turn never waits on a fetch. comfy launch and comfy skills install refresh the cache when it has expired, and comfy knowledge status refreshes it on demand. An unfiltered listing carries no knowledge key at all: its rows are the whole catalog rather than an answer to anything. Five rules:

1. Which model is a data question. Ask it before choosing, rather than picking a name out of a listing. Run comfy --json knowledge pick "<the user's own words for what they want>"; spelling, spacing and phrasing are normalized, and a hit is the ranked table with caveats, rank 1 first. Pass the phrase as one argument and escape it first: $(...), backticks and " still expand inside double quotes, and those words can come from a channel you do not control. Do not dodge a miss by listing first. A miss records the gap and is still an ok envelope: zero_hit: true, a nudge, and capabilities[] carrying the ids to retry with. When the user has already named a model, run comfy --json knowledge resolve <model> instead and build what they asked for: rank is a preference, and their request outranks it. Override an explicit request only for correctness, where status: deprecated plus superseded_by means say so and use the successor. knowledge.picks and knowledge.models inside data carry the same rows whenever a command includes them.
2. available_locally: false means "not here", not "not curated". The row or pick is still the right answer; this install lacks the templates or nodes it resolves to. A row flagged this way also pulls in picks[] for the capabilities that rank it, so the highest-ranked entry without the flag is the runnable alternative. Say what is missing, then name that alternative.
3. Verify before denying. A missing knowledge key or a nudge means nothing is curated for that query, not that it is unsupported. A nudge on a block that still carries rows means your search term matched nothing curated. Check the live list (templates ls, nodes search <term>, generate list) before telling the user something cannot be done.
4. Capability ids are the search vocabulary. Those ids are the terms that reach a ranked picks table. Run comfy --json knowledge pick with no argument to list them; a block's capabilities_available[] carries the same ids when one is present, as bare strings rather than the {id, description} objects pick returns. Query one of them when a gallery tag or a model name misses.

Routing

The CLI auto-detects: cloud if credentials are configured (API key or OAuth session), else local. Precedence: --where flag → COMFY_WHERE env → the governing project's defaults.where (comfy.yaml, see Projects) → comfy set-default --where … config → auto-detect. A local --where always beats the project default. Check routing:

comfy --json cloud whoami   # signed_in, auth_method, base_url

If the user is signed in, commands auto-route to cloud — just run them without --where. Mention routing only when the user asks to switch.

COMFY_WHERE picks the backend; COMFY_LOCAL_URL sets the local address for every command when it isn't 127.0.0.1:8188 (e.g. a ComfyUI started outside comfy-cli): export COMFY_LOCAL_URL=http://127.0.0.1:8189 (accepts http://host:port, host:port, or http://host; port defaults to 8188; IPv6 as http://[::1]:8189). Per-command precedence: --host/--port flag → COMFY_LOCAL_URL → a comfy-cli-launched background server → 127.0.0.1:8188.

Error codes — react, don't guess

The most common error codes and what to do:

Code	Do this
server_not_running	comfy launch to start the local server, or switch to --where cloud
cloud_not_configured	Ask the user to run comfy cloud login (opens browser, OAuth + PKCE)
cloud_unauthorized	Your CLI session expired or token rejected before submission. Run comfy cloud login again.
transient_auth	A cloud job died mid-run with "Unauthorized: Please login first to use this node" — server-side token expiry, NOT your login. Resubmit the same workflow; do NOT re-login.
node_not_found	Read details.close_matches — pick the closest match and re-run

For the full error code list and resolution steps, run comfy --json discover. When any job fails (an execution_error-family envelope), invoke the comfy-debug skill before improvising — it maps every failure code to a fix.

Presenting your work — show, don't tell

This is visual, iterative work, not code — the user steers by seeing the result, so the image is the message, never a path or a sentence about it. The moment a generation lands, Read it into chat (for a clip, run comfy preview clip.mp4 → a contact-sheet PNG you Read, plus duration/fps/audio). Lead with the visual, then show the source that made it (the blueprint/prompt) — never the compiled JSON. Recommend with taste; iterate in fast show→react loops rather than long upfront questionnaires. You can see frames but cannot hear audio — for music/SFX say "give it a listen" and defer to the user's ear. The full playbook is the comfy-relay skill — load it whenever you generate, review, or iterate on media.

Routing the request — survey first, then choose

Don't commit to the first approach that fits. The ecosystem spans gallery templates, partner-API providers, and thousands of OSS nodes/models. Survey the option space before deciding (see "The ecosystem is vast" below for the commands). The default is workflow-first: even when a partner provider is the right model, reach for its node inside a fragment/blueprint so the result is a reusable, inspectable Job on the graph. What to build — which model, provider, and approach — is your judgment to make from what discovery returns; this skill teaches you how to look, not what to pick.

Once you know what you want, there are three mechanisms to build it. Pick by structure, not by habit — this is a mechanism map, not a quality ranking:

Mechanism	When it fits
comfy templates ls/fetch → slot-edit → comfy run	A curated gallery workflow already matches the shape you need
fragments + blueprint → one composed workflow → comfy run	Default — workflows you may extend, fan out, reuse, vary, or explain later; wrap a partner provider's node here too
comfy generate <slug>	Escape hatch — a throwaway one-shot against a single partner provider (a proxy call, not a graph Job)

Prefer one larger Comfy workflow over many separate submissions when the steps can run in the same graph. Comfy can parallelize independent branches, so use fan-out branches, batch nodes, and shared loaders/references inside one workflow before splitting into separate jobs. Split only when a stage needs human review, different routing/auth, server memory isolation, or failure recovery that is worth losing graph-level parallelism.

Escape hatch — comfy generate <slug>: for a throwaway one-shot against a single partner provider, comfy generate skips the graph entirely. It dispatches to Comfy's partner-API proxy (api.comfy.org/proxy/...), which calls the provider on your behalf and bills to your Comfy account (it is not a workflow Job — nothing lands on the graph and nothing is reusable). Reach for it only when you want a quick disposable result; anything you'll reiterate on belongs in a workflow.

Workflow creation — choosing how to build

Once discovery has told you what to build, choose the construction mechanism by complexity and reuse — not as a quality ranking:

1. Template — comfy templates ls --type <image|video|audio> If a curated workflow matches the shape, fetch it. For one-off smoke tests, slot-edit and run it directly. For anything that may become a longer piece, multiple variations, or a reusable pattern, project it into source with comfy workflow decompose (below) and drive it from a blueprint — don't hand-edit the fetched JSON.

2. Fragment + blueprint — this is the default construction path once the workflow is more than a throwaway. Use it even for simple workflows if the next likely step is "make it longer", "add another shot", "vary seeds", "reuse this with a different prompt", or "chain another model".

   There is no shipped fragment library. A fragment is what YOU write after deriving the wiring from live sources — distilled knowledge, kept in the project's ./fragments/. The loop below is the reusable part; the artifacts it produces depend on what YOUR backend has today.

   a. Survey the space — compare OSS, partner, and gallery options before choosing (swap video/VIDEO for the media type at hand):

   comfy --json templates ls --type video --limit 10        # working exemplar graphs
   comfy --json nodes ls --produces VIDEO
   comfy --json nodes ls --category "partner/video*"       # partner providers
   

   b. Learn the wiring from a real graph. Templates are upstream-curated, working workflows — THE reference for how nodes actually wire (positive vs negative conditioning, lora'd CLIP feeding both text encoders, VAE-from-checkpoint, denoise semantics):

   comfy templates fetch <name-from-YOUR-survey> --out ref.json
   comfy --json workflow slots ref.json          # its addressable surface
   

   Or derive from the type graph directly:

   comfy --json nodes show <NodeClass-from-YOUR-survey> --where cloud  # exact schema + enum choices
   comfy nodes path IMAGE VIDEO                  # what CAN connect these types
   

   c. Distill into a local fragment.

   If a working workflow already exists — a template you fetched, a slot-edited file, anything that runs — DECOMPOSE it. Do not re-author the fragment by hand.

   comfy workflow decompose ref.json --name <name>   # → ./fragments/<name>.json
   

   decompose strips loaders → typed inputs (bound to the consumer), strips the terminal save → a typed , and surfaces every scalar widget as a with its current default — all derived from the graph, nothing hardcoded. The buried prompt that used to need becomes a named param you set in the blueprint. (Frontend/subgraph templates are flattened first, so this needs a running or cloud server, or .)

Hard rule: never build raw workflow JSON with >30 nodes. Use fragments and a blueprint. Even for smaller workflows, prefer fragments if any part could be extended, repeated, or reused.

The compile model — edit source, never the artifact (fragments; legacy)

Legacy. Fragments/blueprints/compose produce API format, which can't live on the canvas or merge (CRDT). For reuse/composition prefer recipes (apply --param + capture, above). This section remains for the existing project/blueprint convention and headless batch compiles; new authoring should use recipes.

The folders are source; the workflow JSON is a build artifact. fragments/ + blueprints/ are what you edit; compose is the compiler; blueprints/<name>.compiled.json is the artifact run executes. (templates fetch pulls a vendored dependency into source; decompose turns any workflow into a fragment; compose builds it back.)

This is a hard contract, not a style preference:

• NEVER hand-edit a fetched template or a compiled/exported workflow JSON. Do not open it in an editor, and do not run jq/sed/python to change a value inside a node's inputs/widgets_values, and do not append/rewire nodes by hand.
• The moment you need to change anything inside a fetched/compiled workflow, STOP and comfy workflow decompose <file> it. Then set the value as a named param in a blueprint and compose. The decomposed fragment is self-documenting — its _fragment.description/source say where it came from, and comfy workflow fragment show <name> lists every param with its binds + default, so you edit by name, never by node id.
• Only exception — a throwaway run of a template you will not reuse: comfy workflow slots → set-slot/vary to tweak top-level values, then run. The instant the work will be extended, reused, varied, or chained — or the value lives inside a subgraph slots can't address — decompose instead.

Red flag — STOP: you typed jq/sed/Edit against a workflow's widgets_values or inputs, or you're hunting for a node by numeric id (select(.id==128)). That means the source representation failed. For reusable work, decompose it and set a named param. For a programmatic structured edit of a live graph, use the structured-edit primitives below — never raw jq/sed. (This rule exists because that exact jq-on-id==128 hand-edit is the anti-pattern decompose — and these primitives — were built to kill.)

Structured graph edits — add-node / connect / set-widget / delete-node

The sanctioned way to mutate a graph's structure from code — the alternative to jq/sed on nodes/links/widgets_values. Each edit is validated against object_info (node class, widget name, widget value shape, and connection type are hard-checked; unknown COMBO values / out-of-range numbers come back as soft warnings) and emits a replayable operation in data.op.

When to use which editing path:

• Reusable / human-authored workflow → fragments + blueprint (above). Default.
• Throwaway value tweak on a template → slots → set-slot/vary.
• Programmatic structured edit of a live/draft graph (add or wire or remove nodes; the in-app agent's path; any edit that must merge with a concurrent human editor) → the primitives here.

Live co-editing / CRDT: only the structured-edit primitives (add-node/ connect/set-widget/delete-node/apply) emit a mergeable op in data.op/data.ops (op_id + actor + base_version + stamp). Fragments + compose produce a whole-document graph — fine for authoring a fresh draft (the base), but it does not emit ops and will clobber a concurrent editor if used to re-generate an existing draft. Any edit that must merge with a human's canvas MUST go through the primitives, not a recompose.

# Catalog source: `--where cloud|local` (default routing if omitted), or an
# offline `--input object_info.json` dump. `--where` and `--input` are the only
# catalog flags on these commands.
CAT="--where cloud"

# Start from an existing graph, or an empty one:
echo '{"nodes":[],"links":[],"last_node_id":0,"last_link_id":0}' > wf.json

comfy --json workflow add-node    wf.json KSampler --at 400,200 $CAT  # → data.op.node_id (minted)
comfy --json workflow connect     wf.json 7.LATENT 3.samples $CAT     # source out-slot → target in-slot
comfy --json workflow set-widget  wf.json 3.steps 35 $CAT             # widget by NAME; op carries {old,value}
comfy --json workflow delete-node wf.json 7 $CAT                      # removes node + its links
comfy --json workflow ls-nodes    wf.json                            # id / type / title (no catalog needed)

Building more than one or two nodes? Use apply — one batch, one catalog load, and as aliases so you never capture a minted id by hand:

cat > ops.json <<'JSON'
[ {"op":"add_node","class_type":"CheckpointLoaderSimple","as":"ckpt"},
  {"op":"add_node","class_type":"KSampler","as":"ks"},
  {"op":"connect","from":"ckpt.MODEL","to":"ks.model"},
  {"op":"set_widget","node":"ks","widget":"steps","value":30} ]
JSON
comfy --json workflow apply wf.json --ops ops.json $CAT   # or --ops - to read stdin
# → data.ops[] (all minted ids), data.aliases{ckpt,ks}. Atomic: nothing writes if any spec fails.

Reusable recipes (the reuse path — prefer this over fragments/compose). A recipe is an ops file with a params header and ${param} holes:

{ "recipe":"t2i",
  "params": { "positive": {"type":"string"},          // required (no default)
              "steps":    {"type":"int", "default":20} },  // type: string|int|float|bool
  "ops": [ …, {"op":"set_widget","node":"ks","widget":"steps","value":"${steps}"} ] }

apply --param k=v fills the holes — typed and strict: a value exactly ${x} takes the param's real value; a missing required param, an unknown param, or a bad type all error (never a silent blank).

# capture a working graph into a recipe, PARAMETERIZING the fields you'll vary:
comfy --json workflow capture wf.json --name t2i --param 6.text=positive --param 3.seed=seed -o t2i.recipe.json $CAT
comfy --json workflow apply fresh.json --ops t2i.recipe.json --param positive="a fox" --param seed=42 $CAT

capture --param <node_id>.<widget>=<name> lifts that widget to a ${name} hole (current value becomes its default) — use it for the fields you want to vary, since plain capture omits widgets left at their default. Recipes are UI-format op-batches — mergeable and canvas-native. UI-only nodes (Note/MarkdownNote/Reroute/GetNode/ SetNode/PrimitiveNode) are skipped at capture (reported as warnings on the envelope): links through Reroute and Get/Set chains are spliced to the real source and a PrimitiveNode's value lands on the widget it feeds, so the recipe rebuilds the executable graph — canvas decoration doesn't round-trip. compose/decompose (the fragment/blueprint path) are legacy: they emit API format and can't co-edit; use recipes for anything you'll reuse or edit on the canvas.

Run it and get the image back. Inside a project, outputs land in outputs/. Outside one (a bare wf.json), submit and pipe the result into download:

comfy --json run --workflow wf.json --where cloud --wait > run.json   # blocks until done; data.prompt_id + output refs
comfy --json download --out-dir ./out < run.json                      # pull the produced image(s) to ./out

• Addresses: <node_id>.<slot_or_widget>. Connection slots accept a name (source output like LATENT, target input like samples) or an index; widgets are addressed by name. Discover them with comfy --json nodes show <class> (input/output slot names) and comfy --json workflow slots <file> (widget names — note slots lists widgets only, not connection slots).
• Identity: add-node mints a large random integer id (leaderless, collision-free) and returns it in data.op.node_id; capture it to wire the new node (e.g. id=$(comfy --json workflow add-node … | jq -r .data.op.node_id)). Do not assume small/sequential ids. add-node fills widget defaults (COMBO → first choice), so a new node is runtime-valid without extra set-widget calls.
• The op (data.op): {op, op_id, node_id/link_id, actor, base_version, stamp} — a structured, idempotent, mergeable record of the change (set_widget also carries old/value). --actor <id> and --base-version <n> stamp it for concurrent/CRDT consumers; --stdout prints the new graph instead of writing in place.
• delete-node ≠ delete: delete-node removes a node from the graph file; comfy workflow delete deletes a saved workflow from Comfy Cloud. Do not confuse them.
• add-node/connect/delete-node operate on top-level nodes only. set-widget additionally resolves values inside a subgraph directly — use the flat promoted address slots advertises (e.g. 57.text) or the nested form (57/27.text); no decompose needed.

---

Discovery — what's here?

Read-only. None of these mutate state, charge quota beyond a cheap read, or require sign-in unless you target --where cloud against a node graph the user doesn't have locally. Run them freely.

Always start a non-trivial task with:

comfy --json discover

Returns the full command tree, JSON Schemas for every output, error codes, and capabilities. Everything below flows from it.

Workspace + auth state

comfy --json env             # what's installed locally
comfy --json which           # workspace path
comfy --json cloud whoami    # signed_in, auth_method (oauth/api_key), base_url, api_key_source
comfy --json cloud status    # cloud_workspace, balance, tier, max_concurrent_jobs, upgrade_suggestion
comfy --json auth list       # all credentials (redacted)

cloud status answers "how many credits do I have / what plan am I on / what's my concurrency". It is read-only and spends nothing. Two fields need care: when balance_confirmed is false the balance fields are null rather than 0, so never render "$0.00" from them, and message carries the copy to show instead. Pass message through verbatim rather than composing your own.

Nodes — introspect the graph

Use flag-based filters on nodes ls to find nodes by capability:

comfy --json nodes search "checkpoint loader"    # name/display/category/desc, any word order
comfy --json nodes show KSampler                 # full schema
comfy --json nodes ls --produces MODEL --limit 5 # filter by output type
comfy --json nodes ls --accepts CONDITIONING     # nodes that take this input
comfy --json nodes ls --category "loaders*"      # glob on category path
comfy --json nodes ls --pack comfyui-impact-pack # nodes from a specific pack
comfy --json nodes ls --api-only                 # only partner-API nodes
comfy --json nodes ls --output-only              # terminal output nodes (SaveImage, etc.)
comfy --json nodes ls --include-deprecated       # deprecated nodes are hidden by default
comfy --json nodes ls --cloud-disabled           # what cloud refuses to run
comfy --json nodes upstream KSampler             # what feeds in
comfy --json nodes downstream CheckpointLoaderSimple  # what follows
comfy --json nodes path MODEL IMAGE              # routed paths between types
comfy --json nodes types                         # all connection types
comfy --json nodes categories                    # full category tree

Combine flags to narrow results:

comfy --json nodes ls --produces VIDEO --limit 10
comfy --json nodes ls --pack core --produces MASK --limit 5

Every nodes ls and nodes search row carries is_api_node — true for a paid partner-API node, false for a free open-weights one. Two nodes can share a display name and differ only in this flag, so read it off the row instead of running nodes show per candidate.

If no local server is running and you're not signed into cloud, pass --input <object_info.json> to query against a saved dump.

Dynamic-combo gotcha: some partner nodes declare a COMFY_DYNAMICCOMBO_V3 widget (e.g. a Kling/Grok model or model.resolution) whose choices come back empty from nodes show — the options are resolved at runtime. To learn the valid values, comfy templates fetch <api_template> for that node and read the widget values it ships (e.g. model="kling-v3", model.resolution="720p").

Models — find what's installed, with metadata

On cloud, comfy model search hits the live asset catalog (/api/assets) and returns enriched rows: name, type, tags, base_model, source_url, preview_url, size. On local, the same command falls back to /models/<folder> listings (filenames only).

comfy --json model list-folders                 # every model folder (loras, checkpoints, vae, …)
comfy --json model list-folder loras            # files in a folder, with pathIndex
comfy --json model search --text "wan2.2" --type lora --limit 10
comfy --json model search --text "flux"         # text search across the catalog
comfy --json model show <rows[0].name>          # full Asset + projected row (cloud-only)

model search --type <X> accepts the conventional folder names (lora/loras, checkpoint/checkpoints, vae, controlnet, upscale, clip, clip_vision, unet/diffusion_models, …). Use model list-folders first if you're unsure what types the backend exposes.

Discover → wire loop — every asset type, never hardcoded names:

Every asset name (checkpoint, lora, controlnet, vae, upscaler, embedding, clip-vision model, …) must be discovered at runtime — never hardcoded. Do not default to any model family you've seen in examples, either — the survey IS the decision input; backends differ and the ecosystem moves. The pattern is the same regardless of type:

# 1. Discover available assets for any type
comfy --json model search --type lora --where cloud --text "detail" --limit 5
comfy --json model search --type controlnet --where cloud --limit 5
comfy --json model search --type checkpoint --where cloud --limit 5
comfy --json model search --type vae --where cloud --limit 5
comfy --json model search --type upscale --where cloud --limit 5
comfy --json model search --type embeddings --where cloud --limit 5

# 2. Take rows[0].name verbatim — paste it into your fragment's required param

# 3. Precision check — what will the server actually accept?
comfy --json nodes show LoraLoader --where cloud
# → the lora_name input's "choices" array is the exact list the server accepts
# Same pattern for any loader: ControlNetLoader, VAELoader, UpscaleModelLoader, etc.

Trace (image, OSS checkpoint + lora) — one run of the loop, NOT a recommendation. On this backend, today, the survey returned the rows sketched below; yours will differ — pick from YOUR rows:

comfy --json model search --type checkpoint --where cloud --limit 5  # → picked <ckpt> from rows
comfy --json model search --type lora --where cloud --limit 5        # → picked <lora> from rows
# Learn the lora wiring from a real graph, not memory — fetch a matching template:
comfy --json templates ls --type image --model "<family of <ckpt>, from its row>"
comfy templates fetch <name-from-those-rows> --out ref.json   # read how it wires
# …or derive it from the type graph:
comfy --json nodes show LoraLoader --where cloud  # MODEL+CLIP in, MODEL+CLIP out —
#   the lora'd CLIP must feed BOTH text encoders, not just positive
comfy nodes path MODEL IMAGE                      # sampler → decode → save spine

The agent then authored ./fragments/<your_name>.json with ckpt_name and lora_name as required params (no defaults) and drove it from a blueprint:

pipeline:
  - fragment: <your_name>        # the fragment YOU just wrote
    alias: out
    params:
      ckpt_name: "<rows[0].name from checkpoint search>"
      lora_name: "<rows[0].name from lora search>"
      prompt: "a detailed portrait"

The choices array from nodes show is the universal precision check: it reflects exactly what <server>/object_info reports — authoritative for any loader node on that target.

Templates — one starting point among several

The curated Comfy-Org/workflow_templates gallery is a strong starting point when a template matches your intent — but it sits beside partner-API providers and hand-composed fragments, not above them. Survey all three (see "The ecosystem is vast") before committing.

comfy --json templates ls --type video --tag "Image to Video" --limit 10
comfy --json templates show <name>               # full metadata: models, tags, providers
comfy --json templates fetch <name> --out my.json # pulls the workflow JSON itself

templates fetch validates the name against the gallery index first, so typos surface as template_not_found with details.close_matches — not as a raw 404. The downloaded JSON is frontend-format; comfy run --where cloud auto-converts it to API format on submit.

Saved workflows on cloud

comfy workflow {list,save,get,delete} manages workflows persisted to your cloud account via /api/workflows. Cloud-only — on local, manage JSON files on disk via workflow slots/set-slot/vary instead.

comfy --json workflow list                             # paginated, sorted by create_time
comfy --json workflow list --name "wan" --limit 5      # case-insensitive name filter
comfy --json workflow get <id> --out my.json           # writes workflow JSON
comfy --json workflow save my.json --name "X" --description "Y"
comfy --json workflow delete <id>

Cancel a running job

comfy --json jobs cancel <prompt_id>            # auto-routes via --where
comfy --json jobs cancel <prompt_id> --where cloud

Idempotent on cloud — calling on an already-terminal job returns ok. Local cancels both the pending-queue entry and any in-flight execution.

The ecosystem is vast — explore before building

ComfyUI spans image, video, audio, 3D, and text — with hundreds of models and many partner API providers (BFL, Kling, Runway, ElevenLabs, Meshy, Gemini, Grok, …). Don't guess at counts — discover them:

comfy --json nodes ls --limit 1                  # check data.total for node count
comfy --json nodes ls --produces IMAGE --limit 1 # IMAGE producer count
comfy --json nodes ls --produces VIDEO --limit 1 # VIDEO producer count
comfy --json nodes ls --produces AUDIO --limit 1 # AUDIO producer count
comfy --json nodes ls --api-only --limit 1       # partner API node count
comfy --json nodes categories --prefix "partner"# API provider categories
comfy --json nodes types                         # all connection types
comfy --json model list-folders                 # all model folders
comfy --json templates ls --limit 1              # template count

The total field in nodes ls, nodes search, and model search gives the full count even when --limit caps the returned rows. (One exception: when nodes search finds nothing it falls back to the closest node names and sets data.close_match: true — check that flag, not just count, because those rows are name-similarity guesses rather than matches, and total is only how many guesses it found. Each row carries close_match: true as well.)

Workflows — what can I tweak?

comfy --json workflow slots path.json   # every addressable slot, by address

workflow slots/set-slot/vary and all nodes commands resolve object_info through the routing chain with a cached fallback — cloud-signed-in works with no local server. If the live fetch fails, the command still succeeds from cache and the envelope carries data.stale: true + warnings[] {code: "object_info_stale"} — treat results as possibly outdated re-run the command once the live fetch recovers to pick up fresh object_info. comfy nodes refresh is a different cache — it re-pulls node annotations (pack/labels/cloud_disabled) from Comfy-Org/comfy-complete, not object_info.

Slot addresses are <instance_id>.<input_name>. Feed them to workflow set-slot / workflow vary in the Execution half. Works on any frontend-format workflow JSON — templates, saved workflows, or hand-built files.

---

Execution — make it happen

State-changing. Each of these submits work, edits files, charges cloud quota, or talks to an authenticated backend.

Projects (project/1) — the working convention

Anything beyond a one-shot lives in a project: a directory with a comfy.yaml marker (schema: project/1, plus defaults.where) and five conventional dirs. The convention is the contract — like the envelope.

my-project/
├── comfy.yaml     # marker: schema project/1 + defaults (e.g. defaults.where)
├── assets/        # source files — reference as $asset.<relative/path>
├── fragments/     # fragments YOU author (_fragment JSON)
├── blueprints/    # blueprint YAML; compose writes <name>.compiled.json beside it
├── outputs/       # downloads land here by default
└── .comfy/        # machine-owned: assets.lock.json + runs.jsonl journal

The loop:

comfy project init                     # marker + the five dirs; --where sets the default
cp ~/ref.png assets/s1_first.png       # drop source files under assets/ (subdirs fine)
comfy --json assets push               # upload new/changed files, record them in the lock
# blueprints reference assets by path relative to assets/ (inputs or params):
#   inputs: {start_frame: $asset.s1_first.png}
comfy workflow compose blueprints/<name>.yaml          # → blueprints/<name>.compiled.json
comfy --json run --workflow blueprints/<name>.compiled.json
comfy --json jobs watch <prompt_id>    # terminal envelope: outputs_by_item / outputs_by_node
comfy --json download <prompt_id>      # → outputs/, item-named files
comfy --json project status            # THE state query — root, defaults, blueprints,
                                       #   assets {pushed, stale}, recent_runs, warnings

What the convention buys you:

• The $-reference algebra. Four reference kinds in blueprints, each with ONE resolution source, all resolved at compose time:

  Reference	Resolves from	Where it works
  $alias.output	a prior step's graph output (a wire)	inputs
  $item.field	the current foreach item	inputs + params
  $asset.<relative/path>	the push lock → server-side filename	inputs + params + item field values
  $var.<name>	the vars: block in comfy.yaml	inputs + params + item field values

  Whole-value only: a $-ref must be the ENTIRE string. "a $asset.x b" is plain text — there is no interpolation. $var returns the raw scalar (int stays int); $asset resolves through the lock with staleness checks.

• $asset kills upload-then-paste. The lock (.comfy/assets.lock.json) records sha256 + server name + push target per file, so local and cloud both work; assets push skips files whose content AND target are unchanged (--force re-pushes everything), --where picks the target.

• $var kills copy-pasted constants. Declare a top-level vars: mapping (str/int/float/bool scalars) in comfy.yaml; blueprints reference $var.<name>. Compose snapshots the referenced names + values into the compiled JSON's _meta.vars — provenance for what this compilation used.

• Errors are instructions. Compose fails closed with asset_not_pushed (no lock entry / file gone), asset_stale (file changed since its last push) — both hint exactly run: comfy assets push — or var_not_defined (add the name under vars:). Run the hint, re-compose. $asset / outside a project hint first.

Submit a workflow

comfy run is async by default — returns a prompt_id and state_file path in milliseconds. A detached watcher polls in the background and writes the state file as the job progresses through queued → allocated → executing → terminal.

Prefer async-first: submit, then watch separately. Never poll jobs status in a loop. There are three ways to wait — pick one:

# Step 1: Submit (returns immediately with prompt_id)
RES=$(comfy --json run --workflow path.json)
PROMPT_ID=$(echo "$RES" | jq -r .data.prompt_id)
STATE_FILE=$(echo "$RES" | jq -r .data.state_file)

# (a) Watch — blocks until terminal, returns outputs. The default.
comfy --json jobs watch "$PROMPT_ID"
# → exit 0 / ok:true only on completed; failed job exits 1 / ok:false /
#   error.code=execution_error (payload under error.details); cancelled exits 130.
# `&& next-step` therefore only proceeds on success.

# (b) Read the state file for a quick non-blocking check
jq '{status, outputs, error}' "$STATE_FILE"

# (c) --wait on submit — foreground blocks start-to-finish. Fine for
#     one-shot synchronous runs (e.g. the download pipe below).
comfy --json run --workflow path.json --wait

Why prefer async: submit returns in milliseconds so you can report the prompt_id to the user immediately, then watch in a separate step. Reach for --wait when you want a single blocking call and don't need the prompt_id mid-flight (it's hidden until the job finishes).

--notify fires a desktop notification when the job is terminal. It defaults on in pretty/human async mode, and off in JSON/agent contexts and with --wait. Override explicitly with --notify or --no-notify.

Spend gate — a workflow embedding partner-API (paid) nodes spends the user's Comfy credits. Interactive TTY runs confirm before spending; --json / non-TTY runs fail closed with error code spend_consent_required (exit 1, nothing submitted, nothing spent) unless --allow-spend is passed. Add --allow-spend only when the human has actually approved the spend — do not reflexively add it to make the error go away. Free (non-partner) workflows run without the flag and are byte-identical. (comfy run-template gates the same way with the same flag, and forwards consent to comfy run once its own gate has passed.)

Scope: the async-first / jobs watch / state-file pattern above is the comfy run workflow path only. comfy generate (partner-API one-call) has its own waiting model — see the next section.

Partner-API one-call generation (comfy generate)

comfy generate dispatches straight to a partner provider (BFL Flux, Kling, Gemini, Veo, Ideogram, …) and is often the highest-quality route for a single image/video/edit — not a fallback. It is a separate sub-surface from comfy run, with its own commands and conventions:

comfy generate list                       # enumerate provider models (+ their sync/async mode)
comfy generate schema <model>             # params for one model (e.g. flux-2, kling-i2v)
comfy generate <model> --prompt "…" [--<param> v]… --download outputs/x.png
comfy generate upload <file>              # host a local file → signed URL (for I2V image inputs)
comfy generate <model> … --async          # submit, returns a job id
comfy generate resume <model> <job_id> --download outputs/x.mp4

Mechanical contracts that bite agents — encode them, don't rediscover:

• Spend gate — generation spends the user's Comfy credits and requires consent. Interactive TTY runs confirm before spending; --json / non-TTY runs fail closed with error code spend_consent_required (exit 1, nothing spent) unless consent is supplied. Pass --yes only when the human has actually approved the spend — do not reflexively add it to make the error go away. A human can persist always-proceed with comfy generate consent always (revert: consent ask; inspect: consent show). list / schema / refresh / upload / resume / --emit-workflow spend nothing and are not gated.
• Discovery is structured — never scrape the table. generate list --json and generate schema <model> --json both emit a full renderer envelope (command: "generate list" / "generate schema", schemas generate_list / generate_schema in comfy discover). data.models[] carries {alias, id, partner, category, mode, summary} with the untruncated summary; data.params[] carries {name, type, required, default, enum, description}. Unknown model → generate_unknown_model; missing model arg → generate_bad_args. This catalog is not in comfy discover — generate list is the only source of the alias list.
• Machine-readable output: generate <model> --json prints the raw API response as JSON; generate upload <file> --json emits structured {url, expires_at, …}; generate <model> --emit-workflow out.json goes through the full renderer envelope (command: "generate emit-workflow", error code emit_workflow_failed) — the output is a runnable partner-node workflow you can compose with (fragments+run route, no extra API key). The default pretty path (no flags) is still human-only — do not parse it.
• Failures always come back as an envelope under global --json. Any failed/malformed emits exactly one error on stdout with a stable code — , , , , , , , , — so branch on , never on the text. (Success payloads are unchanged: still the raw API response, not an envelope.) In particular with no model alias is : is a paid cloud/partner verb and always needs an alias first. For text-to-image, use instead.

Pre-flight — validate before you submit

Before comfy run, verify the workflow will succeed:

# Free dry-run: prints the exact API-format graph that WOULD be submitted,
# exits without POSTing — works on both local and cloud routes.
comfy run --workflow wf.json --print-prompt

# Full pre-flight: checks class_types, input shapes, enum values, edge wiring
comfy --json workflow validate --workflow api.json

# Spot-check a single node class exists on the target
comfy --json nodes show <ClassName>
# If error.code == "node_not_found", check details.close_matches

# Confirm a model filename is actually available on the resolved backend (cloud-only)
# On local: use `comfy model list-folder <type>` instead
comfy --json model show <filename>
# If error.code == "model_not_found", check details.close_matches and pick one

This catches the most common failures — unknown nodes, missing models, bad wiring — before burning cloud compute.

Inspect / track jobs

comfy --json jobs ls                # merged: local state files + server queue
comfy --json jobs ls --all          # ...every target, not just the resolved --where
comfy --json jobs status <prompt_id>
comfy --json jobs watch <prompt_id> # blocks until terminal; emits NDJSON with --json-stream

jobs ls is scoped to the resolved --where target: a --where local listing shows local state-file rows only, a --where cloud listing cloud ones. The payload's scope field says which view you got (local / cloud / all); pass --all for the union of everything this CLI submitted.

Terminal envelopes (run --wait, jobs status, jobs watch) carry the flat outputs list plus grouped views of the same artifacts: outputs_by_node: {node_id: [url]} always, and outputs_by_item: {item: [url]} when the workflow came from a foreach blueprint (compose embeds the item map — see Multi-stage orchestration). Never identify fan-out outputs by array order — read outputs_by_item.

Edit workflows in place

workflow slots, set-slot, and vary work on any frontend-format workflow JSON — not just templates. Get slot addresses first:

# 1. Discover addressable slots — addresses are <node_id>.<input>, never titles
comfy --json workflow slots path.json
# → lists every slot as <node_id>.<input_name> with current values
#   subgraph interiors: <instance_id>/<inner_id>.<input>
#   copy addresses verbatim from this output

# 2. Set a single slot
comfy workflow set-slot path.json 6.text="a cat"

# 3. Generate variations (slot lists are zipped — same length required)
comfy --json workflow slots wf.json          # discover addresses first
comfy workflow vary wf.json \
    --slot '6.text=["a cat","a dog","a fox"]' \
    --slot '3.seed=[1,2,3]' \
    --out-dir ./variants
# → 3 workflow JSONs in ./variants
# NOTE: slot addresses use node ids (numeric or UUID), never titles.
#       Always run `slots` first and copy addresses verbatim.

Auth

comfy --json cloud login                         # browser OAuth + PKCE
comfy --json cloud logout
comfy --json auth set huggingface --key hf-…     # third-party provider key
comfy --json cloud set-key --key sk-…            # API-key path for cloud

File transfer — upload and download

Never extract API keys manually. The CLI handles auth internally.

In a project, prefer comfy assets push — it uploads new/changed files under assets/, records server names in the lock, and blueprints just say $asset.<relative/path> (see Projects). The raw commands remain as the non-project fallback:

# Non-project upload fallback: take data.uploads[0].cloud_name from the envelope
comfy --json upload photo.png --where cloud

# Download outputs from a completed job (works in or out of a project)
comfy --json download <prompt_id>

# Pipe pattern — the idiomatic way to generate + collect:
comfy --json run --workflow blueprints/<name>.compiled.json --wait | comfy download
# → submits, waits, downloads outputs in one pipeline

comfy download reads prompt_id + output URLs from piped stdin automatically — no manual extraction, no jq, no API key exposure.

Output directory: the governing project's outputs/, else ./outputs/ (override with --out-dir). Naming: outputs from a foreach blueprint are named by originating item — <item>_<nnn>.<ext> with a per-item counter — and files[] entries carry node_id/item when known; everything else keeps <prompt8>_<idx>.<ext>.

Project layout convention

The project/1 convention above IS the layout: comfy.yaml + assets/ fragments/ blueprints/ outputs/ .comfy/. Lay it down with comfy project init; comfy --json project status reports unknown top-level dirs as warnings (warnings only, nothing enforces).

Never write workflows, fragments, or outputs to /tmp. Always work inside a project. If none governs the directory, run comfy project init before building anything.

Lifecycle (local installs + persistent config)

comfy install                              # set up a local ComfyUI workspace
comfy launch                               # start the local server
comfy set-default --where cloud            # persist the routing mode
comfy set-default --clear-where

Relaying user feedback

This channel carries the user's own words to the maintainers — never your opinion of the tool. You are a relay, not the author.

comfy --json feedback "run is great, but jobs watch should show an ETA"

One-shot and non-interactive. The message ships as a feedback_submitted event; the JSON envelope reports {"sent": true|false}. Feedback is consent-independent (user-initiated), but the hard opt-out (DO_NOT_TRACK / COMFY_NO_TELEMETRY) still suppresses it → sent: false.

When to ask. Occasionally — not every session — invite feedback after a clearly good moment (a job just completed successfully, a multi-step pipeline landed). Roughly one session in five; pick randomly so it stays rare. Ask at most once per session, and never twice if they ignored or declined the first time. One short question, e.g.: "Quick one — anything about the comfy CLI you'd want the maintainers to know? (totally optional)" It's especially worth a nudge after a session with real friction — a papercut you hit repeatedly, a workaround you had to invent, a missing flag (a multi-job wait, a cost readout). That's the highest-signal feedback; surface it in the user's words rather than let it evaporate.

What to send. Only what the user actually says, relayed close to verbatim. Never invent, embellish, or send your own assessment. If they say nothing or brush it off, send nothing. Strip secrets, file contents, and PII. For long or sensitive reports, point them to https://github.com/Comfy-Org/comfy-cli/issues/new/choose instead.

Agent session review (separate, consent-gated)

Distinct from user feedback above: this is your short summary of how the session went — what the user tried, what worked, where they got stuck. Send it at most once, at the end of a substantive session:

comfy --json agent-review "User generated a text-to-video clip; hit a missing-model error on first try, succeeded after switching templates."

Honors every opt-out. Unlike user feedback, this is agent-authored, so it's treated as passive telemetry: it sends ONLY if the user has telemetry enabled. If they opted out by any means (DO_NOT_TRACK, COMFY_NO_TELEMETRY, or no consent), the envelope returns {"sent": false} and nothing is transmitted — that's expected, don't retry or work around it. Keep it short and factual; no secrets, no PII, no user verbatim (that's what comfy feedback is for).

---

Domain gotchas by media type

Hard-won lessons per domain. Not a tutorial — a reference card.

Image

• Survey first: comfy nodes ls --produces IMAGE --api-only (partner APIs), comfy templates ls --type image, comfy model search --type checkpoint — then choose
• Batch sweeps: comfy workflow vary for multi-prompt/seed generation
• Text rendering: use Ideogram (IdeogramV3), NOT Flux — Flux garbles text
• Partner API escape hatch (one-shots only, via the proxy — not a workflow Job): comfy generate flux-ultra --prompt "..."
• Never hardcode checkpoint/LoRA names — discover via model search

Video

• SaveVideo is REQUIRED — video API nodes produce VIDEO but are NOT output nodes
• Never hardcode fps — wire from GetVideoComponents output index 2
• Motion prompts: describe HOW the scene moves, not WHAT is in it
• Assembly: GetVideoComponents → BatchImagesNode → CreateVideo → SaveVideo (ImageBatch is deprecated)
• Autogrow inputs (type COMFY_AUTOGROW_*, e.g. BatchImagesNode images): wire ONE slot key per connection — "images.image0": [..], "images.image1": [..] — never a single images link. nodes show prints the wire_as form; comfy workflow validate rejects the bare form before submit.
• I2V pattern: LoadImage → I2VNode → SaveVideo (check nodes show for the I2V node)
• Model enums mix t2v and i2v variants — a node's model choices may include image-to-video-only models (e.g. grok-imagine-video-1.5) that fail at runtime without an image input. Capability isn't in the metadata: if the model name hints at i2v/image, wire an image or pick another model before burning a cloud run
• Provider clips come back off-spec (e.g. 5.042s @ 1924x1076) — ffprobe and normalize (crop/trim) every clip before concat/conform
• Audio sync: match durations — short audio = silent ending, long audio = truncated ending
• Talking heads (KlingAvatarNode): lip-sync is by construction — it animates the mouth FROM the sound_file you pass, so feed it the EXACT audio that plays under the shot (it carries non-speech like laughter fine, too). BUT it pads the video past the audio (trailing still frames), so clip video-duration > speech. Concatenating such clips raw drifts the voice progressively out of sync — trim each clip to its own audio length (+ a small freeze-held breath beat) before concat; never butt-join the raw clips.
• Survey first: comfy nodes ls --produces VIDEO, comfy nodes ls --category "partner/video*", comfy templates ls --type video — compare OSS, partner-API, and gallery before choosing

Audio

• ACE-Step: timesignature is "4", NOT "4/4"
• Duration on TextEncode AND EmptyLatentAudio MUST match
• Output format is FLAC, not MP3
• For instrumental: set lyrics to empty string ""
• Wire both positive AND negative to same TextEncode output when cfg=1.0
• Cloud can't load uploaded audio. LoadAudio AND VHS_LoadAudioUpload enums are blind to uploads (only ever list bedroom.mp4), even though LoadImage sees uploaded images. Don't upload→LoadAudio — it wall-fails with no signpost. Generate audio in-graph (a TTS / music node) and wire it by connection into the consumer (e.g. KlingAvatar sound_file).
• Emotional TTS: eleven_multilingual_v2 is a flat reader. For real emotion use eleven_v3 + inline performance tags in the text ([whispers], [voice breaking], [long pause]) + lower stability (~0.30) for swing. model.style caps at 0.2 (>0.2 fails validation).
• Accents the preset voices don't cover (Irish, Italian, …): coaxing a preset with an accent tag is unreliable — FB_Qwen3TTSVoiceDesign (an instruct voice description + fixed seed) builds a genuine one. Reuse the SAME instruct+seed across all of a character's lines to keep the voice consistent.
• Survey first: comfy nodes ls --produces AUDIO, comfy nodes ls --category "partner/audio*", comfy templates ls --type audio — compare before choosing

Editing (upscale, inpaint, style transfer)

• FluxProFillNode is REPLACE-ONLY — no denoise/strength param
• For refinement: use KSampler with denoise=0.15–0.25, not FluxProFill
• MagnificImageUpscalerCreativeNode: creativity 0–10, resemblance -10–10 (NOT 0–100)
• MagnificImageRelightNode style="smooth" drains color — use "brighter" or "clean"
• Local upscale: LoadImage → UpscaleModelLoader → ImageUpscaleWithModel → SaveImage
• API upscale: discover via comfy nodes search "upscale"

Conditioning (ControlNet, masks, references)

• Preprocessor output ≠ ControlNet model (two separate things)
• Don't feed raw photos into ControlNet without preprocessing first
• ImageCompositeMasked: mask MUST match SOURCE size, not destination
• COMFY_DYNAMICCOMBO_V3: use flat dotted keys ("model.max_tokens": 800), not nested. Which dotted keys are required depends on the option the selector names, and comfy validate expands that option — so it reports a missing/mistyped sub-input instead of letting /prompt reject it.
• First/last frame transitions: wire start_frame + end_frame → I2V node fills in between
• Wiring: ControlNetApplyAdvanced takes CONDITIONING + IMAGE + CONTROL_NET → modified CONDITIONING

Cloud

• Auth: comfy cloud login (OAuth) or comfy cloud set-key --key sk-…
• Check: comfy --json cloud whoami
• Custom env: comfy cloud set-base-url <url> before login
• CLI auto-injects API keys for partner nodes — never extract manually
• Session tokens are short-lived (~1h); CLI auto-refreshes on 401
• HTTP 401 with XML body = CDN catch-all, not ComfyUI — endpoints are under /api/*
• Cloud uses HTTP polling (no WebSocket); jobs watch polls /api/jobs/<id>

---

Multi-stage orchestration

Build one large workflow graph when possible — ComfyUI parallelizes independent branches automatically. Only split into separate workflows when:

• An intermediate result needs human review before continuing
• Different stages need different routing (local vs cloud)
• The workflow would exceed server memory constraints

Video productions: prefer ONE graph from keyframes to finished film. Generated VIDEO flows between nodes as wires — no save/upload round-trip — so clips + music + assembly belong in a single graph:

LoadImage($asset.s1_first.png) ×N  →  N× first/last-frame i2v nodes
  ├→ per-scene SaveVideo            (side-taps: each clip saved for review)
  └→ N× GetVideoComponents → BatchImagesNode(images.image0…N, scene order)
       → CreateVideo(fps ← GetVideoComponents, audio ← music node) → SaveVideo

The side-taps mean ONE job emits both the reviewable clips AND the assembled film; if review fails a scene, fix and re-run the graph (the extra assembly cost is small next to the video generations). The job-boundary alternative (save clips → download → assets push → LoadVideo in a second graph) is the fallback for a genuine review gate — and note its current limit: pushed images appear in LoadImage's choices, pushed videos are not yet catalogued for LoadVideo on cloud, so the cross-job video handoff requires local assembly today.

Some steps don't belong in a Comfy graph at all — final assembly, format conversion, timing/structure analysis of generated media. Comfy outputs are just files; when the graph can't express what the task needs, you're free to orchestrate your own tools around those files. How is your call — this skill defines what comfy does, not the limits of what you can do with its output.

For parallel generation, don't hand-roll fan-out with shell loops. The engine already parallelizes independent branches, so author ONE graph and let it run them concurrently. Independent fragment steps in a blueprint pipeline (those that don't wire into each other) become parallel branches. For the same pipeline across many inputs, use foreach — it instantiates the pipeline once per item into a single graph:

# blueprints/fan_out.yaml — one graph, N parallel branches via foreach
output_prefix: outputs/sweep
foreach:
  - {id: a, prompt: "a zen garden"}
  - {id: b, prompt: "a neon city"}
  - {id: c, prompt: "a desert at dusk"}
pipeline:
  - fragment: t2i               # ./fragments/t2i.json — a fragment YOU authored via the derivation loop
    alias: shot
    params:
      prompt: $item.prompt

comfy workflow compose blueprints/fan_out.yaml   # → blueprints/fan_out.compiled.json
RES=$(comfy --json run --workflow blueprints/fan_out.compiled.json)
comfy --json jobs watch "$(echo "$RES" | jq -r .data.prompt_id)"

This submits a single Job; the engine runs the independent branches concurrently. Compose embeds _meta (schema: compose/1) provenance in the compiled workflow — blueprint path plus which nodes belong to which foreach item. comfy run strips it before submit (old servers are unaffected) and stashes the map on the job state, so the terminal envelopes report outputs_by_item: {item: [url]} and comfy download names files <item>_<nnn>.<ext>. Read outputs by item, never by array order. Avoid the old PIDS=() shell-loop pattern — it duplicates scheduling the engine already does and gives you N jobs to babysit instead of one. (For a pure prompt/seed sweep over the same graph, comfy workflow vary is the right tool; for reusable parameterized generation use a recipe with workflow foreach.)

The exception — when fan-out across separate jobs IS right. A multi-shot film built on partner-API video/avatar nodes (KlingAvatar, Kling i2v, Sora, …) is the case the one-graph rule doesn't fit: each shot must fail, retry (transient_auth), and QC independently — one mega-graph sinks every shot on a single mid-run auth blip — and the final edit (cuts, ducking, loudnorm) is ffmpeg, which can't live in a Comfy graph. There you DO submit N independent jobs. The loop is: submit N → wait on all at once → download → conform:

# submit each shot, collect prompt_ids
for wf in workflows/s*.json; do
  comfy --json run --workflow "$wf" | jq -r .data.prompt_id
done > ids.txt
# block on the whole batch with one call (NOT a hand-rolled poll loop):
comfy --json jobs wait $(cat ids.txt)   # summary envelope; exit≠0 if any failed
#   --all waits on every tracked non-terminal job; --timeout bounds it;
#   a `settled` NDJSON event fires per job as it finishes (--json-stream)
xargs -a ids.txt -n1 comfy --json download   # then conform with ffmpeg (in shell)

The ffmpeg conform stage legitimately stays in shell — comfy defines what the graph does, not the limit of what you do with its outputs. This is the deliberate per-shot fan-out the foreach advice rules out for in-engine work; it is not the accidental PIDS=() babysitting loop (jobs wait replaces that). Keep the per-shot job_ids.txt / LOG.md discipline from comfy-director.

With chunk: N in a foreach blueprint, compose splits items into N-item batches and writes one numbered file per batch. The envelope then reports out: null plus written[] (all paths) — script against data.written, not data.out.

On cloud, prefer ONE graph over a stage handoff. If a generated image feeds the next step (e.g. keyframe → image-to-video), wire the producer's IMAGE output straight into the next node's image input in the same workflow. The image stays an in-graph tensor on the server — no download, no re-upload, no files. A cross-job handoff instead does cloud → local → cloud and re-transmits the full file bytes (comfy upload always re-sends the body; the cloud has no exists-by-hash skip), so it's pure waste when the graph could have expressed the edge.

Split into separate jobs (and pay the handoff) only when you genuinely need to review the intermediate before spending on the next stage — e.g. QC a keyframe before burning a 5-minute video run. That trade is often worth it; just don't split out of habit.

Stage handoff, when you do need it (download → promote into assets/ → push → $asset):

# `jobs watch` exits 0 only on completion — use && to chain safely:
comfy --json jobs watch "$PID" && comfy --json download "$PID"
# downloads land in outputs/ (item-named) — promote the keepers:
cp outputs/s1_000.png assets/s1_first.png
comfy --json assets push
# the next stage's blueprint references it directly in its inputs:
#   inputs: {start_frame: $asset.s1_first.png}

Outside a project, the legacy handoff still works: comfy --json upload <file> --where cloud, take data.uploads[0].cloud_name, paste it into the next workflow's LoadImage input — but it re-sends the bytes; prefer one graph, or the project flow.

Pipeline failure recovery: re-submit only the failed workflow. Use comfy --json jobs status <id> to identify which failed.

---

Async + parallel — cross-cuts both halves

Image generation: ~5-30s. Video generation: 2-5 minutes. Upscale chains and multi-stage pipelines: variable.

Don't block your turn on a long job — do other useful work while the watcher updates the state file, then check when you need the result. The three wait patterns are in Submit a workflow above (jobs watch, state file read, --wait). For parallelism, author one graph with independent (parallel) branches in a single blueprint rather than fanning out across jobs — see Multi-stage orchestration above.