RunComfy API Docs

The CLI covers three RunComfy products plus your account balance. All commands accept the global flags --output {pretty,json}, -q/--quiet, -v/--verbose, and all except login / logout require authentication (Authentication).

Group	Commands	API
Auth	`login`, `logout`, `whoami`	Web auth
Account	`balance`	Serverless API
Model catalog	`models list`, `models categories`, `models get`	Model API
Model requests	`run`, `status`, `result`, `cancel`	Model API
Deployments	`deployments list/get/create/update/delete`	Serverless API
Deployment inference	`deployments run/status/result/cancel/proxy`	Serverless API
Datasets	`datasets create/list/status/delete/upload`	Trainer API
Training jobs	`train submit/status/result/cancel/resume/edit`	Trainer API

Aliases: runcomfy requests get ≡ runcomfy status, runcomfy requests result ≡ runcomfy result, runcomfy requests cancel ≡ runcomfy cancel. For exit-code semantics across all commands, see Troubleshooting → Exit codes.

Authenticate the CLI with RunComfy via the device-code OAuth flow.

runcomfy login [--web-base <URL>]

Calls POST {web_base}/api/cli-auth/start, receives a short user code and a verification URL.

Prints the code in the terminal:

🔑 Opening the authorization page in your browser
   If your browser doesn't open, visit:  https://www.runcomfy.com/cli-auth

       YOUR CODE:  ABCD-1234

   Type or paste this code into the page, then click Authorize.

Opens the verification URL in your default browser.
Polls POST {web_base}/api/cli-auth/poll every 2 seconds.
On Authorize, saves the access token to ~/.config/runcomfy/token.json (mode 0600).
Ctrl-C aborts the wait cleanly.

Flag	Description
`--web-base <URL>`	Override the auth host (default `https://www.runcomfy.com`). Useful for staging / preview environments. Also reads `RUNCOMFY_WEB_BASE`.

In CI or any non-interactive environment, set RUNCOMFY_TOKEN=<token> and skip runcomfy login entirely.

`logout`

runcomfy logout

Removes the local token file. Does not revoke the token server-side — for that, rotate it on your Profile page.

`whoami`

Show the currently authenticated user.

runcomfy whoami
# 📛 you@example.com
#    token type: cli
#    user id: 36312e13-1b55-45c5-80f7-5382bd18c98b

In --output json mode the same data goes to stdout as a single line, useful for scripts:

USER_ID=$(runcomfy --output json whoami | jq -r .id)

Backs GET https://www.runcomfy.com/api/auth/me.

`balance`

Show the account’s remaining balance. One wallet funds every product — Model API requests, Serverless deployments, and training jobs all draw it down.

runcomfy balance
# balance: $64.11 USD

--output json returns the raw record, including balance_microdollars for exact threshold checks:

runcomfy --output json balance
# {"balance_microdollars":64106410,"balance_usd":64.11,"currency":"USD"}

Backs GET /prod/v2/balance.

`models`

Browse the hosted catalog that run executes — find a model_id, then read its Input schema before building a request.

`models list`

runcomfy models list [--search <TEXT>] [--category <CATEGORY>] [--kind <KIND>]
                     [--include-schema] [--limit <N>] [--offset <N>]

Flag	Default	Description
`--search <TEXT>`	—	Case-insensitive match on model_id, display name, or description
`--category <CATEGORY>`	—	Capability filter, e.g. `text-to-image`, `image-to-video`
`--kind <KIND>`	—	How the model runs: `model`, `workflow`, or `inference`
`--include-schema`	false	Include every model’s full `input_schema` (large; prints JSON)
`--limit <N>`	100	Page size, 1–500
`--offset <N>`	0	Rows to skip

runcomfy models list --search kontext --limit 5
# MODEL_ID                                           NAME              CATEGORY        PRICE
# blackforestlabs/flux-1-kontext/dev/image-to-image  Flux Kontext Dev  image-to-image  $0.06/output
# blackforestlabs/flux-1-kontext/pro/edit            FLUX Kontext      image-to-image  $0.044/output
# ...
#    Showing 1-5 of 5 (page with --offset/--limit; filter with --search/--category)

In --output json mode the raw catalog payload comes back, including inputs, required_inputs, base_price_usd, and model_url. Backs GET /v1/models.

