메인 콘텐츠로 건너뛰기

개요

comfy-cli는 Comfy의 설치 및 관리를 간소화하고 로컬 또는 클라우드에서 전체 ComfyUI 생태계에 대해 스크립트 가능한 단일 명령 액세스를 제공하는 명령줄 도구입니다. 세 가지 주요 기능을 제공합니다:
  1. 로컬 ComfyUI 설치 관리: ComfyUI 및 커스텀 노드 설치, 실행, 업데이트, 스냅샷, bisect.
  2. 호스팅된 파트너 노드 접근: 단일 명령으로 Seedance, Nano Banana (Gemini), Grok, Flux, Ideogram, DALL·E, Recraft, Stability, Kling, Luma, Runway, Pika, Vidu, Hailuo, Moonvalley 등 제공업체의 이미지, 비디오, 오디오, 3D 생성.
  3. Comfy Cloud에서 전체 워크플로 실행: 워크플로 그래프 제출, 큐레이션된 템플릿 갤러리 찾아보기, 워크플로 슬롯 편집, 로컬 GPU 없이 작업 완료까지 모니터링.
두 가지 표면, 하나의 CLI. 모든 명령이 자동으로 실행 위치를 감지합니다. Comfy Cloud에 로그인한 경우 명령은 클라우드로 라우팅되고, 그렇지 않으면 로컬 서버에서 실행됩니다. 각 호출 시 --where local|cloud로 재정의하거나, COMFY_WHERE 환경 변수를 사용하거나, comfy set-default --where cloud로 영구 설정할 수 있습니다.

CLI 설치

pip install comfy-cli
셸 자동완성 힌트를 얻으려면:
comfy --install-completion

빠른 설정 (권장)

최근 버전의 새로운 기능: 한 번에 라우팅, 인증 및 에이전트 기술을 처리하는 단일 대화형 마법사입니다.
comfy setup
라우팅 대상(로컬 또는 클라우드) 선택, 브라우저를 통한 로그인(OAuth), 프로젝트 디렉터리 선택, 그리고 선택적으로 에이전트 기술 설치 과정을 안내합니다. 이것이 권장되는 경로입니다. 복사할 키 없이 브라우저 로그인 창을 열어줍니다.
comfy setup --where cloud
비대화형(CI 전용). 브라우저 OAuth는 대화형 세션이 필요합니다. CI, devcontainer 및 브라우저를 사용할 수 없는 스크립트 설치의 경우 API 키를 대신 전달하세요:
comfy setup --where cloud --api-key comfyui-... --non-interactive
플래그목적
--where local|cloud라우팅 대상; 프롬프트 생략
--project-dir워크플로, 입력 및 출력 디렉터리
--api-key(선택 사항) 헤드리스/CI용 Comfy Cloud API 키이며, --where cloud를 암시합니다.
-y, --non-interactive프롬프트 없음. 모든 것을 플래그로 처리합니다.
--skip-skills에이전트 기술을 설치하지 않음
--skip-verify연결 확인 건너뛰기

ComfyUI 설치 (로컬)

Python 버전 3.9보다 높은 버전을 사용하여 가상 환경을 생성하세요.
conda create -n comfy-env python=3.11
conda activate comfy-env
ComfyUI 설치하기
comfy install
GPU에 따라 CUDA 또는 ROCm를 여전히 설치해야 합니다.

ComfyUI 실행 (로컬)

comfy launch
배경에서 실행하고 나중에 중지:
comfy launch --background
comfy stop
선택된 워크스페이스와 설치된 내용 확인:
comfy which
comfy env

Comfy Cloud

Comfy의 호스팅 GPU에서 워크플로와 파트너 노드를 실행하세요. 로컬 설치가 필요 없습니다.
comfy cloud login          # 브라우저 OAuth + PKCE
comfy cloud whoami         # 로그인 상태, 인증 방법, 기본 URL 표시
comfy cloud logout         # 로컬 세션 지우기
로그인하면 명령이 자동으로 클라우드로 라우팅됩니다. 브라우저 OAuth가 권장되는 방법입니다. 관리할 키가 없으며 CLI가 토큰 새로 고침을 처리합니다. 로그인 이전에 사용자 지정 환경(예: PR 미리보기)을 가리키려면:
comfy cloud set-base-url https://my-preview.comfy.org
API 키는 선택 사항입니다. 브라우저 로그인이 불가능한 헤드리스 또는 CI 사용에서만 API 키가 필요합니다. 이는 기본값이 아닌 대체 수단입니다:
export COMFY_API_KEY=comfyui-...   # 또는 호출 시 --api-key 전달
세션 수명. 클라우드 세션 토큰은 수명이 짧습니다(~1시간). CLI는 필요에 따라 자동으로 새로 고칩니다. 명령에서 cloud_unauthorized를 보고하면 comfy cloud login을 다시 실행하세요.

