# コマンドラインインターフェース

`diffusers-cli` は、Diffusers のパイプラインを実行、検査、パッケージングするためのコマンドラインクライアントです。

## 利用可能なコマンド

| コマンド | 目的 |
|---|---|
| [`env`](#env) | バグレポート用に環境情報を出力します。 |
| [`schema`](#schema) | 重みをダウンロードせずに、パイプラインの`__call__`シグネチャを確認します。 |
| [`run`](#run) | パイプラインをローカルまたは Hugging Face Sandbox で実行します。 |
| [`custom_blocks`](#customblocks) | ローカルの`ModularPipelineBlocks`サブクラスをパッケージして、Hubに公開します。 |
| [`fp16_safetensors`](#fp16safetensors) | チェックポイントを`.safetensors`形式のfp16に変換します。 |
| [`skills`](#skills) | AIコーディングエージェントに、事前作成済みのスキルバンドルをインストールします。 |

> [!TIP]
> このページでは、各サブコマンドのすべてのオプションの詳細を記載していません。任意のサブコマンドの最新かつ完全なオプション一覧を確認するには、`diffusers-cli <command> --help`（`diffusers-cli run --help`）を実行してください。

## env

Python、PyTorch、Diffusers のバージョン、CUDA の情報、およびインストールされている任意の依存関係を出力します。Issue を作成する際に使用し、メンテナーがあなたの環境を再現できるようにしてください。

```bash
diffusers-cli env
```

## スキーマ

重みをダウンロードせずに、パイプラインが受け入れる入力値を返します。[`run`](#run) 用の `--pipeline-kwargs` を構築する際に使用します。

インデックスファイルのみが取得されます。標準のパイプラインは`model_index.json`を読み込みます。モジュラーパイプラインは`modular_model_index.json`を読み込みます。カスタムブロックのリポジトリは`modular_config.json`を読み込み、Hub上のコードが実行されるため、`--trust-remote-code`が必要です。

```bash
diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev
diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code
```

## run

パイプラインをエンドツーエンドで実行します。CLI は、標準リポジトリとモジュラーリポジトリを自動検出します。URL またはローカルパスからメディア入力を自動読み込み、パイプラインの戻り値の型に基づいて出力を保存し、`--remote` を使用して Hugging Face Sandbox 上でリモート実行することもできます。

最小限の例:

```bash
diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev \
    --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}'
```

### パイプライン引数の渡し方

`--pipeline-kwargs` は、`pipeline(**kwargs)` に転送される JSON オブジェクトを受け取ります。既知のメディア入力キーにある文字列値は自動的に読み込まれます:

- Images (`image`、`last_image`、`mask_image`、`control_image`、`ip_adapter_image`、`image_2`) は、`load_image` を通じて `PIL.Image` として返されます。
- Videos (`video`, `control_video`) → `list[PIL.Image]`（`load_video` 経由）。
- Audio (`initial_audio_waveforms`、`reference_audio`、`src_audio`) → `torch.Tensor`（`torchaudio.load` 経由）。

```bash
diffusers-cli run \
    --model black-forest-labs/FLUX.2-klein-9B --dtype bf16 \
    --pipeline-kwargs '{"prompt": "make the fur grey", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png", "strength": 0.6}'
```

メディアキーとテキストキーの両方で、JSON配列を受け取り、単一のパイプライン呼び出しでバッチ処理を実行できます。メディアリストの各エントリは個別に読み込まれます（URL、ローカルパス、またはバケットマウントパス）。DiffusersはGPU上で1回のフォワードパスでリスト全体を処理します。

```bash
diffusers-cli run \
    --model black-forest-labs/FLUX.1-Kontext-dev --dtype bf16 \
    --pipeline-kwargs '{
        "prompt": ["make it grey", "make it pink", "make it blue"],
        "image": [
            "https://.../cat1.png",
            "https://.../cat2.png",
            "https://.../cat3.png"
        ]
    }'
```

### 読み込み中

CLIがモデルの重みとカスタムパイプラインコードを読み込む方法を設定します。

- `--dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32}` — 重みの dtype。
- `--device-map <value>` — コンポーネントの配置。torch のデバイス文字列（`cuda`、`cuda:0`、`cpu`、`mps`）、`balanced`（表示可能な GPU にコンポーネントを自動分割して配置）、またはコンポーネントごとの明示的な配置を指定する JSON 辞書を受け取ります。省略した場合、自動検出されます。詳細は [device_map](../optimization/device_map) を参照してください。
- `--variant fp16` — 重みのバリアントを選択します。
- `--revision <sha>` — 特定のモデルのリビジョンを固定します。
- `--trust-remote-code` — Hub からのカスタムコードを許可します（カスタムパイプラインクラスやモジュラーブロックを同梱するリポジトリでは必須です）。標準的なカスタムパイプラインについては [Community pipelines](../using-diffusers/custom_pipeline_overview)、[Modular Diffusers](../modular_diffusers/overview) についてはそれぞれ該当のセクションを参照してください。
- `--lora <spec>` — 読み込み後に LoRA アダプターを付与します。各値は JSON 辞書です。複数のアダプターをスタックするには、このフラグを繰り返し指定します。各エントリには `lora_id` が必須で、`lora_scale` のデフォルト値は `1.0` です。`adapter_name` は任意で、スタックする場合は `lora_<i>` として自動生成されます。
  - 単一: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'`
  - 複数: `--lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'`

  すべての仕様は`pipeline.load_lora_weights(...)`によって読み込まれ、その後、単一の`pipeline.set_adapters(names, adapter_weights=scales)`呼び出しで同時に有効化されます。アダプタのスタッキング、スケールスケジューリング、ホットスワップの詳細については、[LoRA](../tutorials/using_peft_for_inference)を参照してください。

### 最適化

- `--cpu-offload {model, group, auto}` — onload の対象は `--device-map` から取得されます（offload にはプレーンなデバイス文字列が必要です）。
  - `model` — 標準パイプライン用の`enable_model_cpu_offload`。[モデルのオフロード](../optimization/memory#model-offloading)を参照してください。
  - `group` — 標準的なパイプラインには `enable_group_offload(offload_type="leaf_level", use_stream=True)` を使用します。[グループオフロード](../optimization/memory#group-offloading)を参照してください。
  - `auto` — [`ComponentsManager`](../modular_diffusers/components_manager)でのみモジュラーに対応します。標準モードではモジュラーパイプラインで例外を発生させます。`auto`は標準パイプラインで例外を発生させます。
- `--offload-margin <size>` — `--cpu-offload auto` の下でアクティベーション用に確保しておくデバイスメモリ量。`enable_auto_cpu_offload` に `memory_reserve_margin` として渡されます（デフォルトは `3GB`）。大きなキャンバスでフォワードの途中でメモリ不足が発生する場合は、この値を上げてください。オフローダーはコンポーネントが収まる限りレジデントに保つため、VRAM の大きいカードでは、デフォルトのマージンでは長い動画のアクティベーションに十分な領域が確保されない場合があります。
- `--attention-backend` — Hub にホストされているアテンションカーネルで、初回使用時に自動ダウンロードされます。選択肢は `default` と、Diffusers に登録されている Hub バックエンド（例: `flash_hub`、`flash_varlen_hub`、`flash_4_hub`、`sage_hub`、`sage_blackwell_hub`）です。現在のリストを確認するには `diffusers-cli run --help` を実行してください。Transformer ベースのパイプラインのみサポートしており、レガシーな UNet パイプラインでは警告とともに無視されます。[アテンションバックエンド](../optimization/attention_backends)を参照してください。
- `--vae-tiling` / `--vae-slicing` — VAE デコード時の VRAM 使用量を削減します。[VAE tiling](../optimization/memory#vae-tiling) と [VAE slicing](../optimization/memory#vae-slicing) を参照してください。
- `--compile [JSON]` — [torch.compile](../optimization/fp16#torchcompile)でデノイザーモジュールをコンパイルします。繰り返しブロックを持つモジュールには、CLIが[地域コンパイル](../optimization/fp16#regional-compilation)を優先します。単に`--compile`を指定すると、`fullgraph=true`が使用されます。JSONオブジェクトは`torch.compile`に転送されます。`--context-parallel`との併用はサポートされていません。
- `--context-parallel` — DiT ベースのパイプラインにおける Ulysses 方式のコンテキスト並列化。ローカルでは torchrun が必要ですが、`--remote` を使用すると、CLI が `torchrun --nproc-per-node=gpu` を自動的にラップします。[コンテキスト並列化](../optimization/context_parallelism)を参照してください。

### モジュール化されたパイプライン

`run` は、`modular_model_index.json` が同梱されているか、`model_index.json` が `ModularPipeline` のサブクラスを指定しているかのいずれかの場合に、[モジュラーリポジトリ](../modular_diffusers/overview) を自動的に検出します。そのため、オプトイン用のフラグは不要です。

一部のモジュラーリポジトリでは、コンポーネントを共有しながら、実行されるブロックや受け取る入力が異なる、名前付きタスクのような複数の*ワークフロー*が定義されています。例えば、[MiniMax-H3](../api/pipelines/minimax_h3)では、`t2va`（テキストから動画と音声への変換）、`fl2va`（最初のキーフレームと/または最後のキーフレーム）、`ref2va`（画像、動画、音声の参照の順序付きミックス）が提供されています。`--workflow`を渡すことで、いずれかを選択できます。

```bash
diffusers-cli run \
    --model MiniMaxAI/MiniMax-H3 --workflow fl2va \
    --pipeline-kwargs '{
        "prompt": "the camera pushes in slowly as rain falls",
        "image": "opening-frame.png",
        "last_image": "closing-frame.png",
        "num_frames": 124
    }' \
    --output-key videos --output-key audio \
    --fps 24 --sampling-rate 32000 \
    --cpu-offload auto --dtype bf16
```

ワークフローを選択すると、そのタスクのブロックのみが保持されるため、パイプラインは必要なコンポーネントのみを宣言し、`load_components` はそれらのサブフォルダのみを取得します。`--workflow` を省略すると、利用可能なすべてのワークフローが保持され、パイプラインは与えられた入力に基づいて呼び出しごとに選択します。

```bash
diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code
```

`--workflow` はモジュラーパイプラインにのみ適用されます。標準パイプラインでは、警告とともに無視されます。

モジュール型パイプラインは単一の出力オブジェクトではなく、[`PipelineState`](../modular_diffusers/modular_pipeline) を返すため、`--output-key` は保存する中間結果を指定します。

### 出力

`run` はパイプラインの出力タイプを検出します：

- `PIL.Image`/list → `<NNNN>.png`（ゼロパディングされたインデックス、例: `0000.png`）
- 画像シーケンス → `0000.mp4`（`--fps` でフレームレートを制御します。デフォルトは 8 です）
- オーディオ配列 → `0000.wav`（`--sampling-rate` でレートが制御されます）
- それ以外 → JSON ダンプ

デフォルトの出力ディレクトリ形式は `~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/` です。各実行には独自のサブディレクトリが割り当てられるため、連続した呼び出しによって上書きされることはありません。

`--output <path>` で上書きできます。パスの展開方法は、パスの形式とバッチサイズによって異なります。

| `--output` | 1つの出力 | N 個の出力 |
|---|---|---|
| _省略_ | デフォルトのディレクトリ → `0000.png` | デフォルトのディレクトリ → `0000.png`、`0001.png`、`0002.png`、… |
| `./results/`（末尾に`/`を付けるか、既存のディレクトリを指定） | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … |
| `my-cat.png`（ファイルパス） | `my-cat.png`（そのまま使用） | `my-cat-0000.png`, `my-cat-0001.png`, … |

ディレクトリ出力では、常にパディングされた名前（`0000`、`0001`、…）が使用されます。明示的なファイルパスでは、選択したステムが保持され、バッチが複数の出力を生成する場合に、パディングされたインデックスが追加されます。

`--push-to` を使用して、出力を[Hugging Face ストレージバケット](https://huggingface.co/docs/hub/en/storage-buckets)にアップロードします。以下を受け取ります:

- HF バケット ID(`<namespace>/<name>`)
- `hf://buckets/<namespace>/<name>[/<subpath>]`
[HF URI](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris)
- ブラウザのURL

サブパスはフォルダのプレフィックスとして使用されます。バケットが存在しない場合は作成され、オブジェクトは`[<subpath>/]<run_id>/<filename>`の下に配置されます。

```bash
# HF bucket id — files at hf://buckets/alice/edit-outputs/<run_id>/<file>
--push-to alice/edit-outputs

# URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07/<run_id>/<file>
--push-to hf://buckets/alice/edit-outputs/greyscale/2026-07

# Browser URL copy-paste from the Hub also works.
--push-to https://huggingface.co/buckets/alice/edit-outputs/tree/greyscale/2026-07
```

以下の表はリモート実行について説明しています。ローカル実行の場合、`--push-to` はローカルに保存された出力をアップロードします。ローカルファイルの作成を抑制することはありません。

| `--push-to` が設定されていますか？ | `--output` は設定されていますか? | 結果 |
|---|---|---|
| いいえ | いいえ | デフォルトのローカルディレクトリにダウンロード |
| いいえ | はい | `--output` にダウンロード |
| はい | いいえ | バケットのみ、ローカルへのダウンロードなし |
| はい | はい | bucket および `--output` |

`--format` は、stdout に出力されるメタデータ（パス、タイミング、サンドボックス情報）の形式を指定します。メディア自体のファイル形式は変更されません。書き出される画像は常に PNG、動画は MP4、音声は WAV です。

### リモート実行(`--remote`)

[Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox)内で同じ呼び出しを実行します。これはCLIがHTTP経由で操作する隔離されたクラウドVMであり、入力をアップロードしてパイプラインを実行し、出力をダウンロードした後にサンドボックスを終了します。`huggingface_hub>=1.23`が必要です。

サンドボックスは、torch、CUDA、および CLI の依存関係がすでに同梱された事前構築済みイメージである [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda) から起動します。そのため、コールドランではインストールを先に行うのではなく、生成処理から直接開始されます。

```bash
diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
    --remote --flavor a100-large
```

リモートフラグ:

- `--flavor <name>` — サンドボックスのハードウェア（例: `a10g-small`、`h200`、`rtx-pro-6000`）。
- `--timeout <duration>` — サンドボックス内で実行コマンドを実行する際の最大の実時間（デフォルトは `10m`）。
- `--dependencies <pkg>` — 追加の pip 依存関係（繰り返し指定可能）。イメージ上にインストールされます。diffusers のブランチの tarball を固定したり、パイプライン固有の追加要素を追加したりする場合に便利です。
- `--namespace <name>` — 別の HF 組織/アカウントの下にサンドボックスを作成します。
- `--image <ref>` — サンドボックスイメージを上書きします。`--flavor` のドライバと互換性のある torch + CUDA を同梱している必要があります。CLI は、デフォルトのイメージでは回避されるこの処理を、すべてのコールドサンドボックスに対して独自の依存関係をインストールするために実行します。
- `--volume <bucket-id>[:<mount-path>]` — [HF storage bucket](https://huggingface.co/docs/hub/en/storage-buckets)をサンドボックスに読み書き可能なディレクトリとしてマウントします（繰り返し指定可能）。デフォルトのマウントパスは`/mnt/buckets/<bucket-id>`です。マウントされたファイルは、他のローカルパスと同様に`--pipeline-kwargs`から参照できます。新規サンドボックスの作成時のみ適用され、`--sandbox-id`を介して再接続する場合は無視されます。

デフォルトでは、各 `--remote` 実行はエフェメラル（作成 → 実行 → ダウンロード → 終了）です。実行間でウォームなサンドボックスを再利用し、依存関係、モデル重みのキャッシュ、`torch.compile` キャッシュをディスク上に保持するには、サンドボックスを存続させ、再接続してください。

- `--keep-alive` — 実行後にサンドボックスを終了しません。その ID が出力されます。
- `--sandbox-id <id>` — 新規作成せずに、キープアライブ状態のサンドボックスに再接続します。
- `--idle-timeout <duration>` — この時間だけ無操作が続いた後に自動シャットダウンします（デフォルトは`10m`）。新しいサンドボックスの作成時のみ適用され、`--sandbox-id`を指定して再接続する場合は無視されます。

```bash
# First run keeps the sandbox alive and prints sandbox_id=<id>.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a cat"}' --remote --flavor a100-large --keep-alive

# Reconnect for the next run — the model is already cached, so only inference runs.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a dog"}' --remote --flavor a100-large --sandbox-id <id>

# Stop it when done (or let it timeout).
hf sandbox kill <id>
```

## `custom_blocks`

ローカルの`ModularPipelineBlocks`サブクラスを、Hubへのアップロード用にパッケージ化します。Pythonファイルを読み取り、ASTスキャンによって`ModularPipelineBlocks`またはその複合サブクラス（`SequentialPipelineBlocks`、`AutoPipelineBlocks`、`ConditionalPipelineBlocks`、`LoopSequentialPipelineBlocks`）を継承するクラスを検索し、選択されたクラスをインスタンス化して、現在の作業ディレクトリで`save_pretrained`を呼び出します。

```bash
# Package the first block found in ./block.py
diffusers-cli custom_blocks

# Point at a different file / pick a specific class
diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock
```

ブロッククラスは、コンストラクタ引数をゼロ個でインスタンス化可能である必要があります。デフォルト値は`__init__`内でハードコードするか、呼び出し時にパイプラインの`state`から設定を読み込むかのいずれかです。

## `fp16_safetensors`

> [!CAUTION]
> このコマンドは非推奨となり、将来のバージョンで削除されます。

Hub上のチェックポイントを`.safetensors`形式のfp16に変換し、結果をプッシュします。リポジトリの重みのサイズを縮小して読み込みを高速化する場合に便利です。正確な引数については`diffusers-cli fp16_safetensors --help`を参照してください。

## `skills`

diffusers リポジトリからスキルをインストールします([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills))。

```bash
# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills with a one-line summary of each
diffusers-cli skills list

# Preview a skill's SKILL.md without installing
diffusers-cli skills preview diffusers-cli

# Refetch and reinstall every managed skill
diffusers-cli skills update

# Install to the user-level directory instead of the current project
diffusers-cli skills add diffusers-cli --global

# Install for one agent instead of detecting it from the environment
diffusers-cli skills add --all --claude   # or --codex / --cursor
```

ターゲットフラグを指定しない場合、CLIは起動元のエージェントに対して、または特定できない場合はすべてのエージェントに対してインストールを行います。Claude Codeには`.claude/skills/diffusers/`の下にプラグインバンドルが配置され（`/diffusers:<skill name>`として名前空間化されます）、CodexとCursorには`.agents/skills/<skill name>/`が配置されます。