imagine 🎨

Type a prompt, get a PNG. From your terminal, on your own GPU. Cancel the image-generation subscription. imagine is a tiny CLI front-end for ComfyUI: you stay in the shell, it drives the graph.

imagine "a tiny astronaut cat, studio photo"
imagine "neon tokyo alley at night" --steps 30 --size 1216x832
imagine "minimal logo, single line" --model juggernautXL_v9.safetensors --out ./logos

Each run injects your prompt/seed/size into a standard text-to-image graph (checkpoint → KSampler → VAE decode), queues it on ComfyUI, waits, and drops the PNG into ./imagine-out/.

---

Requirements

imagine needs a running ComfyUI with at least one checkpoint. Don't have one? These get you there fast (and they're free too):

• z-image-turbo-comfy: one-command ComfyUI with a fast turbo model.
• ai-workstation: the full local AI rig setup.

Then imagine only needs Python 3 (standard library, no pip install).

Quick start

git clone https://github.com/CastilloworksAi/imagine.git
cd imagine
./setup.sh                              # link `imagine`, check ComfyUI
imagine --check                         # confirm the server + list your models
imagine "a tiny astronaut cat, studio photo"

If your ComfyUI runs somewhere other than the default:

COMFY_URL=http://127.0.0.1:8000 imagine "..."

Usage

Flag	Default	Meaning
--model	juggernautXL_v9.safetensors	checkpoint to use (--check lists yours)
--steps	25	sampler steps
--seed	random	reproduce a result by reusing its seed
--size	1024x1024	WIDTHxHEIGHT
--negative	sensible default	what to avoid
--out	./imagine-out	where PNGs land
--dry-run	-	print the exact graph, queue nothing
--check	-	verify ComfyUI is reachable + list checkpoints

See exactly what it'll run

imagine "a fox" --dry-run

Prints the full ComfyUI API graph (great for learning the node format, or adapting the template in workflow_api.json).

How it works

imagine "a fox"  ──►  build graph from workflow_api.json (inject prompt/seed/size)
                 ──►  POST /prompt        (queue it on ComfyUI)
                 ──►  poll /history/<id>  (wait for completion)
                 ──►  GET  /view          (download the PNG -> ./imagine-out/)

The graph lives in workflow_api.json in ComfyUI's API format. Swap in your own graph (LoRAs, refiners, upscalers) and imagine will keep injecting the prompt into node 6 and params into nodes 3/4/5.

Development

bash tests/test.sh

No GPU, no ComfyUI, no model needed: the suite checks syntax, that the workflow template is valid and complete, and that --dry-run injects your prompt/params into a correct ComfyUI API graph. CI also runs shellcheck.

Actual image generation runs on your GPU through ComfyUI, so it can't run on a GPU-less CI box. imagine --check then a real prompt confirms it live.

License

MIT. See LICENSE.