Interfaz de línea de comandos

diffusers-cli es un cliente de línea de comandos para ejecutar, inspeccionar y empaquetar pipelines de Diffusers.

Comandos disponibles

Esta página no detalla todas las opciones de cada subcomando. Para obtener la lista completa y actualizada de opciones de cualquier subcomando, ejecute diffusers-cli <command> --help (diffusers-cli run --help).

env

Imprime las versiones de Python, PyTorch y Diffusers, la información de CUDA y las dependencias opcionales instaladas. Úsalo al abrir un problema para que los mantenedores puedan reproducir tu configuración.

diffusers-cli env

esquema

Devuelve las entradas aceptadas por el pipeline sin descargar los pesos. Úsalo al construir --pipeline-kwargs para run.

Solo se descarga el archivo de índice. Las tuberías estándar leen model_index.json. Las tuberías modulares leen modular_model_index.json. Los repositorios de bloques personalizados leen modular_config.json y necesitan --trust-remote-code, porque al cargarlos se ejecuta código del Hub.

diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev
diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code

run

Ejecuta un pipeline de principio a fin. La CLI detecta automáticamente si el repositorio es estándar o modular. Carga automáticamente las entradas multimedia desde URLs o rutas locales, guarda las salidas según el tipo de retorno del pipeline y puede ejecutarse de forma remota en un Hugging Face Sandbox mediante --remote.

Ejemplo mínimo:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev \
    --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}'

Pasar argumentos de pipeline

--pipeline-kwargs toma un objeto JSON que se reenvía a pipeline(**kwargs). Los valores de cadena en las claves conocidas de entrada multimedia se cargan automáticamente:

• Imágenes (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → PIL.Image mediante load_image.
• Vídeos (video, control_video) → list[PIL.Image] mediante load_video.
• Audio (initial_audio_waveforms, reference_audio, src_audio) → torch.Tensor mediante torchaudio.load.

diffusers-cli run \
    --model black-forest-labs/FLUX.2-klein-9B --dtype bf16 \
    --pipeline-kwargs '{"prompt": "make the fur grey", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png", "strength": 0.6}'

Tanto las claves de medios como las de texto aceptan un array JSON para ejecutar un lote en una sola llamada a la pipeline. Cada entrada de una lista de medios se carga de forma individual (URL, ruta local o ruta de montaje de bucket) y Diffusers procesa la lista completa en una sola pasada hacia adelante en la GPU:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-Kontext-dev --dtype bf16 \
    --pipeline-kwargs '{
        "prompt": ["make it grey", "make it pink", "make it blue"],
        "image": [
            "https://.../cat1.png",
            "https://.../cat2.png",
            "https://.../cat3.png"
        ]
    }'

Cargando

Configure cómo la CLI carga los pesos del modelo y el código de pipeline personalizado.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — dtype de los pesos.

• --device-map <value> — colocación de componentes. Acepta una cadena de dispositivo de torch (cuda, cuda:0, cpu, mps), balanced (divide automáticamente los componentes entre las GPU visibles) o un diccionario JSON para una colocación explícita por componente. Se detecta automáticamente si se omite. Consulte device_map para más detalles.

• --variant fp16 — elige una variante de pesos.

• --revision <sha> — fija una revisión específica del modelo.

• --trust-remote-code — permite el uso de código personalizado desde el Hub (necesario para repositorios que incluyen clases de pipeline personalizadas o bloques modulares). Consulta Pipelines de la comunidad para pipelines personalizados estándar y Modular Diffusers.

• --lora <spec> — adjunta un adaptador LoRA después de la carga. Cada valor es un diccionario JSON. Repite la bandera para apilar varios adaptadores. lora_id es obligatorio en cada entrada, lora_scale tiene un valor predeterminado de 1.0 y adapter_name es opcional (se genera automáticamente como lora_<i> al apilar).

  • Único: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • Varios: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'

  Todas las especificaciones se cargan mediante pipeline.load_lora_weights(...) y luego se activan juntas con una única llamada a pipeline.set_adapters(names, adapter_weights=scales). Consulte LoRA para una explicación más detallada sobre la apilación de adaptadores, la programación de escalas y el intercambio en caliente.

Optimizaciones

• --cpu-offload {model, group, auto} — el destino de la carga proviene de --device-map (cadena de dispositivo simple requerida para la descarga). model — enable_model_cpu_offload para pipelines estándar. Consulte Model offloading. group — enable_group_offload(offload_type="leaf_level", use_stream=True) para pipelines estándar. Consulte Group offloading. auto — solo modular con ComponentsManager. Los modos estándar generan un error en pipelines modulares. auto genera un error en pipelines estándar.
  • model — enable_model_cpu_offload for standard pipelines. See Model offloading.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) para pipelines estándar. Consulte Descarga de grupos.
  • auto — solo modular con ComponentsManager. Los modos estándar generan una excepción en pipelines modulares. auto genera una excepción en pipelines estándar.
