runcomfy-cli

What this skill does

# 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](https://www.runcomfy.com/?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [CLI docs](https://docs.runcomfy.com/cli/introduction?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli) · [All models](https://www.runcomfy.com/models?utm_source=skills.sh&utm_medium=skill&utm_campaign=runcomfy-cli)

## Install this skill

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

## Install the CLI

Pick one:

```bash
# 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](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:

```bash
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):

```bash
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):

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

Verify:

```bash
runcomfy whoami
# 📛 [email protected]
#    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:

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

Example — generate an image with GPT Image 2:

```bash
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:

```bash
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 <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:

```bash
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

```bash
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

```bash
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

```bash
# 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:

```bash
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