Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runcomfy.com/llms.txt

Use this file to discover all available pages before exploring further.

The CLI supports two authentication paths: an interactive device-code OAuth flow for humans, and a token env var for CI / containers. Both produce the same kind of token: a row in the user_tokens table tied to your RunComfy account, sent as Authorization: Bearer <token> to the Model API and other RunComfy services.

​
Device-code flow (runcomfy login)

The everyday path for human users. Standard OAuth 2.0 device authorization grant — same shape as gh auth login or stripe login. 
runcomfy login
The CLI:
  1. Calls POST https://www.runcomfy.com/api/cli-auth/start and receives a short user_code (e.g. ABCD-1234).
  2. Prints the code prominently in your terminal.
  3. Opens https://www.runcomfy.com/cli-auth in your browser.
  4. Polls POST .../cli-auth/poll every two seconds.
In the browser:
  1. Sign in (magic link or any other configured provider).
  2. Type or paste the code from the terminal into the form. The page deliberately doesn’t accept a ?code=… query string, so a stranger can’t send you a pre-filled link to phish your token.
  3. Click Authorize.
The CLI saves the resulting token to ~/.config/runcomfy/token.json (Unix mode 0600). 
runcomfy whoami     # confirms it worked
runcomfy logout     # remove the local token
Tokens are minted fresh on every runcomfy login (token_type='cli' in user_tokens) and can be revoked independently of any other API tokens you have on your Profile page.

​
CI / container env var (RUNCOMFY_TOKEN)

In a non-interactive environment, set RUNCOMFY_TOKEN to bypass the device-code flow entirely: 
export RUNCOMFY_TOKEN=<your-api-token>
runcomfy whoami
runcomfy run openai/gpt-image-2/text-to-image --input '{"prompt": "..."}'
The env var takes precedence over ~/.config/runcomfy/token.json. Get the token from your Profile page (the “API Token” section) — that token is interchangeable with one minted by runcomfy login, just with a different token_type. For GitHub Actions: 
- run: runcomfy run ${{ inputs.model_id }} --input '${{ inputs.body }}'
  env:
    RUNCOMFY_TOKEN: ${{ secrets.RUNCOMFY_TOKEN }}

​
Where the token lives

SourceLocationWhen used
RUNCOMFY_TOKEN env varn/aAlways wins if set
runcomfy login$XDG_CONFIG_HOME/runcomfy/token.json or ~/.config/runcomfy/token.jsonDefault location on Linux/macOS/Windows
OverrideRUNCOMFY_CONFIG_DIR=<path>Useful for tests / sandboxes
Legacy macOS~/Library/Application Support/runcomfy/token.jsonRead-only fallback for older builds
The file is mode 0600 (only your user can read), and runcomfy login writes it atomically (temp file + rename(2)) so a crash mid-write can’t corrupt it.

​
Revoking a token

  • Local logout: runcomfy logout removes the token file. The token is still valid server-side until you also revoke it.
  • Server-side revoke: rotate or delete the row from your Profile page.

​
Security notes

  • The token is plaintext in user_tokens.token server-side. (Token-at-rest hashing is on the roadmap but does not change CLI behavior.)
  • Don’t commit token.json or echo $RUNCOMFY_TOKEN in CI logs.
  • The CLI never logs the token: runcomfy -v ... and RUST_LOG=reqwest=trace ... redact the Authorization header.
  • If you suspect a token leak: rotate immediately on the Profile page, then runcomfy logout && runcomfy login.