`models categories`

runcomfy models categories
# audio-to-audio
# image-to-image
# image-to-video
# text-to-image
# ...

Pass any of these to models list --category. Backs GET /v1/models/categories.

`models get`

runcomfy models get blackforestlabs/flux-1-kontext/pro/edit

Prints the model’s description, categories, price, and full input_schema — property types, defaults, enums, and ranges. Read this instead of guessing parameter names for run --input. Properties whose format is image_uri / video_uri / audio_uri take a public HTTPS URL. Backs GET /v1/models/{model_id}.

`run`

Run a Model API model end-to-end: submit, poll, fetch the result, download generated files.

runcomfy run <model_id> [--input <JSON> | --input-file <PATH>]
                        [--no-wait] [--poll-secs <N>]
                        [--output-dir <DIR>] [--no-download]

<model_id> is the slash-separated identifier from the Models catalog (e.g. blackforestlabs/flux-1-kontext/pro/edit, openai/gpt-image-2/text-to-image).

Flag	Default	Description
`--input '<JSON>'`	—	Inline JSON payload matching the model’s Input schema
`--input-file <PATH>`	—	Read JSON input from a file. Use `-` for stdin. Mutually exclusive with `--input`.
`--no-wait`	false	Submit and return the request_id immediately; don’t poll
`--poll-secs <N>`	2	Polling interval in seconds while waiting
`--output-dir <DIR>`	`.`	Where to download generated files
`--no-download`	false	Skip file download; only print the result JSON

Examples

# Inline input
runcomfy run blackforestlabs/flux-1-kontext/pro/edit \
  --input '{"prompt": "a small purple cat", "aspect_ratio": "16:9"}'

# Input from a file
runcomfy run openai/gpt-image-2/text-to-image --input-file ./req.json

# Input from stdin
echo '{"prompt": "piped"}' | \
  runcomfy run openai/gpt-image-2/text-to-image --input-file -

# Submit and return immediately
runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt":"..."}' --no-wait
# {"request_id":"8a3f...","wait":false}

# JSON-only output for scripts
runcomfy --output json run openai/gpt-image-2/text-to-image \
  --input '{"prompt":"..."}' --no-wait | jq -r .request_id

# Save outputs to a specific directory
runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt":"..."}' --output-dir ./out

# Print the result URL but don't download
runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt":"..."}' --no-download

End-to-end output

⏳ 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

Stdout receives the result JSON; stderr receives the progress lines (or [tag] text if not a TTY / NO_COLOR is set).

Behavior details

Submit: POST https://model-api.runcomfy.net/v1/models/<model_id> with the JSON body as-is (Model API expects flat input, not {"input":{...}}).
Poll: GET .../requests/<id>/status every --poll-secs seconds.
Fetch: on terminal status (completed / succeeded / failed / cancelled), GET .../requests/<id>/result.
Download whitelist: the CLI scans the result JSON recursively and downloads every URL whose host ends with .runcomfy.net or .runcomfy.com. URLs outside that whitelist are listed but not fetched — preventing a compromised upstream model from coercing the CLI into pulling arbitrary internet content. Downloads stream to disk and abort with unlink(2) if the response exceeds 2 GiB.
Ctrl-C: while polling, sends POST .../requests/<id>/cancel to RunComfy before exiting. If the cancel call itself fails, the CLI prints the request_id and tells you to retry with runcomfy cancel <id> — so you don’t get billed for GPU you thought was stopped.

`status`

Poll the status of a Model API request submitted via runcomfy run --no-wait.

runcomfy status <request_id>
# request_id: 8a3fbf12-...
# status:     in_progress
# status_url: https://model-api.runcomfy.net/v1/requests/.../status
# result_url: https://model-api.runcomfy.net/v1/requests/.../result

If still queued, the output also includes queue: position N.

status	Meaning
`in_queue`	Waiting for a runner; `queue_position` shows how many ahead
`in_progress`	Running on GPU
`completed` / `succeeded`	Done; fetch the output via `runcomfy run` (same `request_id`) or curl `result_url`
`failed`	Run errored; fetch `result_url` for the failure reason
`cancelled`	Cancelled (by you or by the platform)