• --offload-margin <size> — memoria del dispositivo que se mantiene libre para las activaciones bajo --cpu-offload auto, se pasa a enable_auto_cpu_offload como memory_reserve_margin (valor predeterminado 3GB). Auméntelo cuando un lienzo grande se quede sin memoria a mitad de la propagación hacia adelante. El offloader mantiene los componentes residentes mientras quepan, por lo que en una tarjeta con mucha VRAM el margen predeterminado puede dejar demasiado poco espacio para las activaciones de un video largo.
• --attention-backend — Núcleos de atención alojados en el Hub, descargados automáticamente en el primer uso. Las opciones son default más los backends del Hub registrados en Diffusers (por ejemplo, flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Ejecuta diffusers-cli run --help para ver la lista actual. Solo admite pipelines basados en Transformer y se ignora con una advertencia en pipelines UNet heredados. Consulta Backends de atención.
• --vae-tiling / --vae-slicing — reduce la VRAM de decodificación del VAE. Consulta VAE tiling y VAE slicing.
• --compile [JSON] — compila los módulos del denoiser con torch.compile. La CLI prefiere compilación regional para módulos con bloques repetidos. --compile sin argumentos usa fullgraph=true. Un objeto JSON se reenvía a torch.compile. No compatible con --context-parallel.
• --context-parallel — paralelismo de contexto estilo Ulysses en un pipeline basado en DiT. Localmente requiere torchrun, pero bajo --remote la CLI envuelve torchrun --nproc-per-node=gpu por ti. Consulta Paralelismo de contexto.

Pipelines modulares

run detecta automáticamente un repositorio modular, ya sea porque incluye un modular_model_index.json o porque su model_index.json nombra a una subclase de ModularPipeline, por lo que no es necesario ningún flag para activarlo.

Algunos repositorios modulares definen varios workflows como tareas con nombre que comparten componentes pero difieren en qué bloques se ejecutan y qué entradas reciben. MiniMax-H3, por ejemplo, ofrece t2va (texto a video y audio), fl2va (primer y/o último fotograma clave) y ref2va (una mezcla ordenada de referencias de imagen, video y audio). Pasa --workflow para seleccionar uno:

diffusers-cli run \
    --model MiniMaxAI/MiniMax-H3 --workflow fl2va \
    --pipeline-kwargs '{
        "prompt": "the camera pushes in slowly as rain falls",
        "image": "opening-frame.png",
        "last_image": "closing-frame.png",
        "num_frames": 124
    }' \
    --output-key videos --output-key audio \
    --fps 24 --sampling-rate 32000 \
    --cpu-offload auto --dtype bf16

Seleccionar un flujo de trabajo conserva solo los bloques de esa tarea, de modo que el pipeline declara únicamente los componentes que necesita y load_components recupera solo sus subcarpetas. Omita --workflow para conservar todos los flujos de trabajo disponibles y permitir que el pipeline elija por llamada a partir de las entradas que se le proporcionan.

diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code

--workflow se aplica solo a pipelines modulares. Se ignora con una advertencia en los pipelines estándar.

Un pipeline modular devuelve un PipelineState en lugar de un único objeto de salida, por lo que --output-key nombra el intermedio que se debe guardar.

Salidas

run detecta el tipo de salida de la pipeline:

• PIL.Image/list → <NNNN>.png (índice con ceros a la izquierda, p. ej. 0000.png)
• Secuencia de imágenes → 0000.mp4 (--fps controla la tasa de fotogramas, valor predeterminado 8)
• Matriz de audio → 0000.wav (--sampling-rate controla la tasa)
• Cualquier otra cosa → volcado JSON

El formato de directorio de salida predeterminado es ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Cada ejecución obtiene su propio subdirectorio para que las invocaciones consecutivas no se sobrescriban.

Sobrescríbelo con --output <path>. La forma en que se expande la ruta depende de su estructura y del tamaño del lote:

Las salidas de directorio siempre usan nombres rellenos sin prefijo (0000, 0001, …). Las rutas de archivo explícitas conservan el prefijo que elijas y se les añade el índice rellenado cuando el lote produce varias salidas.

Use --push-to para subir las salidas a un bucket de almacenamiento de Hugging Face. Acepta un:

• ID del bucket de HF (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] URI de HF
• URL del navegador

Una subruta se utiliza como prefijo de carpeta. El bucket se crea si no existe y los objetos se almacenan bajo [<subpath>/]<run_id>/<filename>.

# HF bucket id — files at hf://buckets/alice/edit-outputs/<run_id>/<file>
--push-to alice/edit-outputs

# URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07/<run_id>/<file>
--push-to hf://buckets/alice/edit-outputs/greyscale/2026-07

# Browser URL copy-paste from the Hub also works.
--push-to https://huggingface.co/buckets/alice/edit-outputs/tree/greyscale/2026-07

