runcomfy-cli

RunComfy CLI

One binary, one auth, every RunComfy model. Install once, sign in once, then call any text-to-image, video, edit, lip-sync, face-swap, or LoRA-training endpoint with runcomfy run <model_id> --input '{...}'. This skill is the foundation every other runcomfy-* skill builds on.

runcomfy.com · CLI docs · All models

Install this skill

npx skills add agentspace-so/runcomfy-agent-skills --skill runcomfy-cli -g

Install the CLI

Pick one:

# Global install via npm (recommended for repeat use)
npm i -g @runcomfy/cli

# Zero-install one-shot (no Node global state)
npx -y @runcomfy/cli --version

A standalone curl-pipe installer also exists for environments without Node — see docs.runcomfy.com/cli/install. Inspect any install script before piping it into a shell. This skill only invokes the CLI via Bash(runcomfy *) after you have installed it through one of the verified package managers above.

Confirm:

runcomfy --version

Full options on the Install page.

Sign in

Interactive (opens browser):

runcomfy login
# Code shown in terminal — paste into the browser page, click Authorize
# Token saved to ~/.config/runcomfy/token.json with mode 0600

CI / containers (no browser):

export RUNCOMFY_TOKEN=<token-from-runcomfy.com/profile>

Verify:

runcomfy whoami
# 📛 you@example.com
#    token type: cli
#    user id: ...

Full flow + token rotation: Authentication.

Run a model

The general shape:

runcomfy run <vendor>/<model>/<endpoint> \
  --input '<JSON body>' \
  --output-dir <path>

Example — generate an image with GPT Image 2:

runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt": "a small purple cat at sunset, photorealistic"}'

You will see:

⏳ Submitting request to openai/gpt-image-2/text-to-image
   request_id: 8a3f...
⏳ Polling status (every 2s)...
   in_queue
   in_progress
   completed
✅ completed
{
  "images": [
    "https://playgrounds-storage-public.runcomfy.net/.../result.png"
  ]
}
📥 Downloading 1 file(s) to .
   ./result.png

By default the result is downloaded to the current directory. Override with --output-dir ./out, skip downloading with --no-download.

Quickstart: docs.runcomfy.com/cli/quickstart.

Discover model schemas

Every model has an API tab on its detail page with the exact input schema. Browse the catalog:

open https://www.runcomfy.com/models

Or search by collection / capability:

| URL | What | |---|---| | /models | All featured models | | /models/all | The full catalog | | /models/collections/recently-added | Fresh additions | | /models/collections/nano-banana · /seedream · /flux-kontext · /kling · /seedance · /veo-3 · /wan-models · /hailuo · /qwen-image | Curated brand collections | | /models/feature/lip-sync | Lip-sync capability | | /models/feature/character-swap | Character / face swap | | /models/feature/upscale-video | Video upscalers |

Commands

runcomfy run <model_id>

Synchronous run — submit, poll, download.

| Flag | What | |---|---| | --input '<JSON>' | Inline JSON body. Strings can contain newlines; quote-escape as needed | | --input-file <path> | Read body from a file (JSON or YAML by extension) | | --output-dir <path> | Where to download result files (default: cwd) | | --no-download | Skip the download step; only print the result JSON | | --no-wait | Submit and return request_id immediately; don't poll | | --timeout <seconds> | Cap the polling wait. Default: model-dependent | | --output json | Print machine-readable JSON for piping (default human-readable) | | --quiet | Suppress progress, keep only the final result line |

runcomfy login / runcomfy whoami / runcomfy logout

login runs the device-code flow; whoami prints the active identity; logout removes the local token file. Set RUNCOMFY_TOKEN env var to override the file entirely.

runcomfy status <request_id>

Check status of a --no-wait job:

RID=$(runcomfy --output json run google/nano-banana-2/text-to-image \
  --input '{"prompt": "..."}' --no-wait | jq -r .request_id)

runcomfy status "$RID"

Full command reference: docs.runcomfy.com/cli/commands.

Scripting patterns

Pipe-friendly JSON

runcomfy --output json run openai/gpt-image-2/text-to-image \
  --input '{"prompt": "X"}' \
  --no-download \
| jq -r '.images[0]'

Batch from a file of prompts

while IFS= read -r prompt; do
  runcomfy run blackforestlabs/flux-2-klein/9b/text-to-image \
    --input "$(jq -nc --arg p "$prompt" '{prompt:$p, steps:8}')" \
    --output-dir "./out/$(date +%s%N)"
done < prompts.txt

Submit now, poll later

# Submit one or many jobs without blocking
RID=$(runcomfy --output json run bytedance/seedance-v2/pro \
  --input '{"prompt": "..."}' --no-wait | jq -r .request_id)

# Later — possibly from a different shell:
runcomfy status "$RID"

Retry on transient failure

The CLI returns exit code 75 on retryable errors (timeout, 429). Wrap with a shell retry loop:

for i in 1 2 3; do
  runcomfy run <model_id> --input '{...}' && break
  rc=$?
  [ $rc -eq 75 ] && sleep $((2**i)) && continue
  exit $rc
done

Exit codes

| code | meaning | retry? | |---|---|---| | 0 | success | — | | 64 | bad CLI