Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution.
Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST/WebSocket API for execution.
version
5.0.0
author
["kshitijk4poor","alt-glitch"]
license
MIT
platforms
["macos","linux","windows"]
compatibility
Requires ComfyUI (local, Comfy Desktop, or Comfy Cloud) and comfy-cli (auto-installed via pipx/uvx by the setup script).
prerequisites
{"commands":["python3"]}
setup
{"help":"Run scripts/hardware_check.py FIRST to decide local vs Comfy Cloud; then scripts/comfyui_setup.sh auto-installs locally (or use Cloud API key for platform.comfy.org)."}
Generate images, video, audio, and 3D content through ComfyUI using the
official comfy-cli for setup/lifecycle and direct REST/WebSocket API
for workflow execution.
What's in this skill
Reference docs (references/):
official-cli.md — every comfy ... command, with flags
Why two layers? The official CLI is excellent for installation and server
management but has minimal workflow execution support. The REST/WS API fills
that gap — the scripts handle param injection, execution monitoring, and
output download that the CLI doesn't do.
Quick Start
Detect environment
# What's available?command -v comfy >/dev/null 2>&1 && echo"comfy-cli: installed"
curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo"server: running"# Can this machine run ComfyUI locally? (GPU/VRAM/disk check)
python3 scripts/hardware_check.py
If nothing is installed, see Setup & Onboarding below — but always run the
hardware check first.
One-line health check
python3 scripts/health_check.py
# → JSON: comfy_cli on PATH? server reachable? at least one checkpoint? smoke-test passes?
Core Workflow
Step 1: Get a workflow JSON in API format
Workflows must be in API format (each node has class_type). They come from:
ComfyUI web UI → Workflow → Export (API) (newer UI) or
the legacy "Save (API Format)" button (older UI)
This skill's workflows/ directory (ready-to-run examples)
Community downloads (civitai, Reddit, Discord) — usually editor format,
must be loaded into ComfyUI then re-exported
Editor format (top-level nodes and links arrays) is not directly
executable. The scripts detect this and tell you to re-export.
Step 2: See what's controllable
python3 scripts/extract_schema.py workflow_api.json --summary-only
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}
python3 scripts/extract_schema.py workflow_api.json
# → full schema with parameters, model deps, embedding refs
comfy model download --url <url> --relative-path models/checkpoints
"list installed models"
comfy-cli
comfy model list
"list installed nodes"
comfy-cli
comfy node show installed
Execution (use scripts)
"is everything ready?"
script
health_check.py (optionally with --workflow X --smoke-test)
"what can I change in this workflow?"
script
extract_schema.py W.json
"check if W's deps are met"
script
check_deps.py W.json
"fix missing deps"
script
auto_fix_deps.py W.json
"generate an image"
script
run_workflow.py --workflow W --args '{...}'
"use this image" (img2img)
script
run_workflow.py --input-image image=./x.png ...
"8 variations with random seeds"
script
run_batch.py --count 8 --randomize-seed ...
"show me live progress"
script
ws_monitor.py --prompt-id <id>
"fetch the error from job X"
script
fetch_logs.py <prompt_id>
Direct REST
"what's in the queue?"
REST
curl http://HOST:8188/queue (local) or --host https://cloud.comfy.org
"cancel that"
REST
curl -X POST http://HOST:8188/interrupt
"free GPU memory"
REST
curl -X POST http://HOST:8188/free
Setup & Onboarding
When a user asks to set up ComfyUI, the FIRST thing to do is ask whether
they want Comfy Cloud (hosted, zero install, API key) or Local (install
ComfyUI on their machine). Don't start running install commands or hardware
checks until they've answered.
"Do you want to run ComfyUI locally on your machine, or use Comfy Cloud?
Comfy Cloud — hosted on RTX 6000 Pro GPUs, all common models pre-installed,
zero setup. Requires an API key (paid subscription required to actually run
workflows; free tier is read-only). Best if you don't have a capable GPU.
Local — free, but your machine MUST meet the hardware requirements:
NVIDIA GPU with ≥6 GB VRAM (≥8 GB for SDXL, ≥12 GB for Flux/video), OR
AMD GPU with ROCm support (Linux), OR
Apple Silicon Mac (M1+) with ≥16 GB unified memory (≥32 GB recommended).
Intel Macs and machines with no GPU will NOT work — use Cloud instead.
Which would you like?"
Routing:
Cloud → skip to Path A.
Local → run hardware check first, then pick a path from Paths B–E based on the verdict.
Unsure → run the hardware check and let the verdict decide.
Step 1: Verify Hardware (ONLY if user chose local)
python3 scripts/hardware_check.py --json
# Optional: also probe `torch` for actual CUDA/MPS:
python3 scripts/hardware_check.py --json --check-pytorch
Verdict
Meaning
Action
ok
≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon)
Local install — use comfy_cli_flag from report
marginal
SD1.5 works; SDXL tight; Flux/video unlikely
Local OK for light workflows, else Path A (Cloud)
cloud
No usable GPU, <6 GB VRAM, <16 GB Apple unified, Intel Mac, Rosetta Python
Switch to Cloud unless user explicitly forces local
The script also surfaces wsl: true (WSL2 with NVIDIA passthrough) and
rosetta: true (x86_64 Python on Apple Silicon — must reinstall as ARM64).
If verdict is cloud but the user wants local, do not proceed silently.
Show the notes array verbatim and ask whether they want to (a) switch to
Cloud or (b) force a local install (will OOM or be unusably slow on modern models).
Choosing an Installation Path
Use the hardware check first. The table below is the fallback for when the
user has already told you their hardware:
Situation
Recommended Path
verdict: cloud from hardware check
Path A: Comfy Cloud
No GPU / want to try without commitment
Path A: Comfy Cloud
Windows + NVIDIA + non-technical
Path B: ComfyUI Desktop
Windows + NVIDIA + technical
Path C: Portable or Path D: comfy-cli
Linux + any GPU
Path D: comfy-cli (easiest)
macOS + Apple Silicon
Path B: Desktop or Path D: comfy-cli
Headless / server / CI / agents
Path D: comfy-cli
For the fully automated path (hardware check → install → launch → verify):
bash scripts/comfyui_setup.sh
# Or with overrides:
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
It runs hardware_check.py internally, refuses to install locally when the
verdict is cloud (unless --force-cloud-override), picks the right
comfy-cli flag, and prefers pipx/uvx over global pip to avoid polluting
system Python.
Path A: Comfy Cloud (No Local Install)
For users without a capable GPU or who want zero setup. Hosted on RTX 6000 Pro.
Pricing:https://www.comfy.org/cloud/pricingConcurrent jobs: Free/Standard 1, Creator 3, Pro 5. Free tier
cannot run workflows via API — only browse models. Paid subscription
required for /api/prompt, /api/upload/*, /api/view, etc.
Path B: ComfyUI Desktop (Windows / macOS)
One-click installer for non-technical users. Currently Beta.
Auth:X-API-Key header (or ?token=KEY for WebSocket)
API key: set $COMFY_CLOUD_API_KEY once and the scripts pick it up automatically
Output download:/api/view returns a 302 to a signed URL; the scripts
follow it and strip X-API-Key before fetching from the storage backend
(don't leak the API key to S3/CloudFront).
Endpoint differences from local ComfyUI:
/api/object_info, /api/queue, /api/userdata — 403 on free tier;
paid only.
/history is renamed to /history_v2 on cloud (the scripts route
automatically).
/models/<folder> is renamed to /experiment/models/<folder> on cloud
(the scripts route automatically).
clientId in WebSocket is currently ignored — all connections for a
user receive the same broadcast. Filter by prompt_id client-side.
subfolder is accepted on uploads but ignored — cloud has a flat namespace.
Concurrent jobs: Free/Standard: 1, Creator: 3, Pro: 5. Extras queue
automatically. Use run_batch.py --parallel N to saturate your tier.
Queue & System Management
# Local
curl -s http://127.0.0.1:8188/queue | python3 -m json.tool <!-- scanner-allow:curl_pipe_python -->
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'# cancel pending
curl -X POST http://127.0.0.1:8188/interrupt # cancel running
curl -X POST http://127.0.0.1:8188/free \
-H "Content-Type: application/json" \
-d '{"unload_models": true, "free_memory": true}'# Cloud — same paths under /api/, plus:
python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
Pitfalls
API format required — every script and the /api/prompt endpoint expect
API-format workflow JSON. The scripts detect editor format (top-level
nodes and links arrays) and tell you to re-export via
"Workflow → Export (API)" (newer UI) or "Save (API Format)" (older UI).
Server must be running — all execution requires a live server.
comfy launch --background starts one. Verify with
curl http://127.0.0.1:8188/system_stats.
Model names are exact — case-sensitive, includes file extension.
check_deps.py does fuzzy matching (with/without extension and folder
prefix), but the workflow itself must use the canonical name. Use
comfy model list to discover what's installed.
Missing custom nodes — "class_type not found" means a required node
isn't installed. check_deps.py reports which package to install;
auto_fix_deps.py runs the install for you.
Working directory — comfy-cli auto-detects the ComfyUI workspace.
If commands fail with "no workspace found", use
comfy --workspace /path/to/ComfyUI <command> or
comfy set-default /path/to/ComfyUI.
Cloud free-tier API limits — /api/prompt, /api/view, /api/upload/*,
/api/object_info all return 403 on free accounts. health_check.py and
check_deps.py handle this gracefully and surface a clear message.
Timeout for video/audio workflows — auto-detected when an output node
is VHS_VideoCombine, SaveVideo, etc.; the default jumps from 300 s to
900 s. Override explicitly with --timeout 1800.
Path traversal in output filenames — server-supplied filenames are
passed through safe_path_join to refuse anything escaping --output-dir.
Keep this protection on — workflows with custom save nodes can produce
arbitrary paths.
Workflow JSON is arbitrary code — custom nodes run Python, so
submitting an unknown workflow has the same trust profile as eval.
Inspect workflows from untrusted sources before running.
Auto-randomized seed — pass seed: -1 in --args (or use
--randomize-seed and omit the seed) to get a fresh seed per run.
The actual seed is logged to stderr.
tracking prompt — first run of comfy may prompt for analytics.
Use comfy --skip-prompt tracking disable to skip non-interactively.
comfyui_setup.sh does this for you.
Verification Checklist
Use python3 scripts/health_check.py to run the whole list at once. Manual:
hardware_check.py verdict is ok OR the user explicitly chose Comfy Cloud
comfy --version works (or uvx --from comfy-cli comfy --help)
curl http://HOST:PORT/system_stats returns JSON
comfy model list shows at least one checkpoint (local) OR
/api/experiment/models/checkpoints returns models (cloud)
Workflow JSON is in API format
check_deps.py reports is_ready: true (or only node_check_skipped
on cloud free tier)
Test run with a small workflow completes; outputs land in --output-dir
