# diffusion-cli

Standalone Python CLI scaffolding for local Z-Image Turbo inference.

The first implemented milestone validates CLI inputs, resolves the local
model files, and inspects safetensors metadata without importing ComfyUI
or downloading files.

```bash
uv run diffusion-cli --help
uv run diffusion-cli --inspect-models
```

Model paths and stable generation defaults can be configured in:

```text
~/.config/diffusion.toml
```

Example:

```toml
[models]
diffusion_model = "/models/z-image/diffusion.safetensors"
text_encoder = "/models/z-image/qwen_3_4b.safetensors"
vae = "/models/z-image/ae.safetensors"
tokenizer = "/home/mw/programs/ComfyUI/comfy/text_encoders/qwen25_tokenizer"

[generation]
negative_prompt = "text, watermark, full-body"
width = 832
height = 1248
batch_size = 1
steps = 10
cfg = 1.0
output = "output.png"
output_extension = "png"
output_quality = 95
device = "cuda"
dtype = "auto"
```

Command line options override config values for the current run. Model
paths can also be passed with `--diffusion-model`, `--text-encoder`,
`--vae`, and `--tokenizer-path`.

```bash
uv run diffusion-cli --prompt "a ceramic mug" --steps 12
```

In this example, `--steps 12` overrides any `generation.steps` value in
the config file for that run only.

PNG is the default output format and does not require ImageMagick. To
write a smaller lossy or compressed format, request a final extension
and encoder quality:

```bash
uv run diffusion-cli \
    --prompt "a ceramic mug" \
    --output output.png \
    --output-extension jpg \
    --output-quality 85
```

This writes `output.jpg`; the configured output path still controls the
directory and base name. Supported extensions are `png`, `jpg`, `jpeg`,
`webp`, and `avif`. The `jpeg` alias is normalized to `jpg`.

Non-PNG output uses the `magick` executable from ImageMagick after image
generation completes. AVIF support depends on the local ImageMagick
build and installed delegates.

## HTTP API server

Start the SillyTavern compatibility API with an explicit profile:

```bash
uv run diffusion-cli serve \
    --api-profile sillytavern-sdcpp \
    --host 127.0.0.1 \
    --port 7860
```

Then point SillyTavern's stable-diffusion.cpp provider at:

```text
http://127.0.0.1:7860
```

The `sillytavern-sdcpp` profile implements the endpoint mix used by
SillyTavern's provider adapter. It is not the native stable-diffusion.cpp
server API. Generation still requires local model paths in
`~/.config/diffusion.toml`.