Skip to main content
The runcomfy CLI runs RunComfy AI media models from your terminal or any AI agent. It wraps the Model API so you can submit a request, wait for completion, and have the result automatically downloaded — in one command. 
runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt": "a small purple cat at sunset"}'
Repository: runcomfy-com/runcomfy-cli

​
What it gives you

  • One command end-to-end — submit, poll, fetch the result, and download generated files into your working directory.
  • Pipe-friendly — --output json emits a single line of JSON to stdout (stderr stays empty in JSON mode), so runcomfy ... | jq ... works in scripts.
  • AI-agent-friendly — every progress line goes to stderr; final payload to stdout; sysexits-style exit codes (64 usage / 65 data / 69 upstream / 75 retryable / 77 auth) so callers branch on failure type without parsing strings.
  • Browser OAuth — runcomfy login opens a device-code flow in your browser. No long-lived API key copy-paste, and no token in your shell history.
  • Streaming downloads, with safety — multi-hundred-MB video outputs stream straight to disk; downloads are restricted to RunComfy CDN hosts so a compromised model can’t trick the CLI into pulling arbitrary content.

​
Commands at a glance

CommandPurpose
loginOAuth authentication via the browser (device-code flow)
logoutClear the local token
whoamiShow the currently authenticated user
runRun a Model API model end-to-end
statusPoll a Model API request’s status
cancelCancel a queued or running request
completionGenerate a shell completion script
Aliases: runcomfy requests get and runcomfy requests cancel are equivalent to runcomfy status / runcomfy cancel.

​
Next steps

  • Quickstart — install, log in, generate your first image.
  • Install — npx, npm i -g, curl install.sh, build from source.
  • Authentication — device-code flow, RUNCOMFY_TOKEN for CI, where the token is stored.
  • Troubleshooting — exit codes, common errors, proxy issues.