Command line interface

diffusers-cli is a command line client for running, inspecting, and packaging Diffusers pipelines.

Available commands

Command	Purpose
`env`	Print environment info for bug reports.
`schema`	Inspect a pipeline's `__call__` signature without downloading weights.
`run`	Run a pipeline locally or in a Hugging Face Sandbox.
`custom_blocks`	Package a local `ModularPipelineBlocks` subclass for the Hub.
`fp16_safetensors`	Convert a checkpoint to fp16 `.safetensors`.
`skills`	Install pre-authored skill bundles into your AI coding agent.

[!TIP] This page does not provide details for all options under each subcommand. For the full, always-current list of options for any subcommand, run diffusers-cli <command> --help (diffusers-cli run --help).

`env`

Prints Python/PyTorch/Diffusers versions, CUDA info, and installed optional deps. Use it when opening an issue so maintainers can reproduce your setup.

bash

diffusers-cli env

`schema`

Returns the pipeline's accepted inputs without downloading weights. This is useful when building --pipeline-kwargs

Only the index file is fetched. Standard pipelines read model_index.json; modular pipelines read modular_model_index.json; custom-block repos read modular_config.json and need --trust-remote-code since loading them runs code from the 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`

Run a pipeline end-to-end. Auto-detects standard vs modular repos, auto-loads media inputs from URLs or local paths, saves outputs by detecting the pipeline's return type, and can run remotely on a Hugging Face Sandbox via --remote.

Minimal example:

bash

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

Passing pipeline arguments

--pipeline-kwargs takes a JSON object that's forwarded to pipeline(**kwargs). String values at known media-input keys are auto-loaded:

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

Both media keys and text keys accept a JSON array to run a batch through a single pipeline call. Each entry in a media list is loaded individually (URL, local path, or bucket-mount path), and diffusers processes the whole list in one forward pass on the 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"
        ]
    }'

Loading

Configure how the CLI loads model weights and custom pipeline code.

--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — weight dtype.
--device-map <value> — component placement. Accepts a torch device string (cuda, cuda:0, cpu, mps), balanced (auto-splits components across visible GPUs), or a JSON dict for explicit per-component placement. Auto-detected if omitted. See device_map for more details
--variant fp16 — pick a weight variant.
--revision <sha> — pin a specific model revision.
--trust-remote-code — allow custom code from the Hub (required for repos that ship custom pipeline classes or modular blocks). See Community pipelines for standard custom pipelines and Modular Diffusers.
--lora <spec> — attach a LoRA adapter after loading. Each value is a JSON dict; repeat the flag to stack multiple adapters. lora_id is required per entry; lora_scale defaults to 1.0; adapter_name is optional (auto-generated as lora_<i> when stacking).
- Single: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
- Multiple: --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}'
All specs are loaded by pipeline.load_lora_weights(...), then activated together with a single pipeline.set_adapters(names, adapter_weights=scales) call. See LoRA for a deeper walkthrough of adapter stacking, scale scheduling, and hotswapping.

Optimizations

--cpu-offload {model, group, auto} — model calls enable_model_cpu_offload; group calls enable_group_offload(offload_type="leaf_level", use_stream=True). Onload target comes from --device-map (which must be a plain device string for offload). See Model offloading and Group offloading. Modular pipelines support only auto, which offloads through their ComponentsManager; the standard modes raise for them, and auto raises for standard pipelines.
--offload-margin <size> — device memory kept free for activations under --cpu-offload auto, passed to enable_auto_cpu_offload as memory_reserve_margin (default 3GB). Raise it when a large canvas runs out of memory mid-forward: the offloader keeps components resident while they fit, so on a high-VRAM card the default margin can leave too little room for the activations of a long video.
--attention-backend {default, flash_hub, flash_varlen_hub, flash_4_hub, sage_hub} — Hub-hosted attention kernels, auto-downloaded on first use. Transformer-based pipelines only; ignored with a warning on legacy UNet pipelines. See Attention backends.
--vae-tiling / --vae-slicing — lower VAE decode VRAM. See VAE tiling and VAE slicing.
--compile [JSON] — compile denoiser modules with torch.compile. The CLI prefers regional compilation for modules with repeated blocks. Bare --compile uses fullgraph=true. A JSON object is forwarded to torch.compile. Not supported with --context-parallel.
--context-parallel — Ulysses-style context parallelism on a DiT-based pipeline. Locally requires torchrun; under --remote the CLI wraps torchrun --nproc-per-node=gpu for you. See Context parallelism.

Modular pipelines

run detects a modular repo automatically — either because it ships a modular_model_index.json, or because its model_index.json names a ModularPipeline subclass — so no flag is needed to opt in.

Some modular repos define several workflows: named tasks that share components but differ in which blocks run and which inputs they take. MiniMax-H3, for example, offers t2va (text to video and audio), fl2va (first and/or last keyframe) and ref2va (an ordered mix of image, video and audio references). Pass --workflow to select one:

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

Selecting a workflow keeps only that task's blocks, so the pipeline declares only the components it needs and load_components fetches only their subfolders. Omit --workflow to keep every workflow available and let the pipeline pick per call from the inputs it is given.

bash

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

--workflow applies to modular pipelines only; it is ignored with a warning on standard pipelines.

A modular pipeline returns a PipelineState rather than a single output object, so --output-key names the intermediate to save.

Outputs

run detects the pipeline output type:

PIL.Image/list → <NNNN>.png (zero-padded index, e.g. 0000.png)
Image sequence → 0000.mp4 (--fps controls framerate, default 8)
Audio array → 0000.wav (--sampling-rate controls rate)
Anything else → JSON dump

The default output directory format is ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Each run gets its own subdirectory so consecutive invocations don't overwrite.

Override with --output <path>. How the path expands depends on its shape and the batch size:

`--output`	1 output	N outputs
omitted	default dir → `0000.png`	default dir → `0000.png`, `0001.png`, `0002.png`, …
`./results/` (trailing `/` or an existing directory)	`./results/0000.png`	`./results/0000.png`, `./results/0001.png`, …
`my-cat.png` (file path)	`my-cat.png` (used verbatim)	`my-cat-0000.png`, `my-cat-0001.png`, …

Directory outputs always use bare padded names (0000, 0001, …). Explicit file paths preserve your chosen stem and get the padded index appended when the batch produces multiple outputs.

Use --push-to to upload outputs to a Hugging Face storage bucket. Accepts an HF bucket id (<namespace>/<name>), an hf://buckets/<namespace>/<name>[/<subpath>] HF URI, or a browser URL for the same — a subpath is used as a folder prefix. The bucket is created if missing; objects land under [<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

The table below describes remote runs. For local runs, --push-to uploads the locally saved output. It does not suppress local file creation.

`--push-to` set?	`--output` set?	Result
no	no	download to default local dir
no	yes	download to `--output`
yes	no	bucket only, no local download
yes	yes	bucket AND `--output`

--format shapes the stdout metadata (paths, timing, sandbox info) — it does not change the file format of the media itself. Written images are always PNG, videos MP4, audio WAV.

Remote execution (`--remote`)

Run the same call inside a Hugging Face Sandbox — an isolated cloud VM the CLI drives over HTTP: it uploads inputs, installs deps, runs the pipeline, downloads outputs, then terminates the sandbox. Requires huggingface_hub>=1.23.

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

Remote flags:

--flavor <name> — sandbox hardware (e.g. a10g-small, h200, rtx-pro-6000).
--timeout <duration> — max wallclock for the run command inside the sandbox (default 10m).
--dependencies <pkg> — extra pip deps (repeatable). Useful for pinning a diffusers branch tarball or adding pipeline-specific extras.
--namespace <name> — create the sandbox under a different HF org/account.
--image <ref> — override the sandbox image. Must ship torch + CUDA compatible with your --flavor's driver.
--volume <bucket-id>[:<mount-path>] — mount an HF storage bucket into the sandbox as a read-write directory. Repeatable. Default mount path is /mnt/buckets/<bucket-id>. Reference mounted files from --pipeline-kwargs like any other local path. Applied only on new sandbox creation — ignored when reconnecting via --sandbox-id.

By default each --remote run is ephemeral (create → run → download → kill). To reuse a warm sandbox across runs — keeping deps, the model weight cache, and the torch.compile cache on its disk — keep it alive and reconnect:

--keep-alive — don't terminate the sandbox after the run; its id is printed.
--sandbox-id <id> — reconnect to a kept-alive sandbox instead of creating a new one.
--idle-timeout <duration> — auto-shutdown after this much inactivity (default 10m). Applied only on new sandbox creation — ignored when 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`

Package a local ModularPipelineBlocks subclass for upload to the Hub. Reads a Python file, AST-scans it for subclasses of ModularPipelineBlocks, instantiates the chosen one, and calls save_pretrained in the current working directory.

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

The block class must be instantiable with zero constructor args — hardcode defaults in __init__ or read config from the pipeline state at call time.

`fp16_safetensors`

Convert a checkpoint on the Hub to fp16 .safetensors and push the result. Useful for shrinking a repo's weight size for faster loading. See diffusers-cli fp16_safetensors --help for the exact args.

`skills`

Install skills from the diffusers repo (.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

Without a target flag, the CLI installs for whichever agent launched it, or for every agent when it can't tell. For Claude Code the skills are written as a plugin bundle at .claude/skills/diffusers/, so they are namespaced as /diffusers:<skill name>; Codex and Cursor get .agents/skills/<skill name>/.

Command line interface

Command line interface

Available commands

env

schema

run

Passing pipeline arguments

Loading

Optimizations

Modular pipelines

Outputs

Remote execution (--remote)

custom_blocks

fp16_safetensors

skills

`env`

`schema`

`run`

Remote execution (`--remote`)

`custom_blocks`

`fp16_safetensors`

`skills`