SKILL.md
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 -gInstall the CLI
Pick one:
# Global install via npm (recommended for repeat use)
npm i -g @runcomfy/cliZero-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](https://docs.runcomfy.com/cli/install?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli). **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](https://docs.runcomfy.com/cli/install?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli).
## 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](https://docs.runcomfy.com/cli/auth?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli).
## 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](https://docs.runcomfy.com/cli/quickstart?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli).
## 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](https://www.runcomfy.com/models?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | All featured models |
| [/models/all](https://www.runcomfy.com/models/all?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | The full catalog |
| [/models/collections/recently-added](https://www.runcomfy.com/models/collections/recently-added?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | Fresh additions |
| [/models/collections/nano-banana](https://www.runcomfy.com/models/collections/nano-banana?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/seedream](https://www.runcomfy.com/models/collections/seedream?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/flux-kontext](https://www.runcomfy.com/models/collections/flux-kontext?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/kling](https://www.runcomfy.com/models/collections/kling?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/seedance](https://www.runcomfy.com/models/collections/seedance?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/veo-3](https://www.runcomfy.com/models/collections/veo-3?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/wan-models](https://www.runcomfy.com/models/collections/wan-models?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/hailuo](https://www.runcomfy.com/models/collections/hailuo?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [/qwen-image](https://www.runcomfy.com/models/collections/qwen-image?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | Curated brand collections |
| [/models/feature/lip-sync](https://www.runcomfy.com/models/feature/lip-sync?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | Lip-sync capability |
| [/models/feature/character-swap](https://www.runcomfy.com/models/feature/character-swap?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | Character / face swap |
| [/models/feature/upscale-video](https://www.runcomfy.com/models/feature/upscale-video?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) | Video upscalers |
## Commands
### runcomfy run
Synchronous run — submit, poll, download.
| Flag | What |
| --- | --- |
| `--input ' '` | Inline JSON body. Strings can contain newlines; quote-escape as needed |
| `--input-file ` | Read body from a file (JSON or YAML by extension) |
| `--output-dir ` | 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 ` | 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
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](https://docs.runcomfy.com/cli/commands?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli).
## 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