The CLI doesn’t loop — it returns the current snapshot and exits. Wrap in your own while loop for repeated checks. Backs GET .../requests/<id>/status.

`result`

Fetch the result record of a request submitted with run --no-wait, and download its files.

runcomfy result <request_id> [--output-dir <DIR>] [--no-download]

runcomfy result 8a3fbf12-... --output-dir ./out
# ✅ completed
# {
#   "request_id": "8a3fbf12-...",
#   "status": "completed",
#   "output": { "image": "https://playgrounds-storage-public.runcomfy.net/.../result.jpeg" },
#   "created_at": "...",
#   "completed_at": "..."
# }
# 📥 Downloading 1 file(s) to ./out
#    ./out/result.jpeg

Unlike run, this never submits anything — it reads an existing request. Calling it before the request finishes prints the current record and exits 0; a failed or cancelled request exits non-zero. Alias: runcomfy requests result. Backs GET /v1/requests/{id}/result.

`cancel`

Cancel a queued or running Model API request.

runcomfy cancel <request_id>
# ✅ Cancelled 8a3fbf12-... (final status: cancelled)

If already terminal:

ℹ 8a3fbf12-... is already terminal (succeeded); cancel is a no-op

In --output json mode, the response includes an outcome field (cancelled or not_cancellable). runcomfy run (without --no-wait) auto-cancels on Ctrl-C, so you only need cancel directly when you submitted with --no-wait, the auto-cancel failed, or you’re cancelling someone else’s request_id. Backs POST .../requests/<id>/cancel (returns 202 Accepted).

`deployments`

Manage Serverless API (ComfyUI) deployments and run inference on them. Unlike run, which uses hosted catalog models, these run your own cloud-saved ComfyUI workflows on hardware you choose.

`deployments list` and `deployments get`

runcomfy deployments list [--ids <ID>,<ID>] [--include-payload] [--include-readme]
runcomfy deployments get <deployment_id> [--include-payload] [--include-readme]

runcomfy deployments list
# ID                                    NAME             STATUS    ENABLED  HARDWARE   INSTANCES  VERSION
# a1b2c3d4-...                          text-to-image    standby   true     AMPERE_48  0-1        v1

--include-payload adds workflow_api_json — use it to discover the node IDs and input names that deployments run --overrides targets. Backs GET /prod/v2/deployments[/{id}].

`deployments create`

runcomfy deployments create --name <NAME> --workflow-id <UUID> --workflow-version <VERSION>
                            [--hardware <SKU>] [--min-instances <N>] [--max-instances <N>]
                            [--queue-size <N>] [--keep-warm-secs <SECS>]

Flag	Default	Description
`--name`	required	Human-readable name
`--workflow-id`	required	UUID of the cloud-saved ComfyUI workflow
`--workflow-version`	required	Version label, e.g. `v1`
`--hardware <SKU>`	`AMPERE_48`	`TURING_16`, `AMPERE_24`, `AMPERE_48`, `ADA_48_PLUS`, `AMPERE_80`, `ADA_80_PLUS`, `HOPPER_141`
`--min-instances <N>`	0	Warm instance floor (0–30); billable when > 0
`--max-instances <N>`	1	Concurrency ceiling (1–60)
`--queue-size <N>`	1	Pending requests per instance before scaling out
`--keep-warm-secs <SECS>`	60	Idle seconds before an instance scales down

For LoRA deployments, create via the RunComfy UI (Trainer → LoRA Assets → Deploy), then use deployments list to get the id. Backs POST /prod/v2/deployments.

`deployments update`

Only the flags you pass are changed.

runcomfy deployments update <deployment_id> [--name <NAME>] [--workflow-version <VERSION>]
                            [--hardware <SKU>] [--min-instances <N>] [--max-instances <N>]
                            [--queue-size <N>] [--keep-warm-secs <SECS>] [--enable | --disable]

--disable pauses the deployment (instances shut down, billing stops, configuration is preserved); --enable resumes it. Backs PATCH /prod/v2/deployments/{id}.

`deployments delete`

runcomfy deployments delete <deployment_id> [-y/--yes]

Permanent. Prompts for confirmation on a terminal; in a non-interactive shell it refuses with exit 64 unless --yes is given. Consider deployments update <id> --disable to pause instead. Backs DELETE /prod/v2/deployments/{id}.

