diffusers/main/en/using-diffusers/cli.md

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.

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.

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.

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:

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, 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.

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:

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} — 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.
• --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.

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

# 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.

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.

# 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.

# 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/).

# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills
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