Command line interface

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

Available commands

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. Use it when building --pipeline-kwargs for run.

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, because loading them runs Hub code.

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. The CLI auto-detects standard vs modular repos. It auto-loads media inputs from URLs or local paths, saves outputs from 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, 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.

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, and 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} — onload target comes from --device-map (plain device string required for offload).
  • model — enable_model_cpu_offload for standard pipelines. See Model offloading.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) for standard pipelines. See Group offloading.
  • auto — modular only with ComponentsManager. Standard modes raise on modular pipelines. auto raises on 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 — Hub-hosted attention kernels, auto-downloaded on first use. Choices are default plus the Hub backends registered in Diffusers (for example flash_hub, flash_varlen_hub, flash_4_hub, sage_hub). Run diffusers-cli run --help for the current list. It only supports Transformer-based pipelines only, and is 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, but 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 like 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:

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.

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:

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. It accepts an:

• HF bucket id (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] HF URI
• browser URL

A subpath is used as a folder prefix. The bucket is created if missing, and 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.

--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 a current huggingface_hub with Sandbox support (Diffusers depends on huggingface-hub>=1.31).

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 (for example, 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 and 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 and 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 and hardcodes defaults in __init__ or read config from the pipeline state at call time.

fp16_safetensors

This command is now deprecated and will be removed in a future version.

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 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 the agent that launched it, or for every agent when it cannot tell. Claude Code gets a plugin bundle under .claude/skills/diffusers/ (namespaced as /diffusers:<skill name>). Codex and Cursor get .agents/skills/<skill name>/.