ImaGen/docs/usage.md

Using imagen

Subcommands

imagen generate <prompt> [flags]    generate one image
imagen backends                     list configured + registered backends
imagen config init                  print a sample imagen.yaml on stdout
imagen config validate              parse + validate the active config
imagen config path                  print the resolved config path
imagen serve [--addr :8080]         (stub) start the HTTP server
imagen version                      print version

generate flags

Flag	Default	Notes
--backend	default_backend from config	Instance name from imagen.yaml
--size	1024x1024	WxH
--seed	0 (= backend default)
--steps	0 (= backend default)
--style	empty	One of imagen config init's style names
--negative	empty	Negative prompt (ignored by some adapters)
--output	empty (= use naming template)	Explicit path
--no-sidecar	false	Skip the JSON sidecar even if config enables it
--preview	(auto)	Force open a tmux preview window via tmux-img
--no-preview	(auto)	Suppress the preview window (use for batch / CI callers)
--no-cloud	false	Skip Supabase upload + imagen.images insert for this call
--config	~/.config/imagen.yaml	Override config path

Preview window

After a successful generate, imagen optionally opens a sibling tmux window named img:<slug> running tmux-img --hold <path>. The new window is spawned in the background (tmux new-window -d) so the generating pane keeps focus and its terminal output.

Resolution order is config → $IMAGEN_PREVIEW → flag (later wins):

• output.preview in imagen.yaml: auto (default) | on | off
• IMAGEN_PREVIEW=auto|on|off overrides config
• --preview / --no-preview override env

auto previews iff stdout is a TTY and $TMUX is set. on previews unconditionally and errors outside a tmux session. off never previews.

Preview failures are non-fatal — the image already wrote.

Examples

# Quick smoke test — mock backend ships in-tree
imagen generate "test" --backend mock --output /tmp/x.png

# Real generation, FLUX-schnell on mRock via ComfyUI
imagen generate "a wide editorial blog header about RAG systems" \
  --backend flux-schnell-local \
  --style blog-header \
  --size 1536x768

# Explicit seed for reproducibility
imagen generate "a cat in a fishbowl" --backend mock --seed 42 --output /tmp/cat.png

Config

A complete sample is in imagen config init. Adapters get only their own sub-block — see ../CLAUDE.md for the contract.

Naming template

output.naming placeholders:

Placeholder	Replaced with
{date}	2026-05-08
{time}	143015 (no separators)
{slug}	lowercased ASCII prompt, ≤ 40 chars
{seed}	seed actually used
{backend}	backend instance name
{ext}	file extension matching Result.MimeType

Unknown placeholders are left literal.

Credentials

API-backed adapters read tokens from env vars referenced by the config (api_token_env, api_key_env). Never put a token in imagen.yaml.

export REPLICATE_API_TOKEN=...
imagen generate "a cat" --backend flux-dev-replicate

Cost-tracking (Replicate)

Successful generations through the Replicate adapter write one row to mai.imagen_usage on Supabase: backend, model, latency, per-image cost estimate, prompt sha256 hash (never the prompt itself), and the caller identity (resolved from MAI_FROM_ID or the tmux pane's @mai-name).

The writer is best-effort. If SUPABASE_URL / SUPABASE_SERVICE_KEY are unset, or the database write fails, the image still lands and the CLI prints a warning to stderr.

Inspect spend:

imagen usage                       # all rows, grouped by week + backend + model + caller
imagen usage --since 2026-05-01    # only rows on/after a UTC date
imagen usage --since 2026-05-01 --raw

Per-model rates live in internal/backend/replicate_pricing.go — they are snapshotted from https://replicate.com/pricing and refreshed on a quarterly cadence.

Cloud-sync (Supabase)

Successful generations also upload the PNG to the private Supabase Storage bucket imagen-generated (path: <YYYY-MM-DD>/<slug>-<seed>.png) and insert a row into imagen.images. The row carries the prompt, sha256-hashed prompt, backend, model, seed/steps/width/height, latency, cost estimate, the full local sidecar JSON, and an empty tags array ready for the flexsiebels viewer to fill in.

Configuration:

• owner_user_id in imagen.yaml — m's auth.users.id. Empty disables inserts (the column is NOT NULL).
• output.cloud_sync in imagen.yaml: auto (default — on iff SUPABASE creds + owner_user_id are set), on (errors if either is missing), off.
• IMAGEN_CLOUD_SYNC=auto|on|off overrides config.
• --no-cloud overrides everything for one call.

Reuses the same Supabase env (SUPABASE_URL + SUPABASE_SERVICE_KEY or MAI_SUPABASE_KEY) as cost-tracking. Service-role bypasses RLS for inserts; the owner_user_id = auth.uid() policy on the table gates the read path the flexsiebels viewer hits.

Failures (Storage 5xx, DB unreachable) emit imagen: cloud sync: <err> to stderr and the local PNG + sidecar stay put. Exit code is unchanged.