Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /pt /using-diffusers /cli.md

mishig

about 3 hours ago

preview code

download

raw

18.7 kB

# Interface de linha de comando

`diffusers-cli` é um cliente de linha de comando para executar, inspecionar e empacotar pipelines do Diffusers.

## Comandos disponíveis

| Comando | Propósito |
|---|---|
| [`env`](#env) | Imprime informações do ambiente para relatórios de bugs. |
| [`schema`](#schema) | Inspecione a assinatura de `__call__` de um pipeline sem baixar os pesos. |
| [`run`](#run) | Execute um pipeline localmente ou em um Hugging Face Sandbox. |
| [`custom_blocks`](#customblocks) | Empacote uma subclasse local de `ModularPipelineBlocks` para o Hub. |
| [`fp16_safetensors`](#fp16safetensors) | Converta um checkpoint para fp16 `.safetensors`. |
| [`skills`](#skills) | Instale bundles de habilidades pré-criados no seu agente de codificação com IA. |

> [!TIP]
> Esta página não fornece detalhes para todas as opções de cada subcomando. Para a lista completa e sempre atualizada de opções de qualquer subcomando, execute `diffusers-cli <command> --help` (`diffusers-cli run --help`).

## env

Imprime as versões do Python, PyTorch e Diffusers, as informações da CUDA e as dependências opcionais instaladas. Use-o ao abrir uma issue para que os mantenedores possam reproduzir seu ambiente.

```bash
diffusers-cli env
```

## schema

Retorna as entradas aceitas pelo pipeline sem baixar os pesos. Use-o ao construir `--pipeline-kwargs` para [`run`](#run).

Apenas o arquivo de índice é obtido. Os pipelines padrão leem `model_index.json`. Os pipelines modulares leem `modular_model_index.json`. Os repositórios de blocos personalizados leem `modular_config.json` e precisam de `--trust-remote-code`, pois carregá-los executa código do 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
```

## executar

Execute um pipeline de ponta a ponta. O CLI detecta automaticamente repositórios padrão ou modulares. Ele carrega automaticamente entradas de mídia de URLs ou caminhos locais, salva as saídas com base no tipo de retorno do pipeline e pode ser executado remotamente em um Hugging Face Sandbox via `--remote`.

Exemplo mínimo:

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

### Passando argumentos de pipeline

`--pipeline-kwargs` aceita um objeto JSON que é encaminhado para `pipeline(**kwargs)`. Valores de string nas chaves de entrada de mídia conhecidas são carregados automaticamente:

- Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` via `load_image`.
- Videos (`video`, `control_video`) → `list[PIL.Image]` via `load_video`.
- Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` via `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 as chaves de mídia quanto as chaves de texto aceitam um array JSON para executar um lote em uma única chamada de pipeline. Cada entrada em uma lista de mídia é carregada individualmente (URL, caminho local ou caminho de montagem de bucket) e o Diffusers processa a lista inteira em uma única passagem direta na 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"
        ]
    }'
```

### Carregando

Configure como a CLI carrega os pesos do modelo e o código personalizado do pipeline.

- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype dos pesos.
- `--device-map <value>` — posicionamento dos componentes. Aceita uma string de dispositivo do torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (divide automaticamente os componentes entre as GPUs visíveis) ou um dicionário JSON para posicionamento explícito por componente. Detectado automaticamente se omitido. Veja [device_map](../optimization/device_map) para mais detalhes.
- `--variant fp16` — escolha uma variante de pesos.
- `--revision <sha>` — fixa uma revisão específica do modelo.
- `--trust-remote-code` — permite código personalizado do Hub (necessário para repositórios que incluem classes de pipeline personalizadas ou blocos modulares). Consulte [Community pipelines](../using-diffusers/custom_pipeline_overview) para pipelines personalizados padrão e [Modular Diffusers](../modular_diffusers/overview).
- `--lora <spec>` — anexe um adaptador LoRA após o carregamento. Cada valor é um dicionário JSON. Repita a flag para empilhar múltiplos adaptadores. `lora_id` é obrigatório por entrada, `lora_scale` tem valor padrão de `1.0`, e `adapter_name` é opcional (gerado automaticamente como `lora_<i>` ao empilhar).
  - Simples: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
  - Múltiplos: `--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 as especificações são carregadas por `pipeline.load_lora_weights(...)` e, em seguida, ativadas juntas com uma única chamada de `pipeline.set_adapters(names, adapter_weights=scales)`. Consulte [LoRA](../tutorials/using_peft_for_inference) para um guia mais detalhado sobre empilhamento de adaptadores, agendamento de escala e troca dinâmica.

### Otimizações

- `--cpu-offload {model, group, auto}` — o alvo de onload vem de `--device-map` (é necessária uma string de dispositivo simples 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 padrão. Consulte [Group offloading](../optimization/memory#group-offloading).
  - `auto` — apenas modular com [`ComponentsManager`](../modular_diffusers/components_manager). Os modos padrão geram exceção em pipelines modulares. `auto` gera exceção em pipelines padrão.
- `--offload-margin <size>` — memória de dispositivo mantida livre para ativações sob `--cpu-offload auto`, passada para `enable_auto_cpu_offload` como `memory_reserve_margin` (padrão `3GB`). Aumente esse valor quando um canvas grande esgotar a memória no meio do forward. O offloader mantém os componentes residentes enquanto couberem, de modo que, em uma placa com muito VRAM, a margem padrão pode deixar pouco espaço para as ativações de um vídeo longo.
- `--attention-backend` — kernels de atenção hospedados no Hub, baixados automaticamente no primeiro uso. As opções são `default` mais os backends do Hub registrados no Diffusers (por exemplo, `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Execute `diffusers-cli run --help` para ver a lista atual. Ele suporta apenas pipelines baseados em Transformer e é ignorado com um aviso em pipelines UNet legados. Veja [Backends de atenção](../optimization/attention_backends).
- `--vae-tiling` / `--vae-slicing` — reduz a VRAM usada no decodificação do VAE. Veja [VAE tiling](../optimization/memory#vae-tiling) e [VAE slicing](../optimization/memory#vae-slicing).
- `--compile [JSON]` — compila os módulos do denoiser com [torch.compile](../optimization/fp16#torchcompile). A CLI prefere [compilação regional](../optimization/fp16#regional-compilation) para módulos com blocos repetidos. O `--compile` simples usa `fullgraph=true`. Um objeto JSON é encaminhado para `torch.compile`. Não é suportado com `--context-parallel`.
- `--context-parallel` — paralelismo de contexto no estilo Ulysses em um pipeline baseado em DiT. Localmente, requer torchrun, mas sob `--remote` a CLI encapsula `torchrun --nproc-per-node=gpu` para você. Veja [Paralelismo de contexto](../optimization/context_parallelism).

### Pipelines modulares

`run` detecta automaticamente um [repositório modular](../modular_diffusers/overview) — seja porque ele inclui um `modular_model_index.json`, seja porque seu `model_index.json` nomeia uma subclasse de `ModularPipeline` —, portanto, nenhum sinalizador é necessário para ativar essa funcionalidade.

Alguns repositórios modulares definem vários *workflows*, como tarefas nomeadas que compartilham componentes, mas diferem em quais blocos são executados e quais entradas recebem. [MiniMax-H3](../api/pipelines/minimax_h3), por exemplo, oferece `t2va` (texto para vídeo e áudio), `fl2va` (primeiro e/ou último keyframe) e `ref2va` (uma mistura ordenada de referências de imagem, vídeo e áudio). Passe `--workflow` para selecionar um:

```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
```

Selecionar um workflow mantém apenas os blocos daquela tarefa, de modo que o pipeline declara somente os componentes de que precisa e `load_components` busca apenas os subdiretórios correspondentes. Omita `--workflow` para manter todos os workflows disponíveis e permitir que o pipeline escolha a cada chamada com base nas entradas fornecidas.

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

`--workflow` se aplica apenas a pipelines modulares. É ignorado com um aviso em pipelines padrão.

Um pipeline modular retorna um [`PipelineState`](../modular_diffusers/modular_pipeline) em vez de um único objeto de saída, portanto `--output-key` nomeia o intermediário a ser salvo.

### Saídas

`run` detecta o tipo de saída do pipeline:

- `PIL.Image`/lista → `<NNNN>.png` (índice com zeros à esquerda, por exemplo, `0000.png`)
- Sequência de imagens → `0000.mp4` (`--fps` controla a taxa de quadros, padrão 8)
- Array de áudio → `0000.wav` (`--sampling-rate` controla a taxa)
- Qualquer outra coisa → despejo JSON

O formato padrão do diretório de saída é `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Cada execução recebe seu próprio subdiretório para que invocações consecutivas não sobrescrevam os resultados.

Substitua com `--output <path>`. A forma como o caminho é expandido depende do seu formato e do tamanho do lote:

| `--output` | 1 saída | N saídas |
|---|---|---|
| _omitido_ | diretório padrão → `0000.png` | diretório padrão → `0000.png`, `0001.png`, `0002.png`, … |
| `./results/` (com `/` no final ou um diretório existente) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … |
| `my-cat.png` (caminho do arquivo) | `my-cat.png` (usado literalmente) | `my-cat-0000.png`, `my-cat-0001.png`, … |

As saídas de diretório sempre usam nomes com preenchimento simples (`0000`, `0001`, …). Os caminhos de arquivo explícitos preservam o prefixo escolhido e recebem o índice com preenchimento anexado quando o lote produz múltiplas saídas.

Use `--push-to` para enviar as saídas para um [bucket de armazenamento do Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Ele aceita um:

- ID do bucket do HF (`<namespace>/<name>`)
- `hf://buckets/<namespace>/<name>[/<subpath>]`
[URI do HF](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris)
- URL do navegador

Um subpath é usado como um prefixo de pasta. O bucket é criado se não existir, e os objetos são armazenados em `[<subpath>/]<run_id>/<filename>`.

```bash
# 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
```

A tabela abaixo descreve execuções remotas. Para execuções locais, `--push-to` faz o upload da saída salva localmente. Ele não impede a criação de arquivos locais.

| `--push-to` definido? | `--output` definido? | Resultado |
|---|---|---|
| não | não | baixar para o diretório local padrão |
| não | sim | baixar para `--output` |
| sim | não | somente bucket, sem download local |
| sim | sim | bucket E `--output` |

`--format` define os metadados do stdout (caminhos, tempo de execução, informações do sandbox). Ele não altera o formato de arquivo da própria mídia. As imagens gravadas são sempre PNG, os vídeos MP4 e o áudio WAV.

### Execução remota (`--remote`)

Execute a mesma chamada dentro de um [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — uma VM de nuvem isolada que a CLI controla via HTTP: ela faz o upload das entradas, executa o pipeline, faz o download das saídas e, em seguida, encerra o sandbox. Requer `huggingface_hub>=1.23`.

O sandbox inicia a partir de [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), uma imagem pré-compilada que já inclui torch, CUDA e as dependências do CLI, de modo que uma execução a frio começa a gerar em vez de instalar primeiro.

```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
```

Flags remotas:

- `--flavor <name>` — hardware do sandbox (por exemplo, `a10g-small`, `h200`, `rtx-pro-6000`).
- `--timeout <duration>` — tempo máximo de execução do comando de execução dentro do sandbox (padrão `10m`).
- `--dependencies <pkg>` — dependências pip extras (repetível), instaladas por cima da imagem. Útil para fixar um tarball de uma branch do diffusers ou adicionar extras específicos de pipeline.
- `--namespace <name>` — cria o sandbox em uma organização/conta do HF diferente.
- `--image <ref>` — substitui a imagem do sandbox. Deve incluir torch + CUDA compatível com o driver do seu `--flavor`. O CLI então instala suas próprias dependências por cima em cada sandbox frio, o que a imagem padrão evita.
- `--volume <bucket-id>[:<mount-path>]` — monta um [bucket de armazenamento do HF](https://huggingface.co/docs/hub/en/storage-buckets) na sandbox como um diretório de leitura e gravação (repetível). O caminho de montagem padrão é `/mnt/buckets/<bucket-id>`. Refira-se aos arquivos montados em `--pipeline-kwargs` como qualquer outro caminho local. Aplicado apenas na criação de uma nova sandbox e ignorado ao reconectar via `--sandbox-id`.

Por padrão, cada execução de `--remote` é efêmera (criar → executar → baixar → encerrar). Para reutilizar um sandbox quente entre execuções — mantendo as dependências, o cache de pesos do modelo e o cache do `torch.compile` no disco — mantenha-o ativo e reconecte-se:

- `--keep-alive` — não encerra o sandbox após a execução. Seu id é exibido.
- `--sandbox-id <id>` — reconecta a um sandbox mantido ativo em vez de criar um novo.
- `--idle-timeout <duration>` — desligamento automático após esse período de inatividade (padrão `10m`). Aplicado apenas na criação de um novo sandbox e ignorado ao reconectar via `--sandbox-id`.

```bash
# 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`
Empacote uma subclasse local de `ModularPipelineBlocks` para upload no Hub. Lê um arquivo Python, faz um scan via AST em busca de classes que derivam de `ModularPipelineBlocks` ou de uma de suas subclasses compostas (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), instancia a escolhida e chama `save_pretrained` no diretório de trabalho atual.

```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
```

A classe de bloco deve ser instanciável com zero argumentos de construtor e define padrões fixos em `__init__` ou lê a configuração do estado do pipeline `state` no momento da chamada.

## `fp16_safetensors`
> [!CAUTION]
> Este comando agora está obsoleto e será removido em uma versão futura.
Converta um checkpoint no Hub para `.safetensors` em fp16 e envie o resultado. Útil para reduzir o tamanho dos pesos de um repositório para um carregamento mais rápido. Consulte `diffusers-cli fp16_safetensors --help` para os argumentos exatos.

## `skills`

Instale habilidades do repositório diffusers ([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills)).

```bash
# 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
```

Sem a flag de destino, o CLI instala para o agente que o lançou, ou para todos os agentes quando não consegue identificá-lo. O Claude Code recebe um pacote de plugins em `.claude/skills/diffusers/` (com namespace `/diffusers:<skill name>`). O Codex e o Cursor recebem `.agents/skills/<skill name>/`.

Xet Storage Details

Size:: 18.7 kB
Xet hash:: 7165208927414e970df85afd48fd05adff8b8e2b7ed14e1cdca3b422f4efd6bb

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Interface de linha de comando

	`diffusers-cli` é um cliente de linha de comando para executar, inspecionar e empacotar pipelines do Diffusers.

	## Comandos disponíveis

	\| Comando \| Propósito \|
	\|---\|---\|
	\| [`env`](#env) \| Imprime informações do ambiente para relatórios de bugs. \|
	\| [`schema`](#schema) \| Inspecione a assinatura de `__call__` de um pipeline sem baixar os pesos. \|
	\| [`run`](#run) \| Execute um pipeline localmente ou em um Hugging Face Sandbox. \|
	\| [`custom_blocks`](#customblocks) \| Empacote uma subclasse local de `ModularPipelineBlocks` para o Hub. \|
	\| [`fp16_safetensors`](#fp16safetensors) \| Converta um checkpoint para fp16 `.safetensors`. \|
	\| [`skills`](#skills) \| Instale bundles de habilidades pré-criados no seu agente de codificação com IA. \|

	> [!TIP]
	> Esta página não fornece detalhes para todas as opções de cada subcomando. Para a lista completa e sempre atualizada de opções de qualquer subcomando, execute `diffusers-cli <command> --help` (`diffusers-cli run --help`).

	## env

	Imprime as versões do Python, PyTorch e Diffusers, as informações da CUDA e as dependências opcionais instaladas. Use-o ao abrir uma issue para que os mantenedores possam reproduzir seu ambiente.

	```bash
	diffusers-cli env
	```

	## schema

	Retorna as entradas aceitas pelo pipeline sem baixar os pesos. Use-o ao construir `--pipeline-kwargs` para [`run`](#run).

	Apenas o arquivo de índice é obtido. Os pipelines padrão leem `model_index.json`. Os pipelines modulares leem `modular_model_index.json`. Os repositórios de blocos personalizados leem `modular_config.json` e precisam de `--trust-remote-code`, pois carregá-los executa código do 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
	```

	## executar

	Execute um pipeline de ponta a ponta. O CLI detecta automaticamente repositórios padrão ou modulares. Ele carrega automaticamente entradas de mídia de URLs ou caminhos locais, salva as saídas com base no tipo de retorno do pipeline e pode ser executado remotamente em um Hugging Face Sandbox via `--remote`.

	Exemplo mínimo:

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

	### Passando argumentos de pipeline

	`--pipeline-kwargs` aceita um objeto JSON que é encaminhado para `pipeline(**kwargs)`. Valores de string nas chaves de entrada de mídia conhecidas são carregados automaticamente:

	- Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` via `load_image`.
	- Videos (`video`, `control_video`) → `list[PIL.Image]` via `load_video`.
	- Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` via `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 as chaves de mídia quanto as chaves de texto aceitam um array JSON para executar um lote em uma única chamada de pipeline. Cada entrada em uma lista de mídia é carregada individualmente (URL, caminho local ou caminho de montagem de bucket) e o Diffusers processa a lista inteira em uma única passagem direta na 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"
	]
	}'
	```

	### Carregando

	Configure como a CLI carrega os pesos do modelo e o código personalizado do pipeline.

	- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype dos pesos.
	- `--device-map <value>` — posicionamento dos componentes. Aceita uma string de dispositivo do torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (divide automaticamente os componentes entre as GPUs visíveis) ou um dicionário JSON para posicionamento explícito por componente. Detectado automaticamente se omitido. Veja [device_map](../optimization/device_map) para mais detalhes.
	- `--variant fp16` — escolha uma variante de pesos.
	- `--revision <sha>` — fixa uma revisão específica do modelo.
	- `--trust-remote-code` — permite código personalizado do Hub (necessário para repositórios que incluem classes de pipeline personalizadas ou blocos modulares). Consulte [Community pipelines](../using-diffusers/custom_pipeline_overview) para pipelines personalizados padrão e [Modular Diffusers](../modular_diffusers/overview).
	- `--lora <spec>` — anexe um adaptador LoRA após o carregamento. Cada valor é um dicionário JSON. Repita a flag para empilhar múltiplos adaptadores. `lora_id` é obrigatório por entrada, `lora_scale` tem valor padrão de `1.0`, e `adapter_name` é opcional (gerado automaticamente como `lora_<i>` ao empilhar).
	- Simples: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
	- Múltiplos: `--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 as especificações são carregadas por `pipeline.load_lora_weights(...)` e, em seguida, ativadas juntas com uma única chamada de `pipeline.set_adapters(names, adapter_weights=scales)`. Consulte [LoRA](../tutorials/using_peft_for_inference) para um guia mais detalhado sobre empilhamento de adaptadores, agendamento de escala e troca dinâmica.

	### Otimizações

	- `--cpu-offload {model, group, auto}` — o alvo de onload vem de `--device-map` (é necessária uma string de dispositivo simples 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 padrão. Consulte [Group offloading](../optimization/memory#group-offloading).
	- `auto` — apenas modular com [`ComponentsManager`](../modular_diffusers/components_manager). Os modos padrão geram exceção em pipelines modulares. `auto` gera exceção em pipelines padrão.
	- `--offload-margin <size>` — memória de dispositivo mantida livre para ativações sob `--cpu-offload auto`, passada para `enable_auto_cpu_offload` como `memory_reserve_margin` (padrão `3GB`). Aumente esse valor quando um canvas grande esgotar a memória no meio do forward. O offloader mantém os componentes residentes enquanto couberem, de modo que, em uma placa com muito VRAM, a margem padrão pode deixar pouco espaço para as ativações de um vídeo longo.
	- `--attention-backend` — kernels de atenção hospedados no Hub, baixados automaticamente no primeiro uso. As opções são `default` mais os backends do Hub registrados no Diffusers (por exemplo, `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Execute `diffusers-cli run --help` para ver a lista atual. Ele suporta apenas pipelines baseados em Transformer e é ignorado com um aviso em pipelines UNet legados. Veja [Backends de atenção](../optimization/attention_backends).
	- `--vae-tiling` / `--vae-slicing` — reduz a VRAM usada no decodificação do VAE. Veja [VAE tiling](../optimization/memory#vae-tiling) e [VAE slicing](../optimization/memory#vae-slicing).
	- `--compile [JSON]` — compila os módulos do denoiser com [torch.compile](../optimization/fp16#torchcompile). A CLI prefere [compilação regional](../optimization/fp16#regional-compilation) para módulos com blocos repetidos. O `--compile` simples usa `fullgraph=true`. Um objeto JSON é encaminhado para `torch.compile`. Não é suportado com `--context-parallel`.
	- `--context-parallel` — paralelismo de contexto no estilo Ulysses em um pipeline baseado em DiT. Localmente, requer torchrun, mas sob `--remote` a CLI encapsula `torchrun --nproc-per-node=gpu` para você. Veja [Paralelismo de contexto](../optimization/context_parallelism).

	### Pipelines modulares

	`run` detecta automaticamente um [repositório modular](../modular_diffusers/overview) — seja porque ele inclui um `modular_model_index.json`, seja porque seu `model_index.json` nomeia uma subclasse de `ModularPipeline` —, portanto, nenhum sinalizador é necessário para ativar essa funcionalidade.

	Alguns repositórios modulares definem vários workflows, como tarefas nomeadas que compartilham componentes, mas diferem em quais blocos são executados e quais entradas recebem. [MiniMax-H3](../api/pipelines/minimax_h3), por exemplo, oferece `t2va` (texto para vídeo e áudio), `fl2va` (primeiro e/ou último keyframe) e `ref2va` (uma mistura ordenada de referências de imagem, vídeo e áudio). Passe `--workflow` para selecionar um:

	```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
	```

	Selecionar um workflow mantém apenas os blocos daquela tarefa, de modo que o pipeline declara somente os componentes de que precisa e `load_components` busca apenas os subdiretórios correspondentes. Omita `--workflow` para manter todos os workflows disponíveis e permitir que o pipeline escolha a cada chamada com base nas entradas fornecidas.

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

	`--workflow` se aplica apenas a pipelines modulares. É ignorado com um aviso em pipelines padrão.

	Um pipeline modular retorna um [`PipelineState`](../modular_diffusers/modular_pipeline) em vez de um único objeto de saída, portanto `--output-key` nomeia o intermediário a ser salvo.

	### Saídas

	`run` detecta o tipo de saída do pipeline:

	- `PIL.Image`/lista → `<NNNN>.png` (índice com zeros à esquerda, por exemplo, `0000.png`)
	- Sequência de imagens → `0000.mp4` (`--fps` controla a taxa de quadros, padrão 8)
	- Array de áudio → `0000.wav` (`--sampling-rate` controla a taxa)
	- Qualquer outra coisa → despejo JSON

	O formato padrão do diretório de saída é `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Cada execução recebe seu próprio subdiretório para que invocações consecutivas não sobrescrevam os resultados.

	Substitua com `--output <path>`. A forma como o caminho é expandido depende do seu formato e do tamanho do lote:

	\| `--output` \| 1 saída \| N saídas \|
	\|---\|---\|---\|
	\| _omitido_ \| diretório padrão → `0000.png` \| diretório padrão → `0000.png`, `0001.png`, `0002.png`, … \|
	\| `./results/` (com `/` no final ou um diretório existente) \| `./results/0000.png` \| `./results/0000.png`, `./results/0001.png`, … \|
	\| `my-cat.png` (caminho do arquivo) \| `my-cat.png` (usado literalmente) \| `my-cat-0000.png`, `my-cat-0001.png`, … \|

	As saídas de diretório sempre usam nomes com preenchimento simples (`0000`, `0001`, …). Os caminhos de arquivo explícitos preservam o prefixo escolhido e recebem o índice com preenchimento anexado quando o lote produz múltiplas saídas.

	Use `--push-to` para enviar as saídas para um [bucket de armazenamento do Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Ele aceita um:

	- ID do bucket do HF (`<namespace>/<name>`)
	- `hf://buckets/<namespace>/<name>[/<subpath>]`
	[URI do HF](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris)
	- URL do navegador

	Um subpath é usado como um prefixo de pasta. O bucket é criado se não existir, e os objetos são armazenados em `[<subpath>/]<run_id>/<filename>`.

	```bash
	# 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
	```

	A tabela abaixo descreve execuções remotas. Para execuções locais, `--push-to` faz o upload da saída salva localmente. Ele não impede a criação de arquivos locais.

	\| `--push-to` definido? \| `--output` definido? \| Resultado \|
	\|---\|---\|---\|
	\| não \| não \| baixar para o diretório local padrão \|
	\| não \| sim \| baixar para `--output` \|
	\| sim \| não \| somente bucket, sem download local \|
	\| sim \| sim \| bucket E `--output` \|

	`--format` define os metadados do stdout (caminhos, tempo de execução, informações do sandbox). Ele não altera o formato de arquivo da própria mídia. As imagens gravadas são sempre PNG, os vídeos MP4 e o áudio WAV.

	### Execução remota (`--remote`)

	Execute a mesma chamada dentro de um [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — uma VM de nuvem isolada que a CLI controla via HTTP: ela faz o upload das entradas, executa o pipeline, faz o download das saídas e, em seguida, encerra o sandbox. Requer `huggingface_hub>=1.23`.

	O sandbox inicia a partir de [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), uma imagem pré-compilada que já inclui torch, CUDA e as dependências do CLI, de modo que uma execução a frio começa a gerar em vez de instalar primeiro.

	```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
	```

	Flags remotas:

	- `--flavor <name>` — hardware do sandbox (por exemplo, `a10g-small`, `h200`, `rtx-pro-6000`).
	- `--timeout <duration>` — tempo máximo de execução do comando de execução dentro do sandbox (padrão `10m`).
	- `--dependencies <pkg>` — dependências pip extras (repetível), instaladas por cima da imagem. Útil para fixar um tarball de uma branch do diffusers ou adicionar extras específicos de pipeline.
	- `--namespace <name>` — cria o sandbox em uma organização/conta do HF diferente.
	- `--image <ref>` — substitui a imagem do sandbox. Deve incluir torch + CUDA compatível com o driver do seu `--flavor`. O CLI então instala suas próprias dependências por cima em cada sandbox frio, o que a imagem padrão evita.
	- `--volume <bucket-id>[:<mount-path>]` — monta um [bucket de armazenamento do HF](https://huggingface.co/docs/hub/en/storage-buckets) na sandbox como um diretório de leitura e gravação (repetível). O caminho de montagem padrão é `/mnt/buckets/<bucket-id>`. Refira-se aos arquivos montados em `--pipeline-kwargs` como qualquer outro caminho local. Aplicado apenas na criação de uma nova sandbox e ignorado ao reconectar via `--sandbox-id`.

	Por padrão, cada execução de `--remote` é efêmera (criar → executar → baixar → encerrar). Para reutilizar um sandbox quente entre execuções — mantendo as dependências, o cache de pesos do modelo e o cache do `torch.compile` no disco — mantenha-o ativo e reconecte-se:

	- `--keep-alive` — não encerra o sandbox após a execução. Seu id é exibido.
	- `--sandbox-id <id>` — reconecta a um sandbox mantido ativo em vez de criar um novo.
	- `--idle-timeout <duration>` — desligamento automático após esse período de inatividade (padrão `10m`). Aplicado apenas na criação de um novo sandbox e ignorado ao reconectar via `--sandbox-id`.

	```bash
	# 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`

	Empacote uma subclasse local de `ModularPipelineBlocks` para upload no Hub. Lê um arquivo Python, faz um scan via AST em busca de classes que derivam de `ModularPipelineBlocks` ou de uma de suas subclasses compostas (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), instancia a escolhida e chama `save_pretrained` no diretório de trabalho atual.

	```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
	```

	A classe de bloco deve ser instanciável com zero argumentos de construtor e define padrões fixos em `__init__` ou lê a configuração do estado do pipeline `state` no momento da chamada.

	## `fp16_safetensors`

	> [!CAUTION]
	> Este comando agora está obsoleto e será removido em uma versão futura.

	Converta um checkpoint no Hub para `.safetensors` em fp16 e envie o resultado. Útil para reduzir o tamanho dos pesos de um repositório para um carregamento mais rápido. Consulte `diffusers-cli fp16_safetensors --help` para os argumentos exatos.

	## `skills`

	Instale habilidades do repositório diffusers ([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills)).

	```bash
	# 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
	```

	Sem a flag de destino, o CLI instala para o agente que o lançou, ou para todos os agentes quando não consegue identificá-lo. O Claude Code recebe um pacote de plugins em `.claude/skills/diffusers/` (com namespace `/diffusers:<skill name>`). O Codex e o Cursor recebem `.agents/skills/<skill name>/`.