`deployments run`

Submit an inference request and, by default, wait for it.

runcomfy deployments run <deployment_id>
                         [--overrides <JSON> | --overrides-file <PATH>]
                         [--workflow-file <PATH>] [--extra-data <JSON>]
                         [--webhook-url <URL>] [--webhook-intermediate]
                         [--no-wait] [--poll-secs <N>] [--timeout <SECS>]
                         [--output-dir <DIR>] [--no-download]

Flag	Description
`--overrides <JSON>`	Partial workflow graph keyed by node ID
`--overrides-file <PATH>`	Same, read from a file (`-` for stdin)
`--workflow-file <PATH>`	Advanced: run a full `workflow_api.json` inline without updating the deployment
`--extra-data <JSON>`	e.g. `{"api_key_comfy_org": "comfyui-..."}` for ComfyUI Core API nodes
`--webhook-url <URL>`	Push-based status updates instead of polling
`--webhook-intermediate`	Fire the webhook on every status change, not just terminal ones
`--timeout <SECS>`	Stop waiting after this long (the request keeps running)

One of --overrides, --overrides-file or --workflow-file is required — the API rejects an empty body.

runcomfy deployments run a1b2c3d4-... \
  --overrides '{"6": {"inputs": {"text": "a futuristic cityscape at sunset"}},
                "189": {"inputs": {"image": "https://example.com/input.jpg"}}}'

File inputs take a public HTTPS URL or a Base64 data: URI directly in the override value. Ctrl-C while waiting cancels the remote request. Backs POST /prod/v2/deployments/{id}/inference.

`deployments status`, `result` and `cancel`

runcomfy deployments status <deployment_id> <request_id>
runcomfy deployments result <deployment_id> <request_id> [--output-dir <DIR>] [--no-download]
runcomfy deployments cancel <deployment_id> <request_id>

status also prints instance_id once an instance is running your job — that’s what deployments proxy needs. Output URLs from result are hosted for 7 days. A cancel that the API has only accepted reports Cancellation requested; poll status to confirm it reaches canceled.

`deployments proxy`

Call a ComfyUI backend endpoint on a live instance.

runcomfy deployments proxy <deployment_id> <instance_id> <path> [--body <JSON> | --body-file <PATH>]

# Unload models to free GPU memory
runcomfy deployments proxy a1b2c3d4-... 1697cb1a-... api/free \
  --body '{"unload_models": true, "free_memory": true}'

Instance IDs are ephemeral — valid only while that instance is running. Backs POST /prod/v2/deployments/{id}/instances/{instance_id}/proxy/{path}.

`datasets`

Manage LoRA training datasets. A dataset must reach READY before a training job can mount it.

`datasets create`, `list`, `status` and `delete`

runcomfy datasets create [--name <NAME>]
runcomfy datasets list
runcomfy datasets status <dataset_id>
runcomfy datasets delete <dataset_id> [-y/--yes]

The dataset’s name (not its id) is what an AI Toolkit config references in folder_path. status shows the lifecycle — DRAFT → UPLOADING → READY (or FAILED) — plus the files that uploaded successfully.

runcomfy datasets status 9a2efbab-...
# id:         9a2efbab-...
# name:       my-dataset
# status:     READY
#
# FILENAME      SIZE_BYTES
# img_0001.png  215290
# img_0001.txt  24

`datasets upload`

runcomfy datasets upload <dataset_id> [PATH]...
                         [--from-url <URL> [--filename <NAME>]]
                         [--wait] [--poll-secs <N>]

Each path is a file, or a directory whose top-level files are uploaded. Files up to 150 MB go through the direct upload endpoint; larger ones automatically fetch a signed URL and stream the bytes to storage. Re-uploading a filename overwrites the previous copy. Every image or video needs a caption .txt with the same base name — img_0001.jpg pairs with img_0001.txt.

# A whole folder, then wait until the dataset is READY
runcomfy datasets upload 9a2efbab-... ./my-dataset/ --wait

# A file the server should fetch from a public URL
runcomfy datasets upload 9a2efbab-... --from-url https://example.com/a.jpg --filename img_0002.jpg

