Kappmaker Image

KAppMaker — Image

Before running any command

1. Prerequisites — kappmaker --version (install: npm i -g kappmaker). If a credential is missing the CLI says so; re-run kappmaker config init.
2. Read AiGuidelines/ first — the PRD, positioning and UI spec already answer most questions.

generate-image — Generic AI Image Generator

Syntax: kappmaker generate-image --spec <spec.json> [options] (preferred) or kappmaker generate-image --prompt <text> [options] (quick one-liners only)

Default to a JSON spec, not a prose prompt. Structured JSON steers nano-banana-2 noticeably better than free text: it pins down composition, palette, lighting and hard constraints separately instead of hoping the model untangles them from a sentence — the result is far more accurate and repeatable. Reserve bare --prompt for genuinely trivial requests ("a red heart icon"); for anything with brand, layout or mood requirements, author a spec:

1. kappmaker spec-template image --output Assets/image-spec.json — canonical skeleton; its _instructions key explains each field and is auto-stripped before generation.
2. Fill it from AiGuidelines/ and the user's request: subject, purpose, composition (mention intended aspect ratio framing), style, color_palette (2–4 values, use brand colors), lighting, mood, background, constraints (hard rules — e.g. "no text", "transparent-look background", "leave top third empty for overlay"). Delete fields that don't apply. The skeleton is a baseline — restructure or enrich it freely when that captures the request better.
3. Run kappmaker generate-image --spec Assets/image-spec.json [--aspect-ratio ...] [--output ...].
4. Iterating on feedback = edit one or two spec fields and re-run — much more controllable than rewriting a prose prompt.

If the user hands you a predefined spec JSON, pass it through as-is.

Options:

• --spec <path> — Pre-authored JSON spec used verbatim as the structured prompt (preferred, see above)
• --prompt <text> — Free-text description (required unless --spec; quick one-liners only)
• --output <path> — Output file or directory (default: Assets/generated.png)
• --num-images <n> — Number of images, 1–8 (default: 1)
• --aspect-ratio <ratio> — 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 9:21, auto (default: 1:1)
• --resolution <res> — 1K, 2K, 4K (default: 2K)
• --output-format <fmt> — png, jpg, webp (default: png)
• --reference <paths...> — Reference inputs; switches to fal.ai's nano-banana-2/edit endpoint. Each entry can be a file path, a directory (all .png/.jpg/.jpeg/.webp inside are auto-picked, sorted, non-recursive), or an HTTP(S) URL. Capped at 10 references total.

Prerequisites: falApiKey (prompted on first use if not set). imgbbApiKey is optional but recommended when using --reference with local files — if set, refs are uploaded to imgbb for reliable URLs; if not, they are sent inline as data URIs.

What it does: Thin wrapper around fal.ai's nano-banana-2 (text-to-image) or nano-banana-2/edit (if any reference images are supplied). Submits the request, polls until complete, and downloads the result(s).

Output path rules:

• No --output → defaults to Assets/generated.png (or generated_1.png, _2.png… for multi)
• --output without a file extension → treated as a directory
• --output with a file extension → used verbatim for single image; for multi, _1, _2, … are appended before the extension

When to use this vs create-logo: Use create-logo when the user specifically wants an app logo (grid selection, background removal flow). Use generate-image for one-off marketing images, hero shots, backgrounds, illustrations, mockups, or any other general-purpose image task.

Where this sits in the flow

• Before this: —
• After this: kappmaker-image-tools if the result needs cropping, background removal or WebP.