La tabla siguiente describe las ejecuciones remotas. Para las ejecuciones locales, --push-to sube la salida guardada localmente. No impide la creación de archivos locales.

--format define los metadatos de stdout (rutas, tiempos, información del sandbox). No cambia el formato de archivo de los propios medios. Las imágenes escritas siempre son PNG, los videos MP4 y el audio WAV.

Ejecución remota ( --remote )

Ejecuta la misma llamada dentro de un Hugging Face Sandbox: una VM en la nube aislada que la CLI controla a través de HTTP. Sube las entradas, ejecuta el pipeline, descarga las salidas y luego termina el sandbox. Requiere huggingface_hub>=1.23.

El sandbox se inicia desde diffusers/diffusers-cli-cuda, una imagen precompilada que ya incluye torch, CUDA y las dependencias de la CLI, por lo que una ejecución en frío comienza a generar en lugar de instalar primero.

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
    --remote --flavor a100-large

Banderas remotas:

• --flavor <name> — hardware del sandbox (por ejemplo, a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — tiempo máximo real para el comando de ejecución dentro del sandbox (valor predeterminado 10m).
• --dependencies <pkg> — dependencias adicionales de pip (repetible), instaladas sobre la imagen. Útil para fijar un tarball de una rama de diffusers o para añadir extras específicos de un pipeline.
• --namespace <name> — crea el sandbox bajo una organización/cuenta de HF diferente.
• --image <ref> — sobrescribe la imagen del sandbox. Debe incluir torch + CUDA compatible con el controlador de su --flavor. La CLI instala entonces sus propias dependencias encima en cada sandbox en frío, algo que la imagen predeterminada evita.
• --volume <bucket-id>[:<mount-path>] — monta un bucket de almacenamiento de HF en el sandbox como un directorio de lectura y escritura (repetible). La ruta de montaje predeterminada es /mnt/buckets/<bucket-id>. Referencia los archivos montados desde --pipeline-kwargs como cualquier otra ruta local. Se aplica solo en la creación de un nuevo sandbox y se ignora al reconectar mediante --sandbox-id.

Por defecto, cada ejecución de --remote es efímera (crear → ejecutar → descargar → eliminar). Para reutilizar un sandbox cálido entre ejecuciones —manteniendo las dependencias, la caché de pesos del modelo y la caché de torch.compile en su disco—, manténgalo activo y vuelva a conectarse:

• --keep-alive — no termina el sandbox después de la ejecución. Se imprime su id.
• --sandbox-id <id> — reconectar a un sandbox que se mantiene activo en lugar de crear uno nuevo.
• --idle-timeout <duration> — apagado automático tras este tiempo de inactividad (valor predeterminado 10m). Se aplica solo al crear un nuevo sandbox y se ignora al reconectar mediante --sandbox-id.

# First run keeps the sandbox alive and prints sandbox_id=<id>.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a cat"}' --remote --flavor a100-large --keep-alive

# Reconnect for the next run — the model is already cached, so only inference runs.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a dog"}' --remote --flavor a100-large --sandbox-id <id>

# Stop it when done (or let it timeout).
hf sandbox kill <id>

custom_blocks

Empaqueta una subclase local de ModularPipelineBlocks para su carga en el Hub. Lee un archivo Python, lo analiza mediante AST para detectar clases que derivan de ModularPipelineBlocks o de una de sus subclases compuestas (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks), instancia la elegida y llama a save_pretrained en el directorio de trabajo actual.

# Package the first block found in ./block.py
diffusers-cli custom_blocks

# Point at a different file / pick a specific class
diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock

La clase de bloque debe poder instanciarse con cero argumentos de constructor y debe definir valores predeterminados de forma fija en __init__ o leer la configuración del state de la pipeline en el momento de la llamada.

fp16_safetensors

Este comando está ahora en desuso y se eliminará en una versión futura.

Convierte un checkpoint en el Hub a .safetensors en fp16 y sube el resultado. Útil para reducir el tamaño de los pesos de un repositorio y acelerar su carga. Consulta diffusers-cli fp16_safetensors --help para ver los argumentos exactos.

habilidades

Instala habilidades desde el repositorio de diffusers (.ai/skills/).

# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills with a one-line summary of each
diffusers-cli skills list

# Preview a skill's SKILL.md without installing
diffusers-cli skills preview diffusers-cli

# Refetch and reinstall every managed skill
diffusers-cli skills update

# Install to the user-level directory instead of the current project
diffusers-cli skills add diffusers-cli --global

# Install for one agent instead of detecting it from the environment
diffusers-cli skills add --all --claude   # or --codex / --cursor

Sin una bandera de destino, la CLI instala para el agente que la lanzó, o para todos los agentes cuando no puede determinarlo. Claude Code recibe un paquete de complementos bajo .claude/skills/diffusers/ (con el espacio de nombres /diffusers:<skill name>). Codex y Cursor reciben .agents/skills/<skill name>/.