Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /id /using-diffusers /cli.md

mishig

1 day ago

preview code

download

raw

18.1 kB

# Antarmuka baris perintah

`diffusers-cli` adalah klien baris perintah untuk menjalankan, memeriksa, dan mengemas pipeline Diffusers.

## Perintah yang tersedia

| Perintah | Tujuan |
|---|---|
| [`env`](#env) | Cetak informasi lingkungan untuk laporan bug. |
| [`schema`](#schema) | Periksa tanda tangan `__call__` sebuah pipeline tanpa mengunduh bobot. |
| [`run`](#run) | Jalankan pipeline secara lokal atau di Hugging Face Sandbox. |
| [`custom_blocks`](#customblocks) | Kemas subclass `ModularPipelineBlocks` lokal untuk Hub. |
| [`fp16_safetensors`](#fp16safetensors) | Konversi checkpoint ke fp16 `.safetensors`. |
| [`skills`](#skills) | Install bundel skill yang sudah dibuat sebelumnya ke agen coding AI Anda. |

> [!TIP]
> Halaman ini tidak memberikan detail untuk semua opsi di bawah setiap subcommand. Untuk daftar lengkap dan selalu terkini dari opsi untuk subcommand apa pun, jalankan `diffusers-cli <command> --help` (`diffusers-cli run --help`).

## env

Menampilkan versi Python, PyTorch, Diffusers, info CUDA, dan dependensi opsional yang terpasang. Gunakan ini saat membuka issue agar maintainer dapat mereproduksi setup Anda.

```bash
diffusers-cli env
```

## schema

Mengembalikan input yang diterima pipeline tanpa mengunduh bobot. Gunakan ini saat membangun `--pipeline-kwargs` untuk [`run`](#run).

Hanya file indeks yang diambil. Pipeline standar membaca `model_index.json`. Pipeline modular membaca `modular_model_index.json`. Repo dengan blok kustom membaca `modular_config.json` dan membutuhkan `--trust-remote-code`, karena memuatnya akan menjalankan kode 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

Jalankan pipeline secara end-to-end. CLI mendeteksi secara otomatis apakah repo bersifat standar atau modular. CLI memuat input media secara otomatis dari URL atau path lokal, menyimpan output berdasarkan tipe return dari pipeline, dan dapat dijalankan secara remote di Hugging Face Sandbox melalui `--remote`.

Contoh minimal:

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

### Menyalurkan argumen pipeline

`--pipeline-kwargs` menerima objek JSON yang diteruskan ke `pipeline(**kwargs)`. Nilai string pada kunci input media yang dikenal akan dimuat secara otomatis:

- Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` melalui `load_image`.
- Videos (`video`, `control_video`) → `list[PIL.Image]` melalui `load_video`.
- Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` melalui `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}'
```

Kunci media dan kunci teks sama-sama menerima array JSON untuk menjalankan batch melalui satu panggilan pipeline. Setiap entri dalam daftar media dimuat secara individual (URL, jalur lokal, atau jalur bucket-mount), dan Diffusers memproses seluruh daftar dalam satu forward pass di 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"
        ]
    }'
```

### Memuat

Konfigurasikan cara CLI memuat bobot model dan kode pipeline kustom.

- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype bobot.
- `--device-map <value>` — penempatan komponen. Menerima string perangkat torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (membagi komponen secara otomatis di antara GPU yang terlihat), atau dict JSON untuk penempatan per komponen secara eksplisit. Terdeteksi secara otomatis jika diabaikan. Lihat [device_map](../optimization/device_map) untuk detail lebih lanjut.
- `--variant fp16` — pilih varian bobot.
- `--revision <sha>` — mengunci revisi model tertentu.
- `--trust-remote-code` — mengizinkan kode kustom dari Hub (diperlukan untuk repositori yang menyertakan kelas pipeline kustom atau blok modular). Lihat [Community pipelines](../using-diffusers/custom_pipeline_overview) untuk pipeline kustom standar dan [Modular Diffusers](../modular_diffusers/overview).
- `--lora <spec>` — lampirkan adapter LoRA setelah pemuatan. Setiap nilai adalah dict JSON. Ulangi flag untuk menumpuk beberapa adapter. `lora_id` wajib untuk setiap entri, `lora_scale` secara default bernilai `1.0`, dan `adapter_name` bersifat opsional (dibuat otomatis sebagai `lora_<i>` saat menumpuk).
  - Tunggal: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
  - Berlebih: `--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}'`

  Semua spesifikasi dimuat oleh `pipeline.load_lora_weights(...)`, kemudian diaktifkan bersama dengan satu panggilan `pipeline.set_adapters(names, adapter_weights=scales)`. Lihat [LoRA](../tutorials/using_peft_for_inference) untuk penjelasan lebih mendalam tentang penumpukan adapter, penjadwalan skala, dan penggantian cepat.

### Optimasi

- `--cpu-offload {model, group, auto}` — target onload berasal dari `--device-map` (string device polos diperlukan untuk 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)` untuk pipeline standar. Lihat [Group offloading](../optimization/memory#group-offloading).
  - `auto` — hanya modular dengan [`ComponentsManager`](../modular_diffusers/components_manager). Mode standar memicu error pada pipeline modular. `auto` memicu error pada pipeline standar.
- `--offload-margin <size>` — memori perangkat yang dipertahankan bebas untuk aktivasi di bawah `--cpu-offload auto`, diteruskan ke `enable_auto_cpu_offload` sebagai `memory_reserve_margin` (default `3GB`). Naikkan nilai ini ketika kanvas besar kehabisan memori di tengah forward. Offloader mempertahankan komponen tetap resident selama masih muat, sehingga pada kartu dengan VRAM tinggi, margin default dapat menyisakan ruang yang terlalu sedikit untuk aktivasi video panjang.
- `--attention-backend` — Kernel attention yang di-host di Hub, diunduh secara otomatis saat pertama kali digunakan. Pilihan meliputi `default` ditambah backend Hub yang terdaftar di Diffusers (misalnya `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Jalankan `diffusers-cli run --help` untuk melihat daftar terkini. Opsi ini hanya mendukung pipeline berbasis Transformer, dan akan diabaikan dengan peringatan pada pipeline UNet lama. Lihat [Backend attention](../optimization/attention_backends).
- `--vae-tiling` / `--vae-slicing` — menurunkan VRAM decode VAE. Lihat [VAE tiling](../optimization/memory#vae-tiling) dan [VAE slicing](../optimization/memory#vae-slicing).
- `--compile [JSON]` — mengompilasi modul denoiser dengan [torch.compile](../optimization/fp16#torchcompile). CLI lebih memilih [regional compilation](../optimization/fp16#regional-compilation) untuk modul dengan blok berulang. `--compile` polos menggunakan `fullgraph=true`. Objek JSON diteruskan ke `torch.compile`. Tidak didukung dengan `--context-parallel`.
- `--context-parallel` — paralelisme konteks bergaya Ulysses pada pipeline berbasis DiT. Secara lokal memerlukan torchrun, tetapi di bawah `--remote`, CLI membungkus `torchrun --nproc-per-node=gpu` untuk Anda. Lihat [Paralelisme konteks](../optimization/context_parallelism).

### Pipeline modular

`run` mendeteksi [repo modular](../modular_diffusers/overview) secara otomatis — baik karena menyertakan `modular_model_index.json`, maupun karena `model_index.json`-nya menyebut subclass `ModularPipeline` — sehingga tidak perlu flag untuk mengaktifkannya.

Beberapa repositori modular mendefinisikan beberapa *workflows* seperti tugas bernama yang berbagi komponen tetapi berbeda dalam blok mana yang dijalankan dan input apa yang diambil. [MiniMax-H3](../api/pipelines/minimax_h3), misalnya, menawarkan `t2va` (teks ke video dan audio), `fl2va` (keyframe pertama dan/atau terakhir) dan `ref2va` (campuran terurut dari referensi gambar, video, dan audio). Lewatkan `--workflow` untuk memilih salah satu:

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

Memilih satu workflow hanya mempertahankan blok untuk tugas tersebut, sehingga pipeline hanya mendeklarasikan komponen yang dibutuhkan dan `load_components` hanya mengambil subfolder-nya. Lewatkan `--workflow` untuk mempertahankan semua workflow yang tersedia dan biarkan pipeline memilih per pemanggilan berdasarkan input yang diberikan.

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

`--workflow` hanya berlaku untuk pipeline modular. Opsi ini diabaikan dengan peringatan pada pipeline standar.

Pipeline modular mengembalikan [`PipelineState`](../modular_diffusers/modular_pipeline) alih-alih satu objek output, sehingga `--output-key` menamai intermediate yang akan disimpan.

### Output

`run` mendeteksi tipe output pipeline:

- `PIL.Image`/list → `<NNNN>.png` (indeks dengan nol di depan, mis. `0000.png`)
- Urutan gambar → `0000.mp4` (`--fps` mengontrol framerate, default 8)
- Array audio → `0000.wav` (`--sampling-rate` mengontrol laju)
- Hal lain → dump JSON

Format direktori output default adalah `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Setiap run mendapatkan subdirektori sendiri sehingga pemanggilan berurutan tidak saling menimpa.

Override dengan `--output <path>`. Cara path diperluas bergantung pada bentuknya dan ukuran batch:

| `--output` | 1 output | N output |
|---|---|---|
| _dihapus_ | dir default → `0000.png` | dir default → `0000.png`, `0001.png`, `0002.png`, … |
| `./results/` (akhiran `/` atau direktori yang sudah ada) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … |
| `my-cat.png` (jalur file) | `my-cat.png` (dipakai apa adanya) | `my-cat-0000.png`, `my-cat-0001.png`, … |

Output direktori selalu menggunakan nama bantalan polos (`0000`, `0001`, …). Jalur file eksplisit mempertahankan stem yang Anda pilih dan mendapatkan indeks bantalan yang ditambahkan ketika batch menghasilkan beberapa output.

Gunakan `--push-to` untuk mengunggah output ke [bucket penyimpanan Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Parameter ini menerima:

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

Subpath digunakan sebagai prefiks folder. Bucket dibuat jika belum ada, dan objek ditempatkan di bawah `[<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
```

Tabel di bawah ini menjelaskan eksekusi jarak jauh. Untuk eksekusi lokal, `--push-to` mengunggah output yang disimpan secara lokal. Hal ini tidak menekan pembuatan file lokal.

| Apakah `--push-to` diset? | `--output` diset? | Hasil |
|---|---|---|
| tidak | tidak | unduh ke direktori lokal default |
| tidak | ya | unduh ke `--output` |
| ya | tidak | hanya bucket, tanpa unduhan lokal |
| ya | ya | bucket DAN `--output` |

`--format` membentuk metadata stdout (path, timing, info sandbox). Parameter ini tidak mengubah format file media itu sendiri. Gambar yang ditulis selalu PNG, video MP4, dan audio WAV.

### Eksekusi jarak jauh (`--remote`)

Jalankan pemanggilan yang sama di dalam [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — VM cloud terisolasi yang dikendalikan CLI melalui HTTP: mengunggah input, menjalankan pipeline, mengunduh output, lalu mengakhiri sandbox. Memerlukan `huggingface_hub>=1.23`.

Sandbox berjalan dari [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), sebuah image yang sudah dibangun sebelumnya dan sudah menyertakan torch, CUDA, serta dependensi CLI, sehingga eksekusi dingin langsung mulai menghasilkan output tanpa perlu menginstal terlebih dahulu.

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

Flag jarak jauh:

- `--flavor <name>` — perangkat keras sandbox (misalnya, `a10g-small`, `h200`, `rtx-pro-6000`).
- `--timeout <duration>` — batas waktu maksimum untuk perintah run di dalam sandbox (default `10m`).
- `--dependencies <pkg>` — dependensi pip tambahan (dapat diulang), diinstal di atas image. Berguna untuk mengunci tarball cabang diffusers atau menambahkan ekstra yang spesifik untuk pipeline.
- `--namespace <name>` — buat sandbox di bawah org/akun HF yang berbeda.
- `--image <ref>` — menimpa image sandbox. Harus menyertakan torch + CUDA yang kompatibel dengan driver `--flavor` Anda. CLI kemudian menginstal dependensinya sendiri di atasnya di setiap sandbox dingin, yang dihindari oleh image default.
- `--volume <bucket-id>[:<mount-path>]` — mount [bucket penyimpanan HF](https://huggingface.co/docs/hub/en/storage-buckets) ke dalam sandbox sebagai direktori baca-tulis (dapat diulang). Path mount default adalah `/mnt/buckets/<bucket-id>`. Rujuk file yang di-mount dari `--pipeline-kwargs` seperti path lokal lainnya. Diterapkan hanya saat pembuatan sandbox baru dan diabaikan saat menyambung ulang melalui `--sandbox-id`.

Secara default, setiap eksekusi `--remote` bersifat sementara (buat → jalankan → unduh → matikan). Untuk menggunakan ulang sandbox yang sudah aktif antar eksekusi — dengan mempertahankan dependensi, cache bobot model, dan cache `torch.compile` di disk-nya — biarkan tetap hidup dan sambungkan kembali:

- `--keep-alive` — jangan akhiri sandbox setelah eksekusi. ID-nya akan dicetak.
- `--sandbox-id <id>` — sambungkan ulang ke sandbox yang dijaga tetap aktif, bukan membuat yang baru.
- `--idle-timeout <duration>` — auto-shutdown setelah durasi inaktivitas ini (default `10m`). Diterapkan hanya saat pembuatan sandbox baru dan diabaikan saat reconnecting 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`
Kemas subclass `ModularPipelineBlocks` lokal untuk diunggah ke Hub. Membaca file Python, memindai AST-nya untuk kelas yang diturunkan dari `ModularPipelineBlocks` atau salah satu subclass kompositnya (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), menginstansiasi yang dipilih, dan memanggil `save_pretrained` di direktori kerja saat ini.

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

Kelas blok harus dapat diinstansiasi dengan nol argumen konstruktor dan menghardcode nilai default di `__init__` atau membaca konfigurasi dari `state` pipeline pada saat pemanggilan.

## `fp16_safetensors`
> [!CAUTION]
> Perintah ini sekarang tidak didukung lagi dan akan dihapus dalam versi mendatang.
Konversi checkpoint di Hub menjadi `.safetensors` fp16 dan dorong hasilnya. Berguna untuk memperkecil ukuran bobot repo agar pemuatan lebih cepat. Lihat `diffusers-cli fp16_safetensors --help` untuk argumen yang tepat.

## `skills`

Install keterampilan dari repo 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
```

Tanpa flag target, CLI menginstal untuk agen yang meluncurkannya, atau untuk semua agen jika tidak dapat membedakannya. Claude Code mendapatkan bundle plugin di bawah `.claude/skills/diffusers/` (diberi namespace sebagai `/diffusers:<skill name>`). Codex dan Cursor mendapatkan `.agents/skills/<skill name>/`.

Xet Storage Details

Size:: 18.1 kB
Xet hash:: 52768e47b6ef13ae4023a8dff87f19bb66fbd2fbc8cf9cf988a6b13d8a9842e3

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

	# Antarmuka baris perintah

	`diffusers-cli` adalah klien baris perintah untuk menjalankan, memeriksa, dan mengemas pipeline Diffusers.

	## Perintah yang tersedia

	\| Perintah \| Tujuan \|
	\|---\|---\|
	\| [`env`](#env) \| Cetak informasi lingkungan untuk laporan bug. \|
	\| [`schema`](#schema) \| Periksa tanda tangan `__call__` sebuah pipeline tanpa mengunduh bobot. \|
	\| [`run`](#run) \| Jalankan pipeline secara lokal atau di Hugging Face Sandbox. \|
	\| [`custom_blocks`](#customblocks) \| Kemas subclass `ModularPipelineBlocks` lokal untuk Hub. \|
	\| [`fp16_safetensors`](#fp16safetensors) \| Konversi checkpoint ke fp16 `.safetensors`. \|
	\| [`skills`](#skills) \| Install bundel skill yang sudah dibuat sebelumnya ke agen coding AI Anda. \|

	> [!TIP]
	> Halaman ini tidak memberikan detail untuk semua opsi di bawah setiap subcommand. Untuk daftar lengkap dan selalu terkini dari opsi untuk subcommand apa pun, jalankan `diffusers-cli <command> --help` (`diffusers-cli run --help`).

	## env

	Menampilkan versi Python, PyTorch, Diffusers, info CUDA, dan dependensi opsional yang terpasang. Gunakan ini saat membuka issue agar maintainer dapat mereproduksi setup Anda.

	```bash
	diffusers-cli env
	```

	## schema

	Mengembalikan input yang diterima pipeline tanpa mengunduh bobot. Gunakan ini saat membangun `--pipeline-kwargs` untuk [`run`](#run).

	Hanya file indeks yang diambil. Pipeline standar membaca `model_index.json`. Pipeline modular membaca `modular_model_index.json`. Repo dengan blok kustom membaca `modular_config.json` dan membutuhkan `--trust-remote-code`, karena memuatnya akan menjalankan kode 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

	Jalankan pipeline secara end-to-end. CLI mendeteksi secara otomatis apakah repo bersifat standar atau modular. CLI memuat input media secara otomatis dari URL atau path lokal, menyimpan output berdasarkan tipe return dari pipeline, dan dapat dijalankan secara remote di Hugging Face Sandbox melalui `--remote`.

	Contoh minimal:

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

	### Menyalurkan argumen pipeline

	`--pipeline-kwargs` menerima objek JSON yang diteruskan ke `pipeline(**kwargs)`. Nilai string pada kunci input media yang dikenal akan dimuat secara otomatis:

	- Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` melalui `load_image`.
	- Videos (`video`, `control_video`) → `list[PIL.Image]` melalui `load_video`.
	- Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` melalui `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}'
	```

	Kunci media dan kunci teks sama-sama menerima array JSON untuk menjalankan batch melalui satu panggilan pipeline. Setiap entri dalam daftar media dimuat secara individual (URL, jalur lokal, atau jalur bucket-mount), dan Diffusers memproses seluruh daftar dalam satu forward pass di 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"
	]
	}'
	```

	### Memuat

	Konfigurasikan cara CLI memuat bobot model dan kode pipeline kustom.

	- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — dtype bobot.
	- `--device-map <value>` — penempatan komponen. Menerima string perangkat torch (`cuda`, `cuda:0`, `cpu`, `mps`), `balanced` (membagi komponen secara otomatis di antara GPU yang terlihat), atau dict JSON untuk penempatan per komponen secara eksplisit. Terdeteksi secara otomatis jika diabaikan. Lihat [device_map](../optimization/device_map) untuk detail lebih lanjut.
	- `--variant fp16` — pilih varian bobot.
	- `--revision <sha>` — mengunci revisi model tertentu.
	- `--trust-remote-code` — mengizinkan kode kustom dari Hub (diperlukan untuk repositori yang menyertakan kelas pipeline kustom atau blok modular). Lihat [Community pipelines](../using-diffusers/custom_pipeline_overview) untuk pipeline kustom standar dan [Modular Diffusers](../modular_diffusers/overview).
	- `--lora <spec>` — lampirkan adapter LoRA setelah pemuatan. Setiap nilai adalah dict JSON. Ulangi flag untuk menumpuk beberapa adapter. `lora_id` wajib untuk setiap entri, `lora_scale` secara default bernilai `1.0`, dan `adapter_name` bersifat opsional (dibuat otomatis sebagai `lora_<i>` saat menumpuk).
	- Tunggal: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
	- Berlebih: `--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}'`

	Semua spesifikasi dimuat oleh `pipeline.load_lora_weights(...)`, kemudian diaktifkan bersama dengan satu panggilan `pipeline.set_adapters(names, adapter_weights=scales)`. Lihat [LoRA](../tutorials/using_peft_for_inference) untuk penjelasan lebih mendalam tentang penumpukan adapter, penjadwalan skala, dan penggantian cepat.

	### Optimasi

	- `--cpu-offload {model, group, auto}` — target onload berasal dari `--device-map` (string device polos diperlukan untuk 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)` untuk pipeline standar. Lihat [Group offloading](../optimization/memory#group-offloading).
	- `auto` — hanya modular dengan [`ComponentsManager`](../modular_diffusers/components_manager). Mode standar memicu error pada pipeline modular. `auto` memicu error pada pipeline standar.
	- `--offload-margin <size>` — memori perangkat yang dipertahankan bebas untuk aktivasi di bawah `--cpu-offload auto`, diteruskan ke `enable_auto_cpu_offload` sebagai `memory_reserve_margin` (default `3GB`). Naikkan nilai ini ketika kanvas besar kehabisan memori di tengah forward. Offloader mempertahankan komponen tetap resident selama masih muat, sehingga pada kartu dengan VRAM tinggi, margin default dapat menyisakan ruang yang terlalu sedikit untuk aktivasi video panjang.
	- `--attention-backend` — Kernel attention yang di-host di Hub, diunduh secara otomatis saat pertama kali digunakan. Pilihan meliputi `default` ditambah backend Hub yang terdaftar di Diffusers (misalnya `flash_hub`, `flash_varlen_hub`, `flash_4_hub`, `sage_hub`, `sage_blackwell_hub`). Jalankan `diffusers-cli run --help` untuk melihat daftar terkini. Opsi ini hanya mendukung pipeline berbasis Transformer, dan akan diabaikan dengan peringatan pada pipeline UNet lama. Lihat [Backend attention](../optimization/attention_backends).
	- `--vae-tiling` / `--vae-slicing` — menurunkan VRAM decode VAE. Lihat [VAE tiling](../optimization/memory#vae-tiling) dan [VAE slicing](../optimization/memory#vae-slicing).
	- `--compile [JSON]` — mengompilasi modul denoiser dengan [torch.compile](../optimization/fp16#torchcompile). CLI lebih memilih [regional compilation](../optimization/fp16#regional-compilation) untuk modul dengan blok berulang. `--compile` polos menggunakan `fullgraph=true`. Objek JSON diteruskan ke `torch.compile`. Tidak didukung dengan `--context-parallel`.
	- `--context-parallel` — paralelisme konteks bergaya Ulysses pada pipeline berbasis DiT. Secara lokal memerlukan torchrun, tetapi di bawah `--remote`, CLI membungkus `torchrun --nproc-per-node=gpu` untuk Anda. Lihat [Paralelisme konteks](../optimization/context_parallelism).

	### Pipeline modular

	`run` mendeteksi [repo modular](../modular_diffusers/overview) secara otomatis — baik karena menyertakan `modular_model_index.json`, maupun karena `model_index.json`-nya menyebut subclass `ModularPipeline` — sehingga tidak perlu flag untuk mengaktifkannya.

	Beberapa repositori modular mendefinisikan beberapa workflows seperti tugas bernama yang berbagi komponen tetapi berbeda dalam blok mana yang dijalankan dan input apa yang diambil. [MiniMax-H3](../api/pipelines/minimax_h3), misalnya, menawarkan `t2va` (teks ke video dan audio), `fl2va` (keyframe pertama dan/atau terakhir) dan `ref2va` (campuran terurut dari referensi gambar, video, dan audio). Lewatkan `--workflow` untuk memilih salah satu:

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

	Memilih satu workflow hanya mempertahankan blok untuk tugas tersebut, sehingga pipeline hanya mendeklarasikan komponen yang dibutuhkan dan `load_components` hanya mengambil subfolder-nya. Lewatkan `--workflow` untuk mempertahankan semua workflow yang tersedia dan biarkan pipeline memilih per pemanggilan berdasarkan input yang diberikan.

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

	`--workflow` hanya berlaku untuk pipeline modular. Opsi ini diabaikan dengan peringatan pada pipeline standar.

	Pipeline modular mengembalikan [`PipelineState`](../modular_diffusers/modular_pipeline) alih-alih satu objek output, sehingga `--output-key` menamai intermediate yang akan disimpan.

	### Output

	`run` mendeteksi tipe output pipeline:

	- `PIL.Image`/list → `<NNNN>.png` (indeks dengan nol di depan, mis. `0000.png`)
	- Urutan gambar → `0000.mp4` (`--fps` mengontrol framerate, default 8)
	- Array audio → `0000.wav` (`--sampling-rate` mengontrol laju)
	- Hal lain → dump JSON

	Format direktori output default adalah `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/`. Setiap run mendapatkan subdirektori sendiri sehingga pemanggilan berurutan tidak saling menimpa.

	Override dengan `--output <path>`. Cara path diperluas bergantung pada bentuknya dan ukuran batch:

	\| `--output` \| 1 output \| N output \|
	\|---\|---\|---\|
	\| _dihapus_ \| dir default → `0000.png` \| dir default → `0000.png`, `0001.png`, `0002.png`, … \|
	\| `./results/` (akhiran `/` atau direktori yang sudah ada) \| `./results/0000.png` \| `./results/0000.png`, `./results/0001.png`, … \|
	\| `my-cat.png` (jalur file) \| `my-cat.png` (dipakai apa adanya) \| `my-cat-0000.png`, `my-cat-0001.png`, … \|

	Output direktori selalu menggunakan nama bantalan polos (`0000`, `0001`, …). Jalur file eksplisit mempertahankan stem yang Anda pilih dan mendapatkan indeks bantalan yang ditambahkan ketika batch menghasilkan beberapa output.

	Gunakan `--push-to` untuk mengunggah output ke [bucket penyimpanan Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Parameter ini menerima:

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

	Subpath digunakan sebagai prefiks folder. Bucket dibuat jika belum ada, dan objek ditempatkan di bawah `[<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
	```

	Tabel di bawah ini menjelaskan eksekusi jarak jauh. Untuk eksekusi lokal, `--push-to` mengunggah output yang disimpan secara lokal. Hal ini tidak menekan pembuatan file lokal.

	\| Apakah `--push-to` diset? \| `--output` diset? \| Hasil \|
	\|---\|---\|---\|
	\| tidak \| tidak \| unduh ke direktori lokal default \|
	\| tidak \| ya \| unduh ke `--output` \|
	\| ya \| tidak \| hanya bucket, tanpa unduhan lokal \|
	\| ya \| ya \| bucket DAN `--output` \|

	`--format` membentuk metadata stdout (path, timing, info sandbox). Parameter ini tidak mengubah format file media itu sendiri. Gambar yang ditulis selalu PNG, video MP4, dan audio WAV.

	### Eksekusi jarak jauh (`--remote`)

	Jalankan pemanggilan yang sama di dalam [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — VM cloud terisolasi yang dikendalikan CLI melalui HTTP: mengunggah input, menjalankan pipeline, mengunduh output, lalu mengakhiri sandbox. Memerlukan `huggingface_hub>=1.23`.

	Sandbox berjalan dari [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda), sebuah image yang sudah dibangun sebelumnya dan sudah menyertakan torch, CUDA, serta dependensi CLI, sehingga eksekusi dingin langsung mulai menghasilkan output tanpa perlu menginstal terlebih dahulu.

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

	Flag jarak jauh:

	- `--flavor <name>` — perangkat keras sandbox (misalnya, `a10g-small`, `h200`, `rtx-pro-6000`).
	- `--timeout <duration>` — batas waktu maksimum untuk perintah run di dalam sandbox (default `10m`).
	- `--dependencies <pkg>` — dependensi pip tambahan (dapat diulang), diinstal di atas image. Berguna untuk mengunci tarball cabang diffusers atau menambahkan ekstra yang spesifik untuk pipeline.
	- `--namespace <name>` — buat sandbox di bawah org/akun HF yang berbeda.
	- `--image <ref>` — menimpa image sandbox. Harus menyertakan torch + CUDA yang kompatibel dengan driver `--flavor` Anda. CLI kemudian menginstal dependensinya sendiri di atasnya di setiap sandbox dingin, yang dihindari oleh image default.
	- `--volume <bucket-id>[:<mount-path>]` — mount [bucket penyimpanan HF](https://huggingface.co/docs/hub/en/storage-buckets) ke dalam sandbox sebagai direktori baca-tulis (dapat diulang). Path mount default adalah `/mnt/buckets/<bucket-id>`. Rujuk file yang di-mount dari `--pipeline-kwargs` seperti path lokal lainnya. Diterapkan hanya saat pembuatan sandbox baru dan diabaikan saat menyambung ulang melalui `--sandbox-id`.

	Secara default, setiap eksekusi `--remote` bersifat sementara (buat → jalankan → unduh → matikan). Untuk menggunakan ulang sandbox yang sudah aktif antar eksekusi — dengan mempertahankan dependensi, cache bobot model, dan cache `torch.compile` di disk-nya — biarkan tetap hidup dan sambungkan kembali:

	- `--keep-alive` — jangan akhiri sandbox setelah eksekusi. ID-nya akan dicetak.
	- `--sandbox-id <id>` — sambungkan ulang ke sandbox yang dijaga tetap aktif, bukan membuat yang baru.
	- `--idle-timeout <duration>` — auto-shutdown setelah durasi inaktivitas ini (default `10m`). Diterapkan hanya saat pembuatan sandbox baru dan diabaikan saat reconnecting 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`

	Kemas subclass `ModularPipelineBlocks` lokal untuk diunggah ke Hub. Membaca file Python, memindai AST-nya untuk kelas yang diturunkan dari `ModularPipelineBlocks` atau salah satu subclass kompositnya (`SequentialPipelineBlocks`, `AutoPipelineBlocks`, `ConditionalPipelineBlocks`, `LoopSequentialPipelineBlocks`), menginstansiasi yang dipilih, dan memanggil `save_pretrained` di direktori kerja saat ini.

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

	Kelas blok harus dapat diinstansiasi dengan nol argumen konstruktor dan menghardcode nilai default di `__init__` atau membaca konfigurasi dari `state` pipeline pada saat pemanggilan.

	## `fp16_safetensors`

	> [!CAUTION]
	> Perintah ini sekarang tidak didukung lagi dan akan dihapus dalam versi mendatang.

	Konversi checkpoint di Hub menjadi `.safetensors` fp16 dan dorong hasilnya. Berguna untuk memperkecil ukuran bobot repo agar pemuatan lebih cepat. Lihat `diffusers-cli fp16_safetensors --help` untuk argumen yang tepat.

	## `skills`

	Install keterampilan dari repo 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
	```

	Tanpa flag target, CLI menginstal untuk agen yang meluncurkannya, atau untuk semua agen jika tidak dapat membedakannya. Claude Code mendapatkan bundle plugin di bawah `.claude/skills/diffusers/` (diberi namespace sebagai `/diffusers:<skill name>`). Codex dan Cursor mendapatkan `.agents/skills/<skill name>/`.