파트너 노드로 생성하기

comfy generate는 베타 버전입니다. 플래그명, 모델 별칭 및 출력 형식은 변경될 수 있습니다. 기본 파트너 엔드포인트는 안정적입니다. 피드백은 comfy-cli GitHub 저장소에 제출해 주세요.
터미널이나 스크립트에서 Comfy의 파트너 노드를 호출하는 가장 빠른 방법입니다. ComfyUI 워크플로와 동일한 호스팅 엔드포인트를 사용하지만, 단일 CLI 호출로 실행됩니다. 전체 ComfyUI 그래프가 필요 없는 배치 작업, 빠른 실험 및 자동화에 이상적입니다.

사전 준비 사항

첫 번째 생성

comfy generate flux-pro \
    --prompt "a cat on the moon, cinematic lighting" \
    --width 1024 --height 1024 \
    --download cat.png
CLI가 로컬 파일을 업로드하고 작업을 제출하며 완료를 폴링하고 결과를 저장합니다.
먼저 모델의 실제 파라미터를 확인하세요. 플래그 이름은 모델마다 다릅니다 (예: flux-ultra--width/--height, seedance--ratio/--resolution/--duration 사용). 스크립팅 전에 항상 확인하세요:
comfy generate schema flux-ultra

일반적인 모델

Nano Banana (Google Gemini): 텍스트 기반 이미지 생성 및 편집:
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: 고해상도 텍스트 기반 이미지 생성:
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): 텍스트 기반 비디오 생성 및 이미지 기반 비디오 생성, 최대 1080p / 12초:
# 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): 이미지 및 비디오:
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

모델 검색

comfy generate list                            # 모든 모델
comfy generate list --category text-to-video   # 카테고리로 필터
comfy generate list --partner kling            # 파트너로 필터
comfy generate schema flux-kontext             # 모델의 파라미터 보기

참조 이미지를 사용한 이미지 편집

로컬 파일 경로를 전달합니다. CLI는 Comfy의 스토리지 엔드포인트를 통해 업로드하거나 필요에 따라 base64로 인코딩합니다:
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
한 번 업로드하고 여러 호출에서 재사용하려면:
comfy generate upload ./photo.jpg     # prints a signed URL
업로드된 참조 에셋은 24시간 이후 자동으로 삭제됩니다. Comfy 관리 GCS에 서명된 URL로 저장됩니다. 오래 실행되는 파이프라인의 경우 각 작업 이전에 다시 업로드하세요. 자세한 내용은 참조를 확인하세요.

비디오 생성 (비동기 작업)

비디오 작업은 비동기입니다. CLI는 기본적으로 차단 및 폴링합니다:
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
--async를 사용하면 즉시 반환하고 나중에 다시 시작합니다:
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 출력

파이프라인 통합을 위해 원시 API 응답을 내보냅니다:
comfy generate dalle --prompt "a watercolor whale" --json | jq '.data[0].url'
전체 명령어, 플래그 및 모델 별칭 목록은 참조를 확인하세요.

워크플로 실행 (comfy run)

단일 파트너 호출을 넘어, comfy run은 완전한 ComfyUI 워크플로 그래프를 제출합니다. API 형식과 내보낸 UI 형식 JSON을 모두 허용하며 (UI 워크플로는 클라이언트 측에서 API 형식으로 변환됨), 다른 모든 명령과 마찬가지로 로컬 또는 클라우드로 라우팅합니다. 기본적으로 비동기입니다. 백그라운드 감시자가 진행 상황을 추적하는 동안 밀리초 단위로 prompt_id를 반환합니다. 대신 --wait를 전달하여 차단합니다.
# 제출; prompt_id와 함께 즉시 반환
RES=$(comfy --json run --workflow my_workflow.json)
PROMPT_ID=$(echo "$RES" | jq -r .data.prompt_id)

