# 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 | Comando | Propósito | |---|---| | [`env`](#env) | Imprime la información del entorno para informes de errores. | | [`schema`](#schema) | Inspecciona la firma de `__call__` de un pipeline sin descargar los pesos. | | [`run`](#run) | Ejecuta un pipeline localmente o en un Hugging Face Sandbox. | | [`custom_blocks`](#customblocks) | Empaqueta una subclase local de `ModularPipelineBlocks` para el Hub. | | [`fp16_safetensors`](#fp16safetensors) | Convierte un checkpoint a fp16 `.safetensors`. | | [`skills`](#skills) | Instala paquetes de habilidades preelaborados en tu agente de codificación con IA. | > [!TIP] > 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 --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. ```bash diffusers-cli env ``` ## esquema Devuelve las entradas aceptadas por el pipeline sin descargar los pesos. Úsalo al construir `--pipeline-kwargs` para [`run`](#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. ```bash 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: ```bash 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: - Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` a través de `load_image`. - Videos (`video`, `control_video`) → `list[PIL.Image]` mediante `load_video`. - Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` a través de `torchaudio.load`. ```bash 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 de 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: ```bash 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 ` — 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](../optimization/device_map) para más detalles. - `--variant fp16` — elige una variante de pesos. - `--revision ` — 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](../using-diffusers/custom_pipeline_overview) para los pipelines personalizados estándar y [Modular Diffusers](../modular_diffusers/overview). - `--lora ` — 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_` 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](../tutorials/using_peft_for_inference) 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 onload proviene de `--device-map` (se requiere una cadena de dispositivo simple para offload). - `model` — `enable_model_cpu_offload` for standard pipelines. See [Model offloading](../optimization/memory#model-offloading). - `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` para pipelines estándar. Consulte [Descarga de grupos](../optimization/memory#group-offloading). - `auto` — solo modular con [`ComponentsManager`](../modular_diffusers/components_manager). Los modos estándar generan una excepción en pipelines modulares. `auto` genera una excepción en pipelines estándar. - `--offload-margin ` — 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 desviador 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](../optimization/attention_backends). - `--vae-tiling` / `--vae-slicing` — reduce la VRAM de decodificación del VAE. Consulta [VAE tiling](../optimization/memory#vae-tiling) y [VAE slicing](../optimization/memory#vae-slicing). - `--compile [JSON]` — compila los módulos del denoiser con [torch.compile](../optimization/fp16#torchcompile). La CLI prefiere [compilación regional](../optimization/fp16#regional-compilation) 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 con `--remote` la CLI envuelve `torchrun --nproc-per-node=gpu` por ti. Consulta [Paralelismo de contexto](../optimization/context_parallelism). ### Pipelines modulares `run` detecta automáticamente un [repositorio modular](../modular_diffusers/overview), ya sea porque incluye un `modular_model_index.json` o porque su `model_index.json` nombra 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](../api/pipelines/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: ```bash 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 mantener todos los flujos de trabajo disponibles y permitir que el pipeline elija por cada llamada a partir de las entradas que se le proporcionan. ```bash 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`](../modular_diffusers/modular_pipeline) 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 → `.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--/`. Cada ejecución obtiene su propio subdirectorio para que las invocaciones consecutivas no se sobrescriban. Sobrescríbelo con `--output `. La forma en que se expande la ruta depende de su estructura y del tamaño del lote: | `--output` | 1 salida | N salidas | |---|---|---| | _omitido_ | directorio predeterminado → `0000.png` | directorio predeterminado → `0000.png`, `0001.png`, `0002.png`, … | | `./results/` (con `/` al final o un directorio existente) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … | | `my-cat.png` (ruta del archivo) | `my-cat.png` (usado textualmente) | `my-cat-0000.png`, `my-cat-0001.png`, … | 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](https://huggingface.co/docs/hub/en/storage-buckets). Acepta un: - ID del bucket de HF (`/`) - `hf://buckets//[/]` [URI de HF](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris) - URL del navegador Una subruta se utiliza como prefijo de carpeta. El bucket se crea si no existe y los objetos se almacenan bajo `[/]/`. ```bash # HF bucket id — files at hf://buckets/alice/edit-outputs// --push-to alice/edit-outputs # URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07// --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. | ¿Está configurado `--push-to`? | ¿Está configurado `--output`? | Resultado | |---|---|---| | no | no | descargar al directorio local predeterminado | | no | sí | descargar en `--output` | | sí | no | solo bucket, sin descarga local | | sí | sí | bucket Y `--output` | `--format` define los metadatos de stdout (rutas, tiempos, información del sandbox). No cambia el formato de archivo de los medios en sí. 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](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox): una VM en la nube aislada que la CLI controla mediante 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`](https://hub.docker.com/r/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. ```bash 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 ` — hardware del sandbox (por ejemplo, `a10g-small`, `h200`, `rtx-pro-6000`). - `--timeout ` — tiempo máximo real para el comando de ejecución dentro del sandbox (valor predeterminado `10m`). - `--dependencies ` — 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 ` — crea el sandbox bajo una organización/cuenta de HF diferente. - `--image ` — sobrescribe la imagen del sandbox. Debe incluir torch + CUDA compatible con el controlador de tu `--flavor`. La CLI instala entonces sus propias dependencias encima en cada sandbox en frío, algo que la imagen predeterminada evita. - `--volume [:]` — monta un [bucket de almacenamiento de HF](https://huggingface.co/docs/hub/en/storage-buckets) en el sandbox como un directorio de lectura y escritura (repetible). La ruta de montaje predeterminada es `/mnt/buckets/`. 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 ` — reconectar a un sandbox que se mantiene activo en lugar de crear uno nuevo. - `--idle-timeout ` — 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`. ```bash # First run keeps the sandbox alive and prints sandbox_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 # Stop it when done (or let it timeout). hf sandbox kill ``` ## `custom_blocks` Empaqueta una subclase local de `ModularPipelineBlocks` para su carga en el Hub. Lee un archivo Python, lo analiza mediante AST para encontrar 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. ```bash # 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` > [!CAUTION] > 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. ## `skills` Instala habilidades desde el repositorio de diffusers ([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills)). ```bash # Install a single skill diffusers-cli skills add "" # 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:`). Codex y Cursor reciben `.agents/skills//`.