diffusers-cli

por huggingface

Use cuando el usuario quiera ejecutar un pipeline de diffusers desde un terminal (generación puntual, trabajos por lotes, prueba rápida de un nuevo modelo), ejecutar en hardware de HF Sandbox mediante…

npx skills add https://github.com/huggingface/diffusers --skill diffusers-cli

Descargar ZIP GitHub

34.6k

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