Complete Comfy CLI User Guide

Comfy CLI is the official command-line tool for ComfyUI — install, manage nodes and models, run workflows, and call partner image/video models, all from your terminal.

ℹ️ Note about updates: For the most up-to-date CLI reference, check the official README or docs.comfy.org.

Requirements

Python 3.10+

Installation

Recommended: Using pip

pip install comfy-cli

Using pipx (isolated environment)

pipx install comfy-cli

Using uv (fast Python package installer)

uv tool install comfy-cli

Shell Autocomplete

comfy --install-completion

Now comfy <TAB> expands commands and options.

Quick Start

# Run the interactive setup wizard
comfy setup

comfy setup walks you through everything — local or cloud routing, authentication, and agent skill installation — in one interactive wizard. Pass -y for non-interactive (CI/scripted) installs.

Alternatively, install explicitly:

comfy install

Then launch:

comfy launch

Workspace Management

Comfy CLI supports managing multiple ComfyUI workspaces, allowing you to maintain different ComfyUI environments simultaneously.

Basic Workspace Operations

# Check current workspace path
comfy which

# Set default workspace
comfy set-default /path/to/your/workspace

# Set default workspace with launch parameters
comfy set-default /path/to/your/workspace --launch-extras="--listen 0.0.0.0 --port 8080"

Executing Commands in Different Workspaces

Option	Use Case
`--workspace=<path>`	Run from ComfyUI installed in the specified workspace
`--recent`	Run from the most recently used ComfyUI
`--here`	Run from ComfyUI in the current directory

# Launch ComfyUI in specified workspace
comfy --workspace=~/projects/project-a launch

# Install nodes in recent workspace
comfy --recent node install ComfyUI-Impact-Pack

# Check if current directory has ComfyUI
comfy --here which

Note: --workspace, --recent, and --here cannot be used together.

Workspace Priority Rules

When no workspace is specified:

Default path set by comfy set-default <path>
Most recently executed or installed ComfyUI
ComfyUI in the current directory

Launch Options

Basic Launch

# Default launch
comfy launch

# Run in background
comfy launch --background

# Stop background instance
comfy stop

# Launch with extra args
comfy launch -- --cpu --listen 0.0.0.0

Network Configuration

comfy launch -- --listen 0.0.0.0 --port 8080

Performance Options

comfy launch -- --cpu       # CPU-only mode
comfy launch -- --lowvram   # Low VRAM mode
comfy launch -- --novram     # Ultra-low VRAM mode

Testing Pull Requests

# Install a specific ComfyUI PR
comfy install --pr "#1234"
comfy install --pr "https://github.com/comfyanonymous/ComfyUI/pull/1234"

# Test a frontend PR
comfy launch --frontend-pr "#456"
comfy launch --frontend-pr "username:branch-name"

Frontend PR builds are cached for quick switching. Manage the cache:

comfy pr-cache list              # List cached PR builds
comfy pr-cache clean             # Clean all cached builds
comfy pr-cache clean 456         # Clean specific PR cache

Custom Node Management

View Node Information

comfy node show all                               # All available nodes
comfy node simple-show installed                  # Simple list of installed nodes
comfy node show enabled                           # Enabled nodes only
comfy node show not-installed                     # Uninstalled nodes
comfy node show disabled                          # Disabled nodes
comfy node show all --channel recent              # Nodes from recent channel
comfy node show snapshot                          # View current snapshot info
comfy node show snapshot-list                     # List saved snapshots

Install and Update Nodes

comfy node install ComfyUI-Impact-Pack            # Install a custom node
comfy node update all                             # Update all nodes
comfy node update ComfyUI-Impact-Pack             # Update a specific node

Fast Dependency Resolution

Comfy CLI offers two ways to use uv for faster dependency resolution:

Feature	`--fast-deps`	`--uv-compile`
Scope	`comfy install`, node install/reinstall	Custom node commands only
Resolver	comfy-cli built-in	ComfyUI-Manager v4.1+ unified resolver
Conflict handling	Interactive prompt	Automatic with node attribution

# Fast initial install
comfy install --fast-deps

# uv-compile for custom node management (requires ComfyUI-Manager v4.1+)
comfy node install comfyui-impact-pack --uv-compile

