# 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

```sh
# 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`](../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`.

```sh
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:

```sh
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.