modem-dev/ossrules / public/files/diffusers/.ai/skills/diffusers-cli
diffusers-cli
UnverifiedUse 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.
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 fordiffusers-cli run. Covers--pipeline-kwargssemantics and the shell-quoting gotcha, LoRA via--lora, optimization flags (--dtype,--cpu-offload,--attention-backend,--vae-tiling/slicing), output handling and--push-tobucket uploads, the full--remoteHF Jobs flow (image, container command, log streaming, timing payload, artifact download), and context parallel (--context-parallel) for both local-torchrun and--remotepaths.
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_configor other low-level loader knobs not exposed by the CLI flags → write Python. (device_mapis 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 andkey=valuelines. 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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |