Diffusers CLI (Hugging Face)

---
name: diffusers-cli
description: >
  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.
metadata:
  origin: Hugging Face
---

## 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`](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:

```bash
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](run.md#optimization-flags).)

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