diffusers-cli

1---2name: diffusers-cli3description: >4  Use when the user wants to run a diffusers pipeline from a terminal (one-off5  generation, batch jobs, smoke-testing a new model), run on HF Sandbox6  hardware via `--remote`, introspect a pipeline's input schema before7  calling it, or attach a LoRA at inference time. Prefer this over writing8  ad-hoc Python scripts for generation tasks.9---10 11## Overview12 13`diffusers-cli` is the shipped CLI in `src/diffusers/commands/`. Subcommands relevant to agentic use:14 15| Command         | Purpose                                                                                                                                                                                       |16| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |17| `run`      | Run any `DiffusionPipeline` or `ModularPipeline`. Forwards `--pipeline-kwargs` verbatim, saves output by detecting its runtime type, optionally runs on HF Jobs via `--remote`.                |18| `schema`      | Print the input schema for a pipeline repo (kwarg names, types, defaults, descriptions). **No weights downloaded** — only the small index file.                                               |19| `custom_blocks` | Package a local `ModularPipelineBlocks` subclass for the Hub.                                                                                                                                 |20| `env`           | Print versions of diffusers + torch + transformers + accelerate + safetensors + CUDA + GPU info. Use when investigating environment issues, dtype/precision support, or building bug reports. |21 22## When to read which file23 24Most agentic work goes through `run`. Read the matching reference file before constructing a command:25 26- **[`run.md`](run.md)** — full reference for `diffusers-cli run`. Covers `--pipeline-kwargs`27  semantics and the shell-quoting gotcha, LoRA via `--lora`, optimization flags (`--dtype`, `--cpu-offload`,28  `--attention-backend`, `--vae-tiling/slicing`), output handling and `--push-to` bucket uploads, the full29  `--remote` HF Jobs flow (image, container command, log streaming, timing payload, artifact download), and30  context parallel (`--context-parallel`) for both local-torchrun and `--remote` paths.31 32The other commands are small enough that `diffusers-cli <command> --help` is the canonical reference:33 34```bash35diffusers-cli schema --help36diffusers-cli custom_blocks --help37diffusers-cli env --help38```39 40## When NOT to use this skill41 42- Multi-stage workflows where you need intermediate tensor manipulation between pipelines → write Python.43- Training or fine-tuning → CLI only covers inference.44- Anything requiring `quantization_config` or other low-level loader knobs not exposed by the CLI flags → write45  Python. (`device_map` is exposed as `--device-map`; see [run.md](run.md#optimization-flags).)46 47## Verifying the CLI is installed48 49The console entry point is registered in `pyproject.toml` (`diffusers-cli =50"diffusers.commands.diffusers_cli:main"`). If `diffusers-cli` is not on PATH after `pip install -e .`, reinstall51with `pip install -e . --force-reinstall --no-deps` and check `which diffusers-cli`. If the installed binary is52missing recent features (e.g. you see `unrecognized arguments: --lora`), reinstall.53 54## Output formats55 56`--format {auto, human, agent, json}` (top-level flag, must appear before the subcommand):57 58- **`human`** — plain-text indented output for terminals (default when not running under an agent harness). No ANSI color.59- **`agent`** — TSV tables and `key=value` lines. Auto-selected when an agent env var is present60  (`CLAUDECODE`, `CLAUDE_CODE`, `CODEX_SANDBOX`, `CURSOR_AI`, `AIDER_AI_CONTEXT`, `GH_COPILOT_AGENT`,61  `AI_AGENT`). Token-cheap for LLM agents to read.62- **`json`** — compact JSON. Use for programmatic parsing (scripts, services) where type fidelity and nested63  structures matter.64 65`stdout` carries data; `stderr` carries hints/warnings/progress — parseable output is never polluted.66 67Rule of thumb: `--format json` for scripts that will `json.loads()` the output, otherwise leave it on68auto-detect (`agent` for LLMs, `human` for terminals).69