Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

2 days ago

preview code

download

raw

19.8 kB

# Interface en ligne de commande

`diffusers-cli` est un client en ligne de commande pour exécuter, inspecter et empaqueter les pipelines Diffusers.

## Commandes disponibles

| Commande | Objectif |
|---|---|
| [`env`](#env) | Afficher les informations de l'environnement pour les rapports de bugs. |
| [`schema`](#schema) | Inspecter la signature `__call__` d'un pipeline sans télécharger les poids. |
| [`run`](#run) | Exécuter un pipeline localement ou dans un Hugging Face Sandbox. |
| [`custom_blocks`](#customblocks) | Emballer une sous-classe locale de `ModularPipelineBlocks` pour le Hub. |
| [`fp16_safetensors`](#fp16safetensors) | Convertir un point de contrôle en fp16 `.safetensors`. |
| [`skills`](#skills) | Installez des bundles de compétences pré-écrits dans votre agent de codage IA. |

> [!TIP]
> Cette page ne détaille pas toutes les options de chaque sous-commande. Pour obtenir la liste complète et à jour des options de toute sous-commande, exécutez `diffusers-cli <command> --help` (`diffusers-cli run --help`).

## env

Affiche les versions de Python, PyTorch et Diffusers, les informations CUDA et les dépendances optionnelles installées. Utilisez-le lors de l’ouverture d’un ticket afin que les mainteneurs puissent reproduire votre configuration.

```bash
diffusers-cli env
```

## schema

Retourne les entrées acceptées par le pipeline sans télécharger les poids. Utilisez-le lors de la construction de `--pipeline-kwargs` pour [`run`](#run).

Seul le fichier d’index est récupéré. Les pipelines standard lisent `model_index.json`. Les pipelines modulaires lisent `modular_model_index.json`. Les dépôts à blocs personnalisés lisent `modular_config.json` et nécessitent `--trust-remote-code`, car leur chargement exécute du code du 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

Exécutez un pipeline de bout en bout. L’interface en ligne de commande détecte automatiquement les dépôts standard et modulaires. Elle charge automatiquement les entrées multimédias à partir d’URL ou de chemins locaux, enregistre les sorties selon le type de retour du pipeline et peut s’exécuter à distance sur un Hugging Face Sandbox via `--remote`.

Exemple minimal :

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

### Passage des arguments du pipeline

`--pipeline-kwargs` prend un objet JSON qui est transmis à `pipeline(**kwargs)`. Les valeurs de chaîne aux clés d’entrée multimédia connues sont chargées automatiquement :

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

Les clés média et texte acceptent toutes deux un tableau JSON pour exécuter un lot via un seul appel de pipeline. Chaque entrée d’une liste média est chargée individuellement (URL, chemin local ou chemin de montage de bucket), et Diffusers traite la liste entière en un seul passage avant sur le 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"
        ]
    }'
```

### Chargement

Configurez la façon dont l’interface en ligne de charge (CLI) charge les poids du modèle et le code de pipeline personnalisé.

- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype des poids.
- `--device-map <value>` — placement des composants. Accepte une chaîne de device torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (répartit automatiquement les composants entre les GPU visibles) ou un dictionnaire JSON pour un placement explicite par composant. Détecté automatiquement si omis. Voir [device_map](../optimization/device_map) pour plus de détails.
- `--variant fp16` — choisir une variante de poids.
- `--revision <sha>` — épingler une révision spécifique du modèle.
- `--trust-remote-code` — autorise le code personnalisé issu du Hub (nécessaire pour les dépôts qui incluent des classes de pipeline personnalisées ou des blocs modulaires). Consultez [Community pipelines](../using-diffusers/custom_pipeline_overview) pour les pipelines personnalisés standard et [Modular Diffusers](../modular_diffusers/overview).
- `--lora <spec>` — attacher un adaptateur LoRA après le chargement. Chaque valeur est un dictionnaire JSON. Répétez le drapeau pour empiler plusieurs adaptateurs. `lora_id` est obligatoire pour chaque entrée, `lora_scale` est défini par défaut sur `1.0`, et `adapter_name` est facultatif (généré automatiquement sous la forme `lora_<i>` lors de l’empilement).
  - Simple : `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
  - Plusieurs : `--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}'`

  Toutes les spécifications sont chargées par `pipeline.load_lora_weights(...)`, puis activées ensemble avec un seul appel à `pipeline.set_adapters(names, adapter_weights=scales)`. Consultez [LoRA](../tutorials/using_peft_for_inference) pour un guide détaillé sur le superposition d'adaptateurs, la planification des échelles et le changement à chaud.

### Optimisations

- `--cpu-offload {model, group, auto}` — la cible d'onload provient de `--device-map` (une chaîne de device simple est requise pour l'offload).
  - `model` — `enable_model_cpu_offload` pour les pipelines standard. Voir [Déchargement du modèle](../optimization/memory#model-offloading).
  - `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` pour les pipelines standard. Voir [Group offloading](../optimization/memory#group-offloading).
  - `auto` — uniquement en mode modulaire avec [`ComponentsManager`](../modular_diffusers/components_manager). Les modes standard lèvent une exception sur les pipelines modulaires. `auto` lève une exception sur les pipelines standard.
- `--offload-margin <size>` — mémoire de l’appareil laissée libre pour les activations sous `--cpu-offload auto`, transmise à `enable_auto_cpu_offload` en tant que `memory_reserve_margin` (valeur par défaut `3GB`). Augmentez cette valeur si une grande toile épuise la mémoire en cours de propagation avant. Le déchargeur conserve les composants en mémoire tant qu’ils y tiennent, de sorte qu’avec une carte à forte VRAM, la marge par défaut peut laisser trop peu de place pour les activations d’une longue vidéo.
- `--attention-backend` — Noyaux d’attention hébergés sur le Hub, téléchargés automatiquement lors de la première utilisation. Les choix sont `default` ainsi que les backends du Hub enregistrés dans Diffusers (par exemple `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Exécutez `diffusers-cli run --help` pour obtenir la liste actuelle. Il ne prend en charge que les pipelines basés sur des Transformers et est ignoré avec un avertissement sur les pipelines UNet legacy. Voir [Backends d’attention](../optimization/attention_backends).
- `--vae-tiling` / `--vae-slicing` — réduit la VRAM utilisée par le décodage VAE. Consultez [tiling VAE](../optimization/memory#vae-tiling) et [slicing VAE](../optimization/memory#vae-slicing).
- `--compile [JSON]` — compile les modules du débruiteur avec [torch.compile](../optimization/fp16#torchcompile). L’interface en ligne de commande privilégie la [compilation régionale](../optimization/fp16#regional-compilation) pour les modules comportant des blocs répétés. L’option `--compile` seule utilise `fullgraph=true`. Un objet JSON est transmis à `torch.compile`. Non pris en charge avec `--context-parallel`.
- `--context-parallel` — parallélisme de contexte de type Ulysses sur un pipeline basé sur DiT. Nécessite localement torchrun, mais sous `--remote`, l’interface en ligne de commande encapsule `torchrun --nproc-per-node=gpu` pour vous. Voir [Parallélisme de contexte](../optimization/context_parallelism).

### Pipelines modulaires

`run` détecte automatiquement un [dépôt modulaire](../modular_diffusers/overview) — soit parce qu’il contient un `modular_model_index.json`, soit parce que son `model_index.json` référence une sous-classe de `ModularPipeline` — et aucun drapeau n’est nécessaire pour l’activer.

Certains dépôts modulaires définissent plusieurs *workflows* semblables à des tâches nommées qui partagent des composants mais diffèrent par les blocs exécutés et les entrées qu’ils acceptent. [MiniMax-H3](../api/pipelines/minimax_h3), par exemple, propose `t2va` (texte vers vidéo et audio), `fl2va` (image clé première et/ou dernière) et `ref2va` (un mélange ordonné de références image, vidéo et audio). Passez `--workflow` pour en sélectionner un :

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

Sélectionner un workflow ne conserve que les blocs de cette tâche, de sorte que le pipeline ne déclare que les composants dont il a besoin et `load_components` ne récupère que leurs sous-dossiers. Omettez `--workflow` pour conserver tous les workflows disponibles et laisser le pipeline choisir à chaque appel en fonction des entrées qui lui sont fournies.

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

`--workflow` s'applique uniquement aux pipelines modulaires. Il est ignoré avec un avertissement sur les pipelines standard.

Un pipeline modulaire renvoie un [`PipelineState`](../modular_diffusers/modular_pipeline) plutôt qu'un seul objet de sortie, de sorte que `--output-key` désigne l'intermédiaire à enregistrer.

### Sorties

`run` détecte le type de sortie du pipeline :

- `PIL.Image`/liste → `<NNNN>.png` (index à zéros, par ex. `0000.png`)
- Séquence d'images → `0000.mp4` (`--fps` contrôle la fréquence d'images, valeur par défaut 8)
- Tableau audio → `0000.wav` (`--sampling-rate` contrôle le taux)
- Tout le reste → déchargement JSON

Le format du répertoire de sortie par défaut est `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Chaque exécution reçoit son propre sous-répertoire afin que les invocations successives ne s'écrasent pas.

Utilisez `--output <path>` pour l'écraser. La manière dont le chemin est développé dépend de sa forme et de la taille du lot :

| `--output` | 1 sortie | Sorties N |
|---|---|---|
| _omitted_ | répertoire par défaut → `0000.png` | répertoire par défaut → `0000.png`, `0001.png`, `0002.png`, … |
| `./results/` (avec un `/` final ou un répertoire existant) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … |
| `my-cat.png` (chemin du fichier) | `my-cat.png` (utilisé tel quel) | `my-cat-0000.png`, `my-cat-0001.png`, … |

Les sorties de répertoire utilisent toujours des noms nus avec zéros d’alignement (`0000`, `0001`, …). Les chemins de fichiers explicites conservent la racine choisie et reçoivent l’index aligné en suffixe lorsque le lot produit plusieurs sorties.

Utilisez `--push-to` pour téléverser les résultats dans un [seau de stockage Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Il accepte un :

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

Un sous-chemin est utilisé comme préfixe de dossier. Le bucket est créé s'il est manquant, et les objets sont placés sous `[<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
```

Le tableau ci-dessous décrit les exécutions distantes. Pour les exécutions locales, `--push-to` téléverse la sortie enregistrée localement. Il ne supprime pas la création de fichiers locaux.

| `--push-to` défini ? | `--output` défini ? | Résultat |
|---|---|---|
| non | non | télécharger dans le répertoire local par défaut |
| non | oui | télécharger vers `--output` |
| oui | non | bucket uniquement, sans téléchargement local |
| oui | oui | bucket ET `--output` |

`--format` forme les métadonnées de la sortie standard (chemins, chronométrage, informations sur le bac à sable). Il ne modifie pas le format de fichier des médias eux-mêmes. Les images écrites sont toujours au format PNG, les vidéos en MP4 et l’audio en WAV.

### Exécution à distance (`--remote`)

Effectuez le même appel dans un [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — une VM cloud isolée que le CLI pilote via HTTP : il téléverse les entrées, exécute le pipeline, télécharge les sorties, puis met fin au sandbox. Nécessite `huggingface_hub>=1.23`.

Le bac à sable démarre à partir de [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), une image préconstruite qui inclut déjà torch, CUDA et les dépendances du CLI, de sorte qu'une exécution à froid commence à générer au lieu d'installer d'abord.

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

Drapeaux distants :

- `--flavor <name>` — matériel de la sandbox (par exemple, `a10g-small`, `h200`, `rtx-pro-6000`).
- `--timeout <duration>` — durée maximale réelle pour la commande d’exécution dans le bac à sable (par défaut `10m`).
- `--dependencies <pkg>` — dépendances pip supplémentaires (répétable), installées par-dessus l’image. Utile pour épingler un tarball de branche de diffusers ou ajouter des extras spécifiques à un pipeline.
- `--namespace <name>` — crée le bac à sable sous une autre organisation/compte HF.
- `--image <ref>` — remplace l’image du bac à sable. Elle doit inclure torch + CUDA compatible avec le pilote de votre `--flavor`. Le CLI installe alors ses propres dépendances par-dessus à chaque bac à sable froid, ce que l’image par défaut évite.
- `--volume <bucket-id>[:<mount-path>]` — monte un [bucket de stockage HF](https://huggingface.co/docs/hub/en/storage-buckets) dans le bac à sable en tant que répertoire en lecture-écriture (répétable). Le chemin de montage par défaut est `/mnt/buckets/<bucket-id>`. Référencez les fichiers montés depuis `--pipeline-kwargs` comme n’importe quel autre chemin local. Appliqué uniquement lors de la création d’un nouveau bac à sable et ignoré lors de la reconnexion via `--sandbox-id`.

Par défaut, chaque exécution `--remote` est éphémère (création → exécution → téléchargement → arrêt). Pour réutiliser un bac à sable chaud entre les exécutions — en conservant les dépendances, le cache des poids du modèle et le cache `torch.compile` sur son disque —, maintenez-le en vie et reconnectez-vous :

- `--keep-alive` — ne pas mettre fin au bac à sable après l’exécution. Son identifiant est affiché.
- `--sandbox-id <id>` — se reconnecter à un sandbox maintenu actif au lieu d’en créer un nouveau.
- `--idle-timeout <duration>` — arrêt automatique après cette durée d’inactivité (par défaut `10m`). Appliqué uniquement lors de la création d’une nouvelle sandbox et ignoré lors d’une reconnexion 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`
Emballer un sous-classe local de `ModularPipelineBlocks` pour le téléverser sur le Hub. Lit un fichier Python, l'analyse via AST pour détecter les classes dérivant de `ModularPipelineBlocks` ou de l'un de ses sous-classes composites (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), instancie celle choisie et appelle `save_pretrained` dans le répertoire de travail actuel.

```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 classe de bloc doit être instantiable avec zéro argument de constructeur et durcit les valeurs par défaut dans `__init__` ou lit la configuration depuis l'`state` du pipeline au moment de l'appel.

## `fp16_safetensors`
> [!CAUTION]
> Cette commande est désormais obsolète et sera supprimée dans une version future.
Convertir un point de contrôle sur le Hub en `.safetensors` fp16 et pousser le résultat. Utile pour réduire la taille des poids d'un dépôt afin d'accélérer le chargement. Consultez `diffusers-cli fp16_safetensors --help` pour les arguments exacts.

## `skills`

Installer les compétences depuis le dépôt 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
```

Sans drapeau cible, le CLI installe pour l’agent qui l’a lancé, ou pour tous les agents s’il ne peut pas le déterminer. Claude Code reçoit un bundle de plugins sous `.claude/skills/diffusers/` (namespacé en tant que `/diffusers:<skill name>`). Codex et Cursor reçoivent `.agents/skills/<skill name>/`.

Xet Storage Details

Size:: 19.8 kB
Xet hash:: 6003e250c850507ba1bb19caa01ab05d50aa529e5b54955601ae151077e6dccd

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

	# Interface en ligne de commande

	`diffusers-cli` est un client en ligne de commande pour exécuter, inspecter et empaqueter les pipelines Diffusers.

	## Commandes disponibles

	\| Commande \| Objectif \|
	\|---\|---\|
	\| [`env`](#env) \| Afficher les informations de l'environnement pour les rapports de bugs. \|
	\| [`schema`](#schema) \| Inspecter la signature `__call__` d'un pipeline sans télécharger les poids. \|
	\| [`run`](#run) \| Exécuter un pipeline localement ou dans un Hugging Face Sandbox. \|
	\| [`custom_blocks`](#customblocks) \| Emballer une sous-classe locale de `ModularPipelineBlocks` pour le Hub. \|
	\| [`fp16_safetensors`](#fp16safetensors) \| Convertir un point de contrôle en fp16 `.safetensors`. \|
	\| [`skills`](#skills) \| Installez des bundles de compétences pré-écrits dans votre agent de codage IA. \|

	> [!TIP]
	> Cette page ne détaille pas toutes les options de chaque sous-commande. Pour obtenir la liste complète et à jour des options de toute sous-commande, exécutez `diffusers-cli <command> --help` (`diffusers-cli run --help`).

	## env

	Affiche les versions de Python, PyTorch et Diffusers, les informations CUDA et les dépendances optionnelles installées. Utilisez-le lors de l’ouverture d’un ticket afin que les mainteneurs puissent reproduire votre configuration.

	```bash
	diffusers-cli env
	```

	## schema

	Retourne les entrées acceptées par le pipeline sans télécharger les poids. Utilisez-le lors de la construction de `--pipeline-kwargs` pour [`run`](#run).

	Seul le fichier d’index est récupéré. Les pipelines standard lisent `model_index.json`. Les pipelines modulaires lisent `modular_model_index.json`. Les dépôts à blocs personnalisés lisent `modular_config.json` et nécessitent `--trust-remote-code`, car leur chargement exécute du code du 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

	Exécutez un pipeline de bout en bout. L’interface en ligne de commande détecte automatiquement les dépôts standard et modulaires. Elle charge automatiquement les entrées multimédias à partir d’URL ou de chemins locaux, enregistre les sorties selon le type de retour du pipeline et peut s’exécuter à distance sur un Hugging Face Sandbox via `--remote`.

	Exemple minimal :

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

	### Passage des arguments du pipeline

	`--pipeline-kwargs` prend un objet JSON qui est transmis à `pipeline(**kwargs)`. Les valeurs de chaîne aux clés d’entrée multimédia connues sont chargées automatiquement :

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

	Les clés média et texte acceptent toutes deux un tableau JSON pour exécuter un lot via un seul appel de pipeline. Chaque entrée d’une liste média est chargée individuellement (URL, chemin local ou chemin de montage de bucket), et Diffusers traite la liste entière en un seul passage avant sur le 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"
	]
	}'
	```

	### Chargement

	Configurez la façon dont l’interface en ligne de charge (CLI) charge les poids du modèle et le code de pipeline personnalisé.

	- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype des poids.
	- `--device-map <value>` — placement des composants. Accepte une chaîne de device torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (répartit automatiquement les composants entre les GPU visibles) ou un dictionnaire JSON pour un placement explicite par composant. Détecté automatiquement si omis. Voir [device_map](../optimization/device_map) pour plus de détails.
	- `--variant fp16` — choisir une variante de poids.
	- `--revision <sha>` — épingler une révision spécifique du modèle.
	- `--trust-remote-code` — autorise le code personnalisé issu du Hub (nécessaire pour les dépôts qui incluent des classes de pipeline personnalisées ou des blocs modulaires). Consultez [Community pipelines](../using-diffusers/custom_pipeline_overview) pour les pipelines personnalisés standard et [Modular Diffusers](../modular_diffusers/overview).
	- `--lora <spec>` — attacher un adaptateur LoRA après le chargement. Chaque valeur est un dictionnaire JSON. Répétez le drapeau pour empiler plusieurs adaptateurs. `lora_id` est obligatoire pour chaque entrée, `lora_scale` est défini par défaut sur `1.0`, et `adapter_name` est facultatif (généré automatiquement sous la forme `lora_<i>` lors de l’empilement).
	- Simple : `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
	- Plusieurs : `--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}'`

	Toutes les spécifications sont chargées par `pipeline.load_lora_weights(...)`, puis activées ensemble avec un seul appel à `pipeline.set_adapters(names, adapter_weights=scales)`. Consultez [LoRA](../tutorials/using_peft_for_inference) pour un guide détaillé sur le superposition d'adaptateurs, la planification des échelles et le changement à chaud.

	### Optimisations

	- `--cpu-offload {model, group, auto}` — la cible d'onload provient de `--device-map` (une chaîne de device simple est requise pour l'offload).
	- `model` — `enable_model_cpu_offload` pour les pipelines standard. Voir [Déchargement du modèle](../optimization/memory#model-offloading).
	- `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` pour les pipelines standard. Voir [Group offloading](../optimization/memory#group-offloading).
	- `auto` — uniquement en mode modulaire avec [`ComponentsManager`](../modular_diffusers/components_manager). Les modes standard lèvent une exception sur les pipelines modulaires. `auto` lève une exception sur les pipelines standard.
	- `--offload-margin <size>` — mémoire de l’appareil laissée libre pour les activations sous `--cpu-offload auto`, transmise à `enable_auto_cpu_offload` en tant que `memory_reserve_margin` (valeur par défaut `3GB`). Augmentez cette valeur si une grande toile épuise la mémoire en cours de propagation avant. Le déchargeur conserve les composants en mémoire tant qu’ils y tiennent, de sorte qu’avec une carte à forte VRAM, la marge par défaut peut laisser trop peu de place pour les activations d’une longue vidéo.
	- `--attention-backend` — Noyaux d’attention hébergés sur le Hub, téléchargés automatiquement lors de la première utilisation. Les choix sont `default` ainsi que les backends du Hub enregistrés dans Diffusers (par exemple `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Exécutez `diffusers-cli run --help` pour obtenir la liste actuelle. Il ne prend en charge que les pipelines basés sur des Transformers et est ignoré avec un avertissement sur les pipelines UNet legacy. Voir [Backends d’attention](../optimization/attention_backends).
	- `--vae-tiling` / `--vae-slicing` — réduit la VRAM utilisée par le décodage VAE. Consultez [tiling VAE](../optimization/memory#vae-tiling) et [slicing VAE](../optimization/memory#vae-slicing).
	- `--compile [JSON]` — compile les modules du débruiteur avec [torch.compile](../optimization/fp16#torchcompile). L’interface en ligne de commande privilégie la [compilation régionale](../optimization/fp16#regional-compilation) pour les modules comportant des blocs répétés. L’option `--compile` seule utilise `fullgraph=true`. Un objet JSON est transmis à `torch.compile`. Non pris en charge avec `--context-parallel`.
	- `--context-parallel` — parallélisme de contexte de type Ulysses sur un pipeline basé sur DiT. Nécessite localement torchrun, mais sous `--remote`, l’interface en ligne de commande encapsule `torchrun --nproc-per-node=gpu` pour vous. Voir [Parallélisme de contexte](../optimization/context_parallelism).

	### Pipelines modulaires

	`run` détecte automatiquement un [dépôt modulaire](../modular_diffusers/overview) — soit parce qu’il contient un `modular_model_index.json`, soit parce que son `model_index.json` référence une sous-classe de `ModularPipeline` — et aucun drapeau n’est nécessaire pour l’activer.

	Certains dépôts modulaires définissent plusieurs workflows semblables à des tâches nommées qui partagent des composants mais diffèrent par les blocs exécutés et les entrées qu’ils acceptent. [MiniMax-H3](../api/pipelines/minimax_h3), par exemple, propose `t2va` (texte vers vidéo et audio), `fl2va` (image clé première et/ou dernière) et `ref2va` (un mélange ordonné de références image, vidéo et audio). Passez `--workflow` pour en sélectionner un :

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

	Sélectionner un workflow ne conserve que les blocs de cette tâche, de sorte que le pipeline ne déclare que les composants dont il a besoin et `load_components` ne récupère que leurs sous-dossiers. Omettez `--workflow` pour conserver tous les workflows disponibles et laisser le pipeline choisir à chaque appel en fonction des entrées qui lui sont fournies.

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

	`--workflow` s'applique uniquement aux pipelines modulaires. Il est ignoré avec un avertissement sur les pipelines standard.

	Un pipeline modulaire renvoie un [`PipelineState`](../modular_diffusers/modular_pipeline) plutôt qu'un seul objet de sortie, de sorte que `--output-key` désigne l'intermédiaire à enregistrer.

	### Sorties

	`run` détecte le type de sortie du pipeline :

	- `PIL.Image`/liste → `<NNNN>.png` (index à zéros, par ex. `0000.png`)
	- Séquence d'images → `0000.mp4` (`--fps` contrôle la fréquence d'images, valeur par défaut 8)
	- Tableau audio → `0000.wav` (`--sampling-rate` contrôle le taux)
	- Tout le reste → déchargement JSON

	Le format du répertoire de sortie par défaut est `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Chaque exécution reçoit son propre sous-répertoire afin que les invocations successives ne s'écrasent pas.

	Utilisez `--output <path>` pour l'écraser. La manière dont le chemin est développé dépend de sa forme et de la taille du lot :

	\| `--output` \| 1 sortie \| Sorties N \|
	\|---\|---\|---\|
	\| _omitted_ \| répertoire par défaut → `0000.png` \| répertoire par défaut → `0000.png`, `0001.png`, `0002.png`, … \|
	\| `./results/` (avec un `/` final ou un répertoire existant) \| `./results/0000.png` \| `./results/0000.png`, `./results/0001.png`, … \|
	\| `my-cat.png` (chemin du fichier) \| `my-cat.png` (utilisé tel quel) \| `my-cat-0000.png`, `my-cat-0001.png`, … \|

	Les sorties de répertoire utilisent toujours des noms nus avec zéros d’alignement (`0000`, `0001`, …). Les chemins de fichiers explicites conservent la racine choisie et reçoivent l’index aligné en suffixe lorsque le lot produit plusieurs sorties.

	Utilisez `--push-to` pour téléverser les résultats dans un [seau de stockage Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Il accepte un :

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

	Un sous-chemin est utilisé comme préfixe de dossier. Le bucket est créé s'il est manquant, et les objets sont placés sous `[<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
	```

	Le tableau ci-dessous décrit les exécutions distantes. Pour les exécutions locales, `--push-to` téléverse la sortie enregistrée localement. Il ne supprime pas la création de fichiers locaux.

	\| `--push-to` défini ? \| `--output` défini ? \| Résultat \|
	\|---\|---\|---\|
	\| non \| non \| télécharger dans le répertoire local par défaut \|
	\| non \| oui \| télécharger vers `--output` \|
	\| oui \| non \| bucket uniquement, sans téléchargement local \|
	\| oui \| oui \| bucket ET `--output` \|

	`--format` forme les métadonnées de la sortie standard (chemins, chronométrage, informations sur le bac à sable). Il ne modifie pas le format de fichier des médias eux-mêmes. Les images écrites sont toujours au format PNG, les vidéos en MP4 et l’audio en WAV.

	### Exécution à distance (`--remote`)

	Effectuez le même appel dans un [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — une VM cloud isolée que le CLI pilote via HTTP : il téléverse les entrées, exécute le pipeline, télécharge les sorties, puis met fin au sandbox. Nécessite `huggingface_hub>=1.23`.

	Le bac à sable démarre à partir de [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), une image préconstruite qui inclut déjà torch, CUDA et les dépendances du CLI, de sorte qu'une exécution à froid commence à générer au lieu d'installer d'abord.

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

	Drapeaux distants :

	- `--flavor <name>` — matériel de la sandbox (par exemple, `a10g-small`, `h200`, `rtx-pro-6000`).
	- `--timeout <duration>` — durée maximale réelle pour la commande d’exécution dans le bac à sable (par défaut `10m`).
	- `--dependencies <pkg>` — dépendances pip supplémentaires (répétable), installées par-dessus l’image. Utile pour épingler un tarball de branche de diffusers ou ajouter des extras spécifiques à un pipeline.
	- `--namespace <name>` — crée le bac à sable sous une autre organisation/compte HF.
	- `--image <ref>` — remplace l’image du bac à sable. Elle doit inclure torch + CUDA compatible avec le pilote de votre `--flavor`. Le CLI installe alors ses propres dépendances par-dessus à chaque bac à sable froid, ce que l’image par défaut évite.
	- `--volume <bucket-id>[:<mount-path>]` — monte un [bucket de stockage HF](https://huggingface.co/docs/hub/en/storage-buckets) dans le bac à sable en tant que répertoire en lecture-écriture (répétable). Le chemin de montage par défaut est `/mnt/buckets/<bucket-id>`. Référencez les fichiers montés depuis `--pipeline-kwargs` comme n’importe quel autre chemin local. Appliqué uniquement lors de la création d’un nouveau bac à sable et ignoré lors de la reconnexion via `--sandbox-id`.

	Par défaut, chaque exécution `--remote` est éphémère (création → exécution → téléchargement → arrêt). Pour réutiliser un bac à sable chaud entre les exécutions — en conservant les dépendances, le cache des poids du modèle et le cache `torch.compile` sur son disque —, maintenez-le en vie et reconnectez-vous :

	- `--keep-alive` — ne pas mettre fin au bac à sable après l’exécution. Son identifiant est affiché.
	- `--sandbox-id <id>` — se reconnecter à un sandbox maintenu actif au lieu d’en créer un nouveau.
	- `--idle-timeout <duration>` — arrêt automatique après cette durée d’inactivité (par défaut `10m`). Appliqué uniquement lors de la création d’une nouvelle sandbox et ignoré lors d’une reconnexion 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`

	Emballer un sous-classe local de `ModularPipelineBlocks` pour le téléverser sur le Hub. Lit un fichier Python, l'analyse via AST pour détecter les classes dérivant de `ModularPipelineBlocks` ou de l'un de ses sous-classes composites (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), instancie celle choisie et appelle `save_pretrained` dans le répertoire de travail actuel.

	```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 classe de bloc doit être instantiable avec zéro argument de constructeur et durcit les valeurs par défaut dans `__init__` ou lit la configuration depuis l'`state` du pipeline au moment de l'appel.

	## `fp16_safetensors`

	> [!CAUTION]
	> Cette commande est désormais obsolète et sera supprimée dans une version future.

	Convertir un point de contrôle sur le Hub en `.safetensors` fp16 et pousser le résultat. Utile pour réduire la taille des poids d'un dépôt afin d'accélérer le chargement. Consultez `diffusers-cli fp16_safetensors --help` pour les arguments exacts.

	## `skills`

	Installer les compétences depuis le dépôt 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
	```

	Sans drapeau cible, le CLI installe pour l’agent qui l’a lancé, ou pour tous les agents s’il ne peut pas le déterminer. Claude Code reçoit un bundle de plugins sous `.claude/skills/diffusers/` (namespacé en tant que `/diffusers:<skill name>`). Codex et Cursor reçoivent `.agents/skills/<skill name>/`.