# Run standalone (resolve all existing custom node dependencies)
comfy node uv-sync

# Make --uv-compile the default
comfy manager uv-compile-default true

Node Snapshot Management

comfy node save-snapshot                           # Save current snapshot
comfy node restore-snapshot <snapshot_name>        # Restore a saved snapshot

Dependency Management

comfy node install-deps --workflow=workflow.json   # From workflow JSON
comfy node install-deps --workflow=workflow.png    # From workflow PNG
comfy node install-deps --deps=dependencies.json   # From dep JSON file
comfy node deps-in-workflow --workflow=workflow.json --output=deps.json

Node Troubleshooting (Bisect)

Pinpoint which custom node is causing a bug:

comfy node bisect start                            # Start bisect session
comfy node bisect good                             # Mark current state as good
comfy node bisect bad                              # Mark current state as bad
comfy node bisect reset                            # Reset session

Generate Images Without Workflow JSON

Comfy CLI can directly call partner image and video models — no workflow graph required:

comfy generate --prompt "a cat on a beach" --model flux/schnell
comfy generate --prompt "anime girl" --model stability/stable-diffusion-3.5
comfy generate --prompt "city street" --model ideogram/ideogram-v2

Supported providers include: Flux, Ideogram, DALL·E, Recraft, Stability, Gemini, Kling, Luma, Runway, Pika, Vidu, Hailuo, Seedance, and more.

Route to Cloud

Run any workflow on Comfy Cloud (no local GPU required):

comfy launch -- --where cloud
# or
comfy generate --model recraft/recraft-v3 --where cloud

Structured Output for Agents

Every command supports --json for machine-readable output — ideal for CI/CD and AI agent integration:

comfy generate --prompt "a cat" --model flux/schnell --json

Model Management

Download Models

# From Hugging Face
comfy model download --url https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors --relative-path models/checkpoints

# From CivitAI
comfy model download --url https://civitai.com/api/download/models/123456 --relative-path models/checkpoints

# With API token
comfy model download --url https://civitai.com/api/download/models/123456 --set-civitai-api-token YOUR_TOKEN

API tokens can also be set via environment variables (CIVITAI_API_TOKEN, HF_API_TOKEN), which is safer for CI/CD environments.

Manage Models

comfy model list                                  # List models in default path
comfy model list --relative-path models/loras     # List in subfolder
comfy model remove --model-names "model.safetensors"  # Remove a model

ComfyUI-Manager Management

comfy manager disable-gui                         # Disable Manager GUI
comfy manager enable-gui                          # Enable Manager GUI
comfy manager clear                               # Clear reserved startup actions

Environment Information

comfy env                                         # Show detailed environment info
comfy tracking status                             # Check tracking settings
comfy tracking disable                            # Disable usage tracking
comfy tracking enable                             # Enable usage tracking

Advanced Features

comfy-lock.yaml (Beta)

Use a comfy-lock.yaml file to manage project dependencies:

basic:

models:
  - model: SD1.5 Base
    url: https://huggingface.co/...
    paths:
      - path: models/checkpoints
    hashes:
      - hash: abc123...
        type: SHA256
    type: checkpoint

custom_nodes:
  git_custom_nodes:
    https://github.com/user/ComfyUI-Node:
      disabled: false
      hash: a1b2c3d...

Common Usage Scenarios

Development Environment Management

# Create workspace for stable development
comfy --workspace=~/dev/comfyui-stable install

# Create workspace for experimental features
comfy --workspace=~/dev/comfyui-experimental install

# Install experimental nodes
comfy --workspace=~/dev/comfyui-experimental node install ComfyUI-AnimateDiff-Evolved

Project Dependency Management

# Create a snapshot for a project
comfy node save-snapshot my-project-v1

# Restore project dependencies
comfy node restore-snapshot my-project-v1

# Install workflow dependencies
comfy node install-deps --workflow=project.json

Troubleshooting

Common Issues

Workspace path issues

comfy which              # Check current workspace
comfy set-default /path  # Reset to correct path

Node conflicts

comfy node bisect start  # Use bisect to locate the problematic node

Permission issues

ls -la ~/comfy           # Check directory permissions