# 터미널 상태가 될 때까지 감시한 다음 출력 수집
comfy --json jobs watch "$PROMPT_ID" | comfy download
단일 차단 호출을 선호하시나요? --wait를 사용하세요:
comfy run --workflow my_workflow.json --wait | comfy download
작업 추적 및 관리:
comfy jobs ls                 # 로컬 비동기 제출 + 서버 실행 대기열/기록
comfy jobs status <prompt_id> # 하나의 작업
comfy jobs wait <id1> <id2>   # ALL이 터미널 상태에 도달할 때까지 차단
comfy jobs cancel <prompt_id> # 멱등성
제출하기 전에 유효성을 검사하세요. 클라우드 컴퓨팅을 사용하기 전에 알 수 없는 노드, 누락된 모델 및 잘못된 연결을 찾아내세요:
comfy validate --workflow my_workflow.json

템플릿으로 시작하기

엄선된 Comfy-Org/workflow_templates 갤러리는 주어진 작업에 대한 검증된 워크플로를 얻는 가장 빠른 방법입니다. 처음부터 만들 필요가 없습니다.
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
다운로드된 JSON은 프론트엔드 형식입니다. comfy run --where cloud가 제출 시 자동으로 API 형식으로 변환합니다.

워크플로 직접 편집

comfy workflow 명령어는 프론트엔드 형식의 모든 워크플로에서 에이전트가 조정 가능한 슬롯을 노출하고 덮어쓸 수 있게 해줍니다. 수동으로 JSON을 수정할 필요가 없습니다.
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
Comfy Cloud에 저장된 워크플로:
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>
복잡한 다단계 파이프라인의 경우, 작은 재사용 가능한 조각을 하나의 그래프로 구성할 수 있습니다:
comfy workflow compose blueprints/my_pipeline.yaml -o workflows/my_pipeline.json
comfy workflow decompose my.json             # inverse: project a workflow into a fragment

노드 및 모델 발견

해결된 백엔드에서 사용할 수 있는 모든 것을 검사하세요. 노드:
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
모델:
comfy models list-folders                    # every model folder
comfy models search --text "wan2.2" --type lora
comfy models show wan2.2_vae.safetensors     # full metadata

파일 업로드 및 다운로드

comfy upload photo.png video.mp4             # → server input directory
comfy download <prompt_id>                   # → ./outputs/
관용적인 파이프 사용법:
comfy run --workflow flux.json --wait | comfy download
comfy download는 파이프로 연결된 stdin에서 prompt_id와 출력 URL을 자동으로 읽습니다. 수동으로 키를 추출하거나 jq를 사용할 필요가 없습니다.

커스텀 노드 관리

comfy node install <NODE_NAME>
이 도구는 커스텀 노드 설치를 위해 cm-cli를 사용합니다. 자세한 내용은 ComfyUI Manager cm-cli 문서를 참조하세요.

모델 관리 (로컬)

모델을 쉽게 다운로드합니다:
comfy model download --url <url> --relative-path models/checkpoints

스크립트 및 에이전트를 위한 JSON 출력

모든 명령은 --json을 허용하며 동일한 봉투 형태를 출력하므로 CLI를 완전히 스크립트 가능하고 에이전트 친화적으로 만듭니다:
{
  "ok": true,
  "command": "...",
  "version": "1.11.1",
  "where": "local | cloud | null",
  "data": { },
  "error": null
}
error가 있을 때는 hint를 읽고 그에 따라 조치하십시오:
comfy --json run --workflow my.json | jq '.error.hint'
에이전트를 위한 인터페이스는 완전히 자체 설명적입니다. 전체 명령 트리, 출력 스키마 및 오류 코드를 덤프합니다:
comfy --json discover

에이전트 스킬

번들된 Comfy 에이전트 스킬을 Claude Code, Cursor 및 AGENTS.md를 인식하는 모든 도구에 설치하여 코딩 에이전트가 CLI를 직접 사용할 수 있도록 합니다:
comfy skills install
comfy skills list      # comfy, comfy-fragments, comfy-debug, comfy-relay, comfy-director
comfy skills status    # 설치된 위치 확인
이는 comfy skills install로 설치되는 번들된 CLI 스킬입니다. Comfy Cloud MCPcomfy-cloud Claude Code 플러그인을 호스팅하는 Comfy Skills 저장소와는 별개입니다.

기여하기

기여를 환영합니다. comfy-cli GitHub 저장소에서 이슈를 열거나 풀 리퀘스트를 제출해 주세요. 자세한 세부 정보는 개발 전용 가이드를 참조하세요.

분석

사용 추적은 CLI 개선에 도움이 됩니다. 다음 명령으로 비활성화할 수 있습니다:
comfy tracking disable
추적을 다시 활성화하려면:
comfy tracking enable
DO_NOT_TRACK 또는 COMFY_NO_TELEMETRY 환경 변수를 통해 완전히 비활성화할 수도 있습니다.