--wait polls until READY (or FAILED, which exits non-zero). Ctrl-C while waiting stops watching; the uploads are already done.

`train`

Submit and manage AI Toolkit training jobs — typically LoRA training.

`train submit`

runcomfy train submit --config <PATH> [--gpu-type <TYPE>] [--gpu-count <N>] [--gpu-id <ID>]
                      [--wait] [--poll-secs <N>] [--timeout <SECS>]

Flag	Default	Description
`--config <PATH>`	required	Complete AI Toolkit YAML config (`-` reads stdin)
`--gpu-type <TYPE>`	`ADA_80_PLUS`	`ADA_80_PLUS` (H100) or `HOPPER_141` (H200)
`--gpu-count <N>`	1	`1`, or `8` for multi-GPU (`ADA_80_PLUS` only)
`--wait`	false	Poll until the job finishes, then print its result

Two paths in the config are fixed by the platform:

training_folder: "/app/ai-toolkit/output"
datasets:
  - folder_path: "/app/ai-toolkit/datasets/{dataset_name}"

where {dataset_name} is the dataset’s name from datasets list. Training runs for hours, so the command returns as soon as the job is queued unless you pass --wait. With --wait, Ctrl-C stops watching but does not cancel the job.

`train status` and `train result`

runcomfy train status <job_id>
runcomfy train result <job_id> [--download] [--output-dir <DIR>]

Lifecycle: IN_QUEUE → RUNNING → STOPPED (finished or preempted), FAILED, or CANCELED. status prints step progress:

runcomfy train status 7f2c...
# id:       7f2c...
# name:     my_lora
# status:   RUNNING
# progress: 16% (step 320/2000)

result lists checkpoints, the resolved config, and samples as hosted URLs. It is safe to call while the job is still RUNNING — the artifact list grows over time — and after a FAILED or CANCELED job to recover whatever was produced. Downloads are opt-in via --download because checkpoints are large. A checkpoint URL can be fed straight back to run without deploying anything:

runcomfy run <base_model_id> \
  --input '{"prompt": "...", "lora": {"path": "my_lora_3000.safetensors"}}'

The path is either a name from your LoRA Assets or a public URL.

`train cancel`, `resume` and `edit`

runcomfy train cancel <job_id>
runcomfy train resume <job_id>
runcomfy train edit <job_id> --config <PATH>

cancel stops progress; artifacts produced so far stay available through train result. resume restarts from the highest-step checkpoint under the same job_id (from step 0 if none exists) — useful after a preemption. edit replaces the config of a STOPPED / CANCELED / FAILED job, after which resume re-queues it; config.name must still match the original job’s name.

Getting Started

Reference

Commands

`logout`

`whoami`

`balance`

`models`

`models list`

`models categories`

`models get`

`run`

Examples

End-to-end output

Behavior details

`status`

`result`

`cancel`

`deployments`

`deployments list` and `deployments get`

`deployments create`

`deployments update`

`deployments delete`

`deployments run`

`deployments status`, `result` and `cancel`

`deployments proxy`

`datasets`

`datasets create`, `list`, `status` and `delete`

`datasets upload`

`train`

`train submit`

`train status` and `train result`

`train cancel`, `resume` and `edit`

​login

​logout

​whoami

​balance

​models

​models list

​models categories

​models get

​run

​Examples

​End-to-end output

​Behavior details

​status

​result

​cancel

​deployments

​deployments list and deployments get

​deployments create

​deployments update

​deployments delete

​deployments run

​deployments status, result and cancel

​deployments proxy

​datasets

​datasets create, list, status and delete

​datasets upload

​train

​train submit

​train status and train result

​train cancel, resume and edit

`login`

`logout`

`whoami`

`balance`

`models`

`models list`

`models categories`

`models get`

`run`

Examples

End-to-end output

Behavior details

`status`

`result`

`cancel`

`deployments`

`deployments list` and `deployments get`

`deployments create`

`deployments update`

`deployments delete`

`deployments run`

`deployments status`, `result` and `cancel`

`deployments proxy`

`datasets`

`datasets create`, `list`, `status` and `delete`

`datasets upload`

`train`

`train submit`

`train status` and `train result`

`train cancel`, `resume` and `edit`