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.

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

Model paths and stable generation defaults can be configured in:

~/.config/diffusion.toml

Example:

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

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:

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:

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:

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.