> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-feat-openapi-i18n.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install comfy-cli, set up local or cloud routing, generate with partner nodes, and run workflows from the terminal.

## Overview

`comfy-cli` is a [command line tool](https://github.com/Comfy-Org/comfy-cli) that streamlines installation and management of Comfy, and gives you scriptable, single-command access to the entire ComfyUI ecosystem locally or in the cloud.

It serves three primary functions:

1. **Manage a local ComfyUI installation** — install, launch, update, snapshot, and bisect ComfyUI and custom nodes.
2. **Access hosted partner nodes** — generate images, video, audio, and 3D from providers including Seedance, Nano Banana (Gemini), Grok, Flux, Ideogram, DALL·E, Recraft, Stability, Kling, Luma, Runway, Pika, Vidu, Hailuo, Moonvalley, and others with single commands.
3. **Run full workflows on Comfy Cloud** — submit workflow graphs, browse the curated template gallery, slot-edit workflows, and watch jobs to completion without a local GPU.

<Note>
  **Two surfaces, one CLI.** Every command auto-detects where to run. If you are signed in to Comfy Cloud, commands route to **cloud**; otherwise they run against your **local** server. Override per call with `--where local|cloud`, the `COMFY_WHERE` env var, or persist it with `comfy set-default --where cloud`.
</Note>

## Install CLI

<CodeGroup>
  ```bash pip theme={null}
  pip install comfy-cli
  ```

  ```bash homebrew theme={null}
  brew tap Comfy-Org/comfy-cli
  brew install comfy-org/comfy-cli/comfy-cli
  ```
</CodeGroup>

To get shell completion hints:

```bash theme={null}
comfy --install-completion
```

## Quick Setup (Recommended)

New in recent versions: a single interactive wizard that handles routing, auth, and agent skills in one step.

```bash theme={null}
comfy setup
```

It walks you through choosing a routing target (local or cloud), **signing in through your browser (OAuth)**, picking a project directory, and optionally installing the agent skills. This is the recommended path. It opens the browser sign-in for you, with no keys to copy.

```bash theme={null}
comfy setup --where cloud
```

<Note>
  **Non-interactive (CI only).** Browser OAuth needs an interactive session. For CI, devcontainers, and scripted installs where no browser is available, pass an API key instead:

  ```bash theme={null}
  comfy setup --where cloud --api-key comfyui-... --non-interactive
  ```
</Note>

| Flag                    | Purpose                                                                   |
| ----------------------- | ------------------------------------------------------------------------- |
| `--where local\|cloud`  | Routing target; skips the prompt                                          |
| `--project-dir`         | Directory for workflows, inputs, and outputs                              |
| `--api-key`             | *(Optional)* Comfy Cloud API key for headless/CI; implies `--where cloud` |
| `-y, --non-interactive` | No prompts. Drive everything from flags                                   |
| `--skip-skills`         | Do not install agent skills                                               |
| `--skip-verify`         | Skip the connectivity check                                               |

## Install ComfyUI (Local)

Create a virtual environment with any Python version greater than 3.9.

<CodeGroup>
  ```bash conda theme={null}
  conda create -n comfy-env python=3.11
  conda activate comfy-env
  ```

  ```bash venv theme={null}
  python3 -m venv comfy-env
  source comfy-env/bin/activate
  ```
</CodeGroup>

Install ComfyUI

```bash theme={null}
comfy install
```

<Warning>You still need to install CUDA, or ROCm depending on your GPU.</Warning>

## Run ComfyUI (Local)

```bash theme={null}
comfy launch
```

Run in the background and stop it later:

```bash theme={null}
comfy launch --background
comfy stop
```

Check which workspace is selected and what is installed:

```bash theme={null}
comfy which
comfy env
```

## Comfy Cloud

Run workflows and partner nodes on Comfy's hosted GPUs. No local install required.

```bash theme={null}
comfy cloud login          # browser OAuth + PKCE
comfy cloud whoami         # show sign-in status, auth method, base URL
comfy cloud logout         # clear the local session
```

Once signed in, commands auto-route to cloud. **Browser OAuth is the recommended path.** No keys to manage, and the CLI handles token refresh for you. To point at a custom environment (for example a PR preview) before signing in:

```bash theme={null}
comfy cloud set-base-url https://my-preview.comfy.org
```

<Note>
  **API key is optional.** You only need an API key for headless or CI use where a browser sign-in is not possible. It is a fallback, not the default:

  ```bash theme={null}
  export COMFY_API_KEY=comfyui-...   # or pass --api-key per call
  ```
</Note>

<Note>
  **Session lifetime.** Cloud session tokens are short-lived (\~1h). The CLI auto-refreshes them on demand. If a command reports `cloud_unauthorized`, run `comfy cloud login` again.
</Note>

## Generate with Partner Nodes

<Info>
  **`comfy generate` is in beta.** Flag names, model aliases, and output formats may change. The underlying partner endpoints are stable. File feedback on the [comfy-cli GitHub repo](https://github.com/Comfy-Org/comfy-cli/issues).
</Info>

The fastest way to call Comfy's [partner nodes](/tutorials/partner-nodes/overview) from a terminal or script. It hits the same hosted endpoints as ComfyUI workflows, but as single CLI calls. Ideal for batch jobs, quick experiments, and automation where a full ComfyUI graph is unnecessary.

### Prerequisites

* An active Comfy Cloud session via `comfy cloud login` (browser OAuth), **or** a [Comfy API key](/development/api-development/getting-an-api-key) (`--api-key` / `COMFY_API_KEY`) for headless or CI use
* [Credits](/interface/credits) on your account
* *Optional:* [Browse partner nodes and per-call pricing](/tutorials/partner-nodes/pricing)

### First generation

```bash theme={null}
comfy generate flux-pro \
    --prompt "a cat on the moon, cinematic lighting" \
    --width 1024 --height 1024 \
    --download cat.png
```

The CLI uploads local files, submits the job, polls for completion, and saves results.

<Tip>
  Discover a model's real parameters first. Flag names differ per model (for example `flux-ultra` takes `--width`/`--height`; `seedance` takes `--ratio`/`--resolution`/`--duration`). Always check before scripting:

  ```bash theme={null}
  comfy generate schema flux-ultra
  ```
</Tip>

### Common models

**Nano Banana (Google Gemini): text-to-image and editing:**

```bash theme={null}
comfy generate nano-banana \
    --prompt "a watercolor of a sleeping fox" \
    --download fox.png

# Image editing:
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

# Specify a model variant:
comfy generate nano-banana \
    --prompt "neon city skyline" \
    --model gemini-3-pro-image-preview \
    --download city.png
```

**Flux 1.1 Pro Ultra: high-resolution text-to-image:**

```bash theme={null}
comfy generate flux-ultra \
    --prompt "a purple Victorian house in San Francisco, golden hour" \
    --width 896 --height 1152 --seed 11 \
    --download house.png
```

**Seedance (ByteDance): text-to-video and image-to-video, up to 1080p / 12s:**

```bash theme={null}
# Text-to-video:
comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

# Image-to-video (animate a local image, auto-uploaded):
comfy generate seedance \
    --model seedance-1-0-pro-250528 \
    --image ./painting.png \
    --ratio 3:4 --resolution 1080p --duration 5 \
    --prompt "the painting gently comes alive, a soft breeze stirs the trees" \
    --download animated.mp4
```

**Grok (xAI): images and video:**

```bash theme={null}
comfy generate grok --prompt "a cyberpunk street market at night" --download street.png
comfy generate grok-edit --prompt "swap the umbrella for a parasol" --image ./photo.jpg --download out.png
comfy generate grok-video --prompt "a paper plane gliding through a cathedral" --download flight.mp4
```

### Discover models

```bash theme={null}
comfy generate list                            # all models
comfy generate list --category text-to-video   # filter by category
comfy generate list --partner kling            # filter by partner
comfy generate schema flux-kontext             # view a model's parameters
```

### Image editing with references

Pass local file paths. The CLI uploads via Comfy's storage endpoint or base64-encodes as needed:

```bash theme={null}
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

comfy generate flux-kontext \
    --prompt "add a top hat and a monocle" \
    --input_image ./photo.jpg \
    --download out.png

comfy generate ideogram-edit \
    --image cat.png --mask mask.png \
    --prompt "add sunglasses" \
    --rendering_speed TURBO \
    --download edited.png
```

To upload once and reuse across calls:

```bash theme={null}
comfy generate upload ./photo.jpg     # prints a signed URL
```

<Note>
  Uploaded reference assets auto-delete after **24 hours**. They are stored in Comfy-managed GCS with signed URLs. For long-running pipelines, re-upload before each job. See the [reference](/comfy-cli/reference#upload) for details.
</Note>

### Video generation (async jobs)

Video jobs are async. The CLI blocks and polls by default:

```bash theme={null}
comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

comfy generate kling \
    --prompt "a paper boat drifting on a river at dusk" \
    --duration 5 \
    --download boat.mp4
```

Return immediately with `--async`, then resume later:

```bash theme={null}
comfy generate luma --prompt "neon koi swimming through clouds" --aspect_ratio 16:9 --async
# prints a job id; resume with:
comfy generate resume luma <job_id> --download out.mp4
```

### JSON output for scripts

Emit raw API responses for pipeline integration:

```bash theme={null}
comfy generate dalle --prompt "a watercolor whale" --json | jq '.data[0].url'
```

See the [reference](/comfy-cli/reference) for the full list of commands, flags, and model aliases.

## Run Workflows (`comfy run`)

Beyond single partner calls, `comfy run` submits a complete ComfyUI workflow graph. It accepts both API-format and exported UI-format JSON (UI workflows are converted to API format client-side), and routes to local or cloud like every other command. It is **async by default**. It returns a `prompt_id` in milliseconds while a background watcher tracks progress. Pass `--wait` to block instead.

```bash theme={null}
# Submit; returns immediately with a prompt_id
RES=$(comfy --json run --workflow my_workflow.json)
PROMPT_ID=$(echo "$RES" | jq -r .data.prompt_id)

# Watch until terminal, then collect outputs
comfy --json jobs watch "$PROMPT_ID" | comfy download
```

Prefer a single blocking call? Use `--wait`:

```bash theme={null}
comfy run --workflow my_workflow.json --wait | comfy download
```

Track and manage jobs:

```bash theme={null}
comfy jobs ls                 # local async submits + server queue/history
comfy jobs status <prompt_id> # one job
comfy jobs wait <id1> <id2>   # block until ALL reach a terminal state
comfy jobs cancel <prompt_id> # idempotent
```

<Tip>
  Validate before you submit. Catch unknown nodes, missing models, and bad wiring before burning cloud compute:

  ```bash theme={null}
  comfy validate --workflow my_workflow.json
  ```
</Tip>

## Start from a Template

The curated `Comfy-Org/workflow_templates` gallery is the fastest way to get a known-good workflow for a given task. You do not need to build from scratch.

```bash theme={null}
comfy templates ls --type image --tag "Text to Image"   # browse
comfy templates show <name>                              # full metadata
comfy templates fetch <name> --out my.json               # pull the workflow JSON
```

The downloaded JSON is frontend-format. `comfy run --where cloud` auto-converts it to API format on submit.

## Edit Workflows In Place

`comfy workflow` exposes the agent-tweakable slots in any frontend-format workflow and lets you override them. No manual JSON surgery.

```bash theme={null}
comfy workflow slots my.json                 # list addressable slots
comfy workflow set-slot my.json 6.text="a fox in the snow"
comfy workflow vary my.json \
    --slot positive.text='["a cat","a dog","a fox"]' \
    --out-dir ./variants                     # fan out N variants
```

Saved workflows on Comfy Cloud:

```bash theme={null}
comfy workflow list                          # your saved workflows
comfy workflow get <id> --out my.json
comfy workflow save my.json --name "My Flow"
comfy workflow delete <id>
```

For complex multi-step pipelines, compose small reusable fragments into one graph:

```bash theme={null}
comfy workflow compose blueprints/my_pipeline.yaml -o workflows/my_pipeline.json
comfy workflow decompose my.json             # inverse: project a workflow into a fragment
```

## Discover Nodes and Models

Introspect everything available on the resolved backend.

**Nodes:**

```bash theme={null}
comfy nodes search "checkpoint"              # fuzzy search
comfy nodes show KSampler                    # full schema: inputs, outputs, defaults
comfy nodes ls --produces IMAGE --limit 10   # filter by output type
comfy nodes ls --api-only                    # partner-API nodes only
```

**Models:**

```bash theme={null}
comfy models list-folders                    # every model folder
comfy models search --text "wan2.2" --type lora
comfy models show wan2.2_vae.safetensors     # full metadata
```

## Upload and Download Files

```bash theme={null}
comfy upload photo.png video.mp4             # → server input directory
comfy download <prompt_id>                   # → ./outputs/
```

<Tip>
  **The idiomatic pipe:**

  ```bash theme={null}
  comfy run --workflow flux.json --wait | comfy download
  ```

  `comfy download` reads the prompt\_id and output URLs from piped stdin automatically. No manual key extraction, no `jq`.
</Tip>

## Manage Custom Nodes

```bash theme={null}
comfy node install <NODE_NAME>
```

The tool uses `cm-cli` for custom node installation. See the [ComfyUI Manager cm-cli docs](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/cm-cli.md) for details.

## Manage Models (Local)

Download models easily:

```bash theme={null}
comfy model download --url <url> --relative-path models/checkpoints
```

## JSON Output for Scripts and Agents

Every command accepts `--json` and emits the same envelope shape, making the CLI fully scriptable and agent-friendly:

```json theme={null}
{
  "ok": true,
  "command": "...",
  "version": "1.11.1",
  "where": "local | cloud | null",
  "data": { },
  "error": null
}
```

When `error` is present, read the `hint` and act on it:

```bash theme={null}
comfy --json run --workflow my.json | jq '.error.hint'
```

The agent-facing surface is fully self-describing. Dump the entire command tree, output schemas, and error codes:

```bash theme={null}
comfy --json discover
```

## Agent Skills

Install the bundled Comfy agent skills into Claude Code, Cursor, and any AGENTS.md-aware tool, so your coding agent can drive the CLI directly:

```bash theme={null}
comfy skills install
comfy skills list      # comfy, comfy-fragments, comfy-debug, comfy-relay, comfy-director
comfy skills status    # what's installed where
```

<Note>
  These are **bundled CLI skills** installed by `comfy skills install`. They are separate from the [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) repository, which hosts the **comfy-cloud** Claude Code plugin for [Comfy Cloud MCP](/agent-tools/cloud).
</Note>

## Contributing

Contributions are welcome. Open issues or submit pull requests on the [comfy-cli GitHub repository](https://github.com/Comfy-Org/comfy-cli/issues). Refer to the [Dev Guide](https://github.com/Comfy-Org/comfy-cli/blob/main/DEV_README.md) for further details.

## Analytics

Usage tracking helps improve the CLI. Disable it with:

```bash theme={null}
comfy tracking disable
```

Re-enable tracking:

```bash theme={null}
comfy tracking enable
```

You can also hard opt-out via the `DO_NOT_TRACK` or `COMFY_NO_TELEMETRY` environment variables.