Overview
diffusers-cli is the shipped CLI in src/diffusers/commands/. Subcommands relevant to agentic use:
| Command |
Purpose |
run |
Run any DiffusionPipeline or ModularPipeline. Forwards --pipeline-kwargs verbatim, saves output by detecting its runtime type, optionally runs on HF Jobs via --remote. |
schema |
Print the input schema for a pipeline repo (kwarg names, types, defaults, descriptions). No weights downloaded — only the small index file. |
custom_blocks |
Package a local ModularPipelineBlocks subclass for the Hub. |
env |
Print versions of diffusers + torch + transformers + accelerate + safetensors + CUDA + GPU info. Use when investigating environment issues, dtype/precision support, or building bug reports. |
When to read which file
Most agentic work goes through run. Read the matching reference file before constructing a command:
run.md — full reference for diffusers-cli run. Covers --pipeline-kwargs
semantics and the shell-quoting gotcha, LoRA via --lora, optimization flags (--dtype, --cpu-offload,
--attention-backend, --vae-tiling/slicing), output handling and --push-to bucket uploads, the full
--remote HF Jobs flow (image, container command, log streaming, timing payload, artifact download), and
context parallel (--context-parallel) for both local-torchrun and --remote paths.
The other commands are small enough that diffusers-cli <command> --help is the canonical reference:
diffusers-cli schema --help
diffusers-cli custom_blocks --help
diffusers-cli env --help
When NOT to use this skill
- Multi-stage workflows where you need intermediate tensor manipulation between pipelines → write Python.
- Training or fine-tuning → CLI only covers inference.
- Anything requiring
quantization_config or other low-level loader knobs not exposed by the CLI flags → write
Python. (device_map is exposed as --device-map; see run.md.)
Verifying the CLI is installed
The console entry point is registered in pyproject.toml (diffusers-cli = "diffusers.commands.diffusers_cli:main"). If diffusers-cli is not on PATH after pip install -e ., reinstall
with pip install -e . --force-reinstall --no-deps and check which diffusers-cli. If the installed binary is
missing recent features (e.g. you see unrecognized arguments: --lora), reinstall.
Output formats
--format {auto, human, agent, json} (top-level flag, must appear before the subcommand):
human — plain-text indented output for terminals (default when not running under an agent harness). No ANSI color.agent — TSV tables and key=value lines. Auto-selected when an agent env var is present
(CLAUDECODE, CLAUDE_CODE, CODEX_SANDBOX, CURSOR_AI, AIDER_AI_CONTEXT, GH_COPILOT_AGENT,
AI_AGENT). Token-cheap for LLM agents to read.json — compact JSON. Use for programmatic parsing (scripts, services) where type fidelity and nested
structures matter.
stdout carries data; stderr carries hints/warnings/progress — parseable output is never polluted.
Rule of thumb: --format json for scripts that will json.loads() the output, otherwise leave it on
auto-detect (agent for LLMs, human for terminals).
1---2name: diffusers-cli3description: Use when the user wants to run a diffusers pipeline from a terminal (one-off generation, batch jobs, smoke-testing a new model), run on HF Sandbox hardware via `--remote`, introspect a pipeline's input schema before calling it, or attach a LoRA at inference time. Prefer this over writing ad-hoc Python scripts for generation tasks.4---56## Overview78`diffusers-cli` is the shipped CLI in `src/diffusers/commands/`. Subcommands relevant to agentic use:910| Command | Purpose |11| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |12| `run` | Run any `DiffusionPipeline` or `ModularPipeline`. Forwards `--pipeline-kwargs` verbatim, saves output by detecting its runtime type, optionally runs on HF Jobs via `--remote`. |13| `schema` | Print the input schema for a pipeline repo (kwarg names, types, defaults, descriptions). **No weights downloaded** — only the small index file. |14| `custom_blocks` | Package a local `ModularPipelineBlocks` subclass for the Hub. |15| `env` | Print versions of diffusers + torch + transformers + accelerate + safetensors + CUDA + GPU info. Use when investigating environment issues, dtype/precision support, or building bug reports. |1617## When to read which file1819Most agentic work goes through `run`. Read the matching reference file before constructing a command:2021- **[`run.md`](run.md)** — full reference for `diffusers-cli run`. Covers `--pipeline-kwargs`22 semantics and the shell-quoting gotcha, LoRA via `--lora`, optimization flags (`--dtype`, `--cpu-offload`,23 `--attention-backend`, `--vae-tiling/slicing`), output handling and `--push-to` bucket uploads, the full24 `--remote` HF Jobs flow (image, container command, log streaming, timing payload, artifact download), and25 context parallel (`--context-parallel`) for both local-torchrun and `--remote` paths.2627The other commands are small enough that `diffusers-cli <command> --help` is the canonical reference:2829```bash30diffusers-cli schema --help31diffusers-cli custom_blocks --help32diffusers-cli env --help33```3435## When NOT to use this skill3637- Multi-stage workflows where you need intermediate tensor manipulation between pipelines → write Python.38- Training or fine-tuning → CLI only covers inference.39- Anything requiring `quantization_config` or other low-level loader knobs not exposed by the CLI flags → write40 Python. (`device_map` is exposed as `--device-map`; see [run.md](run.md#optimization-flags).)4142## Verifying the CLI is installed4344The console entry point is registered in `pyproject.toml` (`diffusers-cli =45"diffusers.commands.diffusers_cli:main"`). If `diffusers-cli` is not on PATH after `pip install -e .`, reinstall46with `pip install -e . --force-reinstall --no-deps` and check `which diffusers-cli`. If the installed binary is47missing recent features (e.g. you see `unrecognized arguments: --lora`), reinstall.4849## Output formats5051`--format {auto, human, agent, json}` (top-level flag, must appear before the subcommand):5253- **`human`** — plain-text indented output for terminals (default when not running under an agent harness). No ANSI color.54- **`agent`** — TSV tables and `key=value` lines. Auto-selected when an agent env var is present55 (`CLAUDECODE`, `CLAUDE_CODE`, `CODEX_SANDBOX`, `CURSOR_AI`, `AIDER_AI_CONTEXT`, `GH_COPILOT_AGENT`,56 `AI_AGENT`). Token-cheap for LLM agents to read.57- **`json`** — compact JSON. Use for programmatic parsing (scripts, services) where type fidelity and nested58 structures matter.5960`stdout` carries data; `stderr` carries hints/warnings/progress — parseable output is never polluted.6162Rule of thumb: `--format json` for scripts that will `json.loads()` the output, otherwise leave it on63auto-detect (`agent` for LLMs, `human` for terminals).
Hugging Face