imageCLI

What it is

Running image generation locally means no API costs, no rate limits, and full control over prompts and outputs. But wiring up HuggingFace Diffusers — quantization, VRAM budgeting, preflight checks, freeing memory after — is the same boilerplate every time. imageCLI wraps all of it into one command. Give it a text prompt or a Markdown file and get an image; swap the backend with -e; batch a whole directory; or import it as a Python library.

It is the pixels sibling to voiceCLI's speech and llmCLI's tokens — local-first, GPU-resident, the same operational shape.

One command, every engine

A small fleet of backends, each tuned for a different trade-off between speed, VRAM, and fidelity — and each just a value of -e. PuLID variants add face-identity lock from a reference image.

NVFP4 variants target Blackwell cards for an extra speed step. The full matrix — nine engines with steps, speed, and quantization notes — lives in the repo README.

How a prompt becomes an image

A prompt — plain text or a .md file with frontmatter — is dispatched to the chosen engine. The engine lazy-loads its model on the first call, runs preflight VRAM and RAM checks, generates, saves the image, then frees the GPU. Nothing stays resident longer than it needs to.

• Dispatch — route the prompt (or each file in a batch) to its engine.
• Preflight — lazy-load the model, check VRAM/RAM before committing.
• Generate — run the diffusion steps at the configured resolution.
• Save & free — write the image out, release GPU memory.

imagecli batch applies the same flow to every prompt in a directory; imagecli info verifies the install and GPU detection before you spend a model download on it.

Cross-host over NATS

The GPU and the caller need not be the same machine. imageCLI ships a NATS satellite: the model loads once on a GPU server, and a request from anywhere on the bus returns a generated image — PUT to a cross-host blob store so a non-GPU box never touches the weights.

That is how imageCLI plugs into roxabi-factory: it registers as an image worker exposing image.generate, so any agent in the factory renders by publishing a request — the transport invisible to the model's reasoning loop.

Run it

Requirements: Python 3.12, a CUDA GPU (16 GB recommended; 10 GB for fp8 engines), and the uv package manager. Heavy engine deps are opt-in, so you install only what you use. Models download automatically on first use.

uv tool install .                      # install (cu128 index from pyproject)
imagecli info                          # verify install + GPU
imagecli generate "a cat in space"     # generate from anywhere
imagecli generate prompt.md -e flux1-dev
imagecli batch images/prompts_in/      # batch a directory

Engines, the dispatcher, and the NATS satellite are all in the open.

• The repo · github.com/Roxabi/imageCLI →