diffusion-cli

Standalone Python CLI for local diffusion model inference.

The CLI supports the existing Z-Image backend and local Krea 2 Turbo profiles. It never imports ComfyUI or downloads model 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.

Named model profiles

The legacy [models] table remains supported and is treated as an implicit legacy Z-Image profile. Named profiles can coexist:

default_model = "krea2-turbo"

[model_profiles.krea2-turbo]
architecture = "krea2"
variant = "turbo"
diffusion_model = "/models/krea2/krea2_turbo_fp8_scaled.safetensors"
text_encoder = "/models/krea2/qwen3vl_4b_fp8_scaled.safetensors"
vae = "/models/krea2/qwen_image_vae.safetensors"
tokenizer = "/home/mw/programs/ComfyUI/comfy/text_encoders/qwen25_tokenizer"

[model_profiles.z-image-turbo]
architecture = "z-image"
variant = "turbo"
diffusion_model = "/models/z-image/diffusion.safetensors"
text_encoder = "/models/z-image/qwen_3_4b.safetensors"
vae = "/models/z-image/ae.safetensors"
tokenizer = "/models/qwen25_tokenizer"

Select a profile for one-shot generation with --model-profile krea2-turbo. Krea 2 Turbo uses eight steps, CFG zero, and timestep shift mu = 1.15 by default. Raw profiles use 52 steps and CFG 3.5. All model and tokenizer paths must be local regular files/directories; missing paths fail without checking a Hub cache. HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE, and DIFFUSERS_OFFLINE are also enabled at process startup.

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.