studio-lumiere-cli 0.1.6 → 0.1.7

package/README.md

@@ -1,532 +1,550 @@
-# Studio Lumiere CLI
-
-Local SDK + CLI for AI-powered jewelry product photography. Generate editorial-quality images, videos, and compositions from reference jewelry photos.
-
-```bash
-npx studio-lumiere-cli <command> [options]
-```
-
-## Setup
-
-1. Install dependencies
-
-```
-npm install
-```
-
-2. Create `.env`
-
-```
-GEMINI_API_KEY=your_key_here
-LUMIERE_OUTPUT_DIR=outputs
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| [`generate`](#generate) | Generate styled jewelry product images |
-| [`refine`](#refine) | Apply refinement instructions to an existing image |
-| [`upscale`](#upscale) | Upscale an image to higher resolution |
-| [`muse`](#muse) | Create a consistent character reference ("Muse") |
-| [`video`](#video) | Generate video from a text prompt |
-| [`tired-girl`](#tired-girl) | Generate "before" / casual aesthetic images |
-| [`annotate`](#annotate) | Overlay text on an image |
-| [`grid`](#grid) | Combine multiple images into a grid layout |
-| [`list`](#list) | List available templates, backgrounds, vibes, etc. |
-
----
-
-## generate
-
-Generate styled jewelry product images using AI.
-
-```bash
-lumiere generate --images <paths> --template <id> [options]
-```
-
-### Required
-
-| Flag | Description |
-|------|-------------|
-| `--images <paths>` | Comma-separated input image paths |
-| `--template <id>` | Template ID (see [Templates](#templates)) |
-
-### Customization
-
-| Flag | Description |
-|------|-------------|
-| `--detail <id>` | Primary customization (template-specific) |
-| `--secondary-detail <id>` | Secondary customization |
-| `--tertiary-detail <id>` | Tertiary customization |
-| `--ethnicity <id>` | Model ethnicity |
-| `--skin-tone <id>` | Model skin tone |
-| `--hair-color <id>` | Model hair color |
-| `--background <id>` | Background color/texture |
-| `--background-type <id>` | Background type (studio, interior, exterior, texture) |
-| `--vibe <id>` | Photography mood/style |
-| `--resolution <id>` | Output aspect ratio (default: `portrait`) |
-| `--occasion <id>` | Special occasion theme |
-
-### Generation
-
-| Flag | Description |
-|------|-------------|
-| `--quantity <n>` | Number of images to generate (default: `1`) |
-| `--muse-id <id>` | Muse ID for consistent model appearance |
-| `--muse-images <paths>` | Comma-separated Muse reference image paths |
-| `--no-enhance` | Skip LLM prompt enhancement |
-
-### Example
-
-```bash
-lumiere generate \
-  --images "ring.jpg" \
-  --template hand_model \
-  --detail nail_red \
-  --background velvet_black \
-  --vibe golden_hour \
-  --quantity 4
-```
-
----
-
-## refine
-
-Apply refinement instructions to an existing generated image.
-
-```bash
-lumiere refine --image <path> --instruction <text> [options]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--image <path>` | **(required)** Path to image to refine |
-| `--instruction <text>` | **(required)** Refinement instruction |
-| `--size <percent>` | Resize jewelry to given percentage (e.g. `80` = smaller, `120` = larger) |
-
-```bash
-lumiere refine --image "output.png" --instruction "make the background warmer"
-lumiere refine --image "output.png" --instruction "adjust jewelry" --size 80
-```
-
----
-
-## upscale
-
-Upscale an image to higher resolution.
-
-```bash
-lumiere upscale --image <path> [--scale <n>]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--image <path>` | **(required)** Path to image |
-| `--scale <n>` | Scale factor (default: `2`) |
-
----
-
-## muse
-
-Create a Muse (consistent character reference) from a source image. Used with the `half_body_muse` template for identity-consistent generations.
-
-```bash
-lumiere muse --name <name> --source <path> [--variations <n>]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--name <name>` | **(required)** Name for the Muse |
-| `--source <path>` | **(required)** Path to source image |
-| `--variations <n>` | Number of variations to generate (default: `3`) |
-
-```bash
-lumiere muse --name "Sarah" --source "reference.jpg"
-lumiere generate --images "necklace.jpg" --template half_body_muse --muse-id sarah
-```
-
----
-
-## video
-
-Generate a short video from a text prompt.
-
-```bash
-lumiere video --prompt <text> [options]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--prompt <text>` | **(required)** Video description |
-| `--aspect <ratio>` | Aspect ratio (`1:1`, `3:4`, `9:16`, `16:9`) |
-| `--duration <seconds>` | Duration in seconds |
-
-Video-enabled templates: `hand_model`, `neck_model`, `ear_model`, `flatlay_creative`, `floating_minimal`, `half_body_muse`.
-
----
-
-## tired-girl
-
-Generate "tired girl" / "before" aesthetic images showing a model in casual, un-styled looks (no jewelry).
-
-```bash
-lumiere tired-girl [options]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--muse-id <id>` | Muse ID for identity reference |
-| `--image <path>` | Single reference image (if no Muse) |
-| `--styles <ids>` | Comma-separated style IDs |
-| `--quantity <n>` | Number of images (default: `1`) |
-
-### Available styles
-
-| ID | Description |
-|----|-------------|
-| `tired` | Slightly tired, soft under-eye shadows, relaxed expression |
-| `morning` | Freshly awake, morning light, sleepy energy |
-| `no_makeup` | Completely bare faced |
-| `crazy_hair` | Messy, unstyled wild hair |
-| `pyjama` | Cozy pajamas or loungewear |
-
-```bash
-lumiere tired-girl --muse-id sarah --styles "tired,no_makeup" --quantity 2
-```
-
----
-
-## annotate
-
-Overlay text on an image with customizable styling.
-
-```bash
-lumiere annotate --input <path> --output <path> --text <text> [options]
-```
-
-### Required
-
-| Flag | Description |
-|------|-------------|
-| `--input <path>` | Input image path |
-| `--output <path>` | Output image path |
-| `--text <text>` | Text to overlay |
-
-### Text styling
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--font <name>` | `Poppins` | Font family |
-| `--size <px>` | auto | Font size in pixels |
-| `--weight <n>` | `700` | Font weight |
-| `--color <hex>` | `#FFFFFF` | Text color |
-| `--stroke-color <value>` | `rgba(0,0,0,0.6)` | Text outline color |
-| `--stroke-width <px>` | `fontSize * 0.08` | Text outline width |
-
-### Banner
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--banner` | off | Enable semi-transparent banner behind text |
-| `--banner-color <value>` | `rgba(0,0,0,0.45)` | Banner color |
-| `--banner-padding <px>` | `fontSize * 0.6` | Banner padding |
-| `--banner-radius <px>` | `fontSize * 0.4` | Banner corner radius |
-
-### Position
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--position <pos>` | `bottom-center` | One of: `top-center`, `top-left`, `top-right`, `bottom-center`, `bottom-center-high`, `bottom-left`, `bottom-right`, `center` |
-| `--padding <px>` | auto | Padding from edges |
-| `--max-width <ratio>` | auto | Max text width as ratio of image width (0-1) |
-
-```bash
-lumiere annotate \
-  --input "image.jpg" \
-  --output "branded.jpg" \
-  --text "New Collection" \
-  --position bottom-center \
-  --banner \
-  --size 48
-```
-
----
-
-## grid
-
-Combine multiple images into a grid layout.
-
-```bash
-lumiere grid --inputs <paths> --output <path> [options]
-```
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--inputs <paths>` | | **(required)** Comma-separated image paths |
-| `--output <path>` | | **(required)** Output image path |
-| `--columns <n>` | `2` | Number of columns |
-| `--rows <n>` | `2` | Number of rows |
-| `--padding <px>` | `20` | Padding between tiles |
-| `--background <hex>` | `#000000` | Background color |
-| `--tile-width <px>` | auto | Fixed tile width |
-| `--tile-height <px>` | auto | Fixed tile height |
-
-```bash
-lumiere grid \
-  --inputs "img1.jpg,img2.jpg,img3.jpg,img4.jpg" \
-  --output "grid.jpg" \
-  --columns 2 --rows 2 \
-  --padding 10 --background "#FFFFFF"
-```
-
----
-
-## list
-
-List available options for any category. Output is JSON.
-
-```bash
-lumiere list <type>
-```
-
-| Type | Description |
-|------|-------------|
-| `templates` | All templates with their customization options |
-| `ethnicities` | Model ethnicity options |
-| `skin-tones` | Skin tone options |
-| `hair-colors` | Hair color options |
-| `backgrounds` | Background color/texture options |
-| `background-types` | Background type options |
-| `vibes` | Photography mood options |
-| `resolutions` | Aspect ratio options |
-| `occasions` | Special occasion themes |
-
----
-
-## Templates
-
-### `hand_model` -- Hand Model
-
-Close-up of a model's hand, wrist, and forearm. Perfect for rings and bracelets.
-
-| Customization | Options |
-|---------------|---------|
-| **Nail Polish** (`--detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
-
----
-
-### `neck_model` -- Neckline Portrait
-
-Waist-up portrait focusing on the neck and collarbone. Ideal for necklaces and pendants.
-
-| Customization | Options |
-|---------------|---------|
-| **Wardrobe** (`--detail`) | `wear_skin` Bare Skin, `wear_silk` White Silk Shirt, `wear_black` Black Turtleneck, `wear_gown` Evening Gown, `wear_kaftan` Modern Kaftan |
-| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
-
----
-
-### `ear_model` -- Ear Detail
-
-Intimate side profile shot. Best for earrings.
-
-| Customization | Options |
-|---------------|---------|
-| **Hairstyle** (`--detail`) | `hair_tucked` Tucked Behind Ear, `hair_updo` Elegant Updo, `hair_waves` Loose Waves, `hair_sleek` Sleek & Straight |
-| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
-
----
-
-### `flatlay_creative` -- Creative Flatlay
-
-Artistic still-life composition on a surface. No model. Great for any jewelry type.
-
-| Customization | Options |
-|---------------|---------|
-| **Surface** (`--detail`) | `surf_marble` White Marble, `surf_stone` Dark Slate, `surf_velvet` Beige Velvet, `surf_wood` Aged Wood, `surf_sand` Fine Sand, `surf_pedestal` Geometric Pedestal, `surf_riser` Stone Riser |
-
----
-
-### `floating_minimal` -- Floating Minimalist
-
-Jewelry suspended in mid-air with dramatic lighting. No model.
-
-| Customization | Options |
-|---------------|---------|
-| **Lighting** (`--detail`) | `light_soft` Soft & Diffused, `light_hard` Hard Contrast, `light_warm` Golden Glow, `light_cool` Cool Steel |
-
----
-
-### `half_body_muse` -- The Editorial Muse
-
-Dynamic waist-up fashion shot. The only template that supports Muse (consistent model identity).
-
-| Customization | Options |
-|---------------|---------|
-| **Outfit** (`--detail`) | `outfit_blazer` Power Suit, `outfit_evening` Evening Glamour, `outfit_linen` Resort Linen, `outfit_knit` Cashmere Knit, `outfit_silk` Silk Shirt, `outfit_turtleneck` Turtleneck |
-| **Nail Polish** (`--secondary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
-| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
-| **Pose** (quaternary) | `pose_winking`, `pose_grimace`, `pose_teasing`, `pose_kiss`, `pose_laughing`, `pose_pout`, `pose_peace` |
-
----
-
-### `romance_proposal` -- Romance & Proposal
-
-Emotional engagement ring moments with a couple.
-
-| Customization | Options |
-|---------------|---------|
-| **Moment** (`--detail`) | `moment_proposal` The Proposal, `moment_said_yes` Just Said Yes, `moment_hand_in_hand` Hand in Hand, `moment_dinner` Intimate Dinner, `moment_promise` The Promise |
-| **Setting** (`--secondary-detail`) | `setting_garden` Garden, `setting_restaurant` Candlelit Restaurant, `setting_beach` Beach at Sunset, `setting_home` Cozy at Home, `setting_rooftop` Rooftop City Views, `setting_winter` Winter Snow |
-| **Nail Polish** (`--tertiary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
-
----
-
-### `museum_exhibit` -- Museum Exhibit
-
-Jewelry displayed as a priceless museum artifact. No model.
-
-| Customization | Options |
-|---------------|---------|
-| **Museum Style** (`--detail`) | `museum_classical` Classical Gallery, `museum_modern` Modern Art Museum, `museum_baroque` Baroque Palace, `museum_art_deco` Art Deco Gallery |
-| **Display Type** (`--secondary-detail`) | `display_vitrine` Glass Vitrine, `display_pedestal` Velvet Pedestal, `display_stand` Open Display, `display_wall` Wall Mount, `display_alcove` Illuminated Alcove |
-
----
-
-### `romantic_mood` -- Romantic Mood
-
-Jewelry styled as a romantic still life with props. No model.
-
-| Customization | Options |
-|---------------|---------|
-| **Props** (`--detail`) | `prop_rose_petals` Rose Petals, `prop_candles` Candlelight, `prop_love_letter` Love Letter, `prop_silk_lace` Silk & Lace, `prop_fresh_roses` Fresh Roses, `prop_gift_box` The Gift |
-| **Mood** (`--secondary-detail`) | `mood_candlelight` Warm Candlelight, `mood_morning` Soft Morning Light, `mood_moody` Moody & Dark, `mood_golden` Golden Hour Glow, `mood_blush` Blush Pink Haze |
-
----
-
-## Global Options
-
-### Ethnicities (`--ethnicity`)
-
-| ID | Name |
-|----|------|
-| `european` | European |
-| `moroccan` | Moroccan |
-| `middle_east` | Middle Eastern |
-| `african` | African |
-| `asian` | East Asian |
-
-### Skin Tones (`--skin-tone`)
-
-| ID | Name |
-|----|------|
-| `fair` | Porcelain |
-| `light` | Light |
-| `medium` | Tan |
-| `deep` | Deep |
-| `dark` | Ebony |
-
-### Hair Colors (`--hair-color`)
-
-| ID | Name |
-|----|------|
-| `dark` | Dark / Black |
-| `brunette` | Brunette |
-| `blonde` | Blonde |
-| `red` | Red / Auburn |
-| `grey` | Silver / Grey |
-
-### Backgrounds (`--background`)
-
-| ID | Name |
-|----|------|
-| `silk_cream` | Cream Silk |
-| `velvet_black` | Midnight Velvet |
-| `marble_white` | Carrara Marble |
-| `emerald_velvet` | Emerald Velvet |
-| `studio_grey` | Studio Grey |
-| `warm_beige` | Warm Beige |
-| `burgundy_velvet` | Burgundy Velvet |
-| `champagne_gold` | Champagne Gold |
-| `navy_sapphire` | Navy Sapphire |
-| `blush_rose` | Blush Rose |
-| `ivory_pearl` | Ivory Pearl |
-| `slate_charcoal` | Slate Charcoal |
-
-### Background Types (`--background-type`)
-
-| ID | Name |
-|----|------|
-| `studio` | Studio Flat |
-| `interior` | Luxury Interior |
-| `exterior` | Outdoors |
-| `texture` | Macro Texture |
-
-### Vibes (`--vibe`)
-
-| ID | Name |
-|----|------|
-| `golden_hour` | Golden Hour -- warm natural sunlight |
-| `moody_chic` | Moody Chic -- dramatic shadows, high contrast |
-| `clean_minimal` | Clean Minimal -- bright, airy, minimalist |
-| `romantic_soft` | Romantic -- soft focus, pastel tones |
-
-### Resolutions (`--resolution`)
-
-| ID | Aspect Ratio | Best for |
-|----|-------------|----------|
-| `square` | 1:1 | Instagram Feed |
-| `portrait` | 3:4 | Instagram Feed (vertical) |
-| `story` | 9:16 | Instagram Stories / Reels |
-| `landscape` | 16:9 | Website / Ads |
-
-### Occasions (`--occasion`)
-
-Occasions auto-configure vibe, background, and background type, and inject thematic prompt details.
-
-| ID | Name |
-|----|------|
-| `moroccan_wedding` | Moroccan Wedding |
-| `eid_fitr` | Eid al-Fitr |
-| `eid_adha` | Eid al-Adha |
-| `henna_night` | Henna Night |
-| `ramadan` | Ramadan |
-| `valentines` | Valentine's Day |
-| `mothers_day` | Mother's Day |
-| `birthday` | Birthday |
-| `anniversary` | Anniversary |
-| `graduation` | Graduation |
-| `christmas` | Christmas |
-| `new_year` | New Year |
-
----
-
-## SDK Usage
-
-```ts
-import { generateImages } from "studio-lumiere-cli";
-
-const result = await generateImages(
-  { apiKey: "your-key", outputDir: "outputs" },
-  {
-    inputImages: ["./ring.jpg"],
-    quantity: 4,
-    selections: {
-      templateId: "hand_model",
-      detailId: "nail_red",
-      backgroundId: "velvet_black",
-      vibeId: "golden_hour",
-      resolutionId: "portrait",
-    },
-  }
-);
-```
-
-## Notes
-
-- Templates, backgrounds, vibes, and all shared options are synced from the main Studio Lumiere web app at build time (`npm run sync`). The CLI always matches the web app.
-- The Muse flow generates variations and stores a local `muses.json` index under your output directory.
-- Video generation uses Veo via the Gemini SDK and returns an operation name plus the video file when available.
+# Studio Lumiere CLI
+
+Local SDK + CLI for AI-powered jewelry product photography. Generate editorial-quality images, videos, and compositions from reference jewelry photos.
+
+```bash
+npx studio-lumiere-cli <command> [options]
+```
+
+## Setup
+
+1. Install dependencies
+
+```
+npm install
+```
+
+2. Create `.env`
+
+```
+GEMINI_API_KEY=your_key_here
+LUMIERE_OUTPUT_DIR=outputs
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| [`generate`](#generate) | Generate styled jewelry product images |
+| [`refine`](#refine) | Apply refinement instructions to an existing image |
+| [`upscale`](#upscale) | Upscale an image to higher resolution |
+| [`muse`](#muse) | Create a consistent character reference ("Muse") |
+| [`video`](#video) | Generate video from a text prompt |
+| [`tired-girl`](#tired-girl) | Generate "before" / casual aesthetic images |
+| [`annotate`](#annotate) | Overlay text on an image |
+| [`grid`](#grid) | Combine multiple images into a grid layout |
+| [`list`](#list) | List available templates, backgrounds, vibes, etc. |
+
+---
+
+## generate
+
+Generate styled jewelry product images using AI.
+
+```bash
+lumiere generate --images <paths> --template <id> [options]
+```
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--images <paths>` | Comma-separated input image paths |
+| `--template <id>` | Template ID (see [Templates](#templates)) |
+
+### Customization
+
+| Flag | Description |
+|------|-------------|
+| `--detail <id>` | Primary customization (template-specific) |
+| `--secondary-detail <id>` | Secondary customization |
+| `--tertiary-detail <id>` | Tertiary customization |
+| `--quaternary-detail <id>` | Quaternary customization |
+| `--quinary-detail <id>` | Quinary customization |
+| `--ethnicity <id>` | Model ethnicity |
+| `--skin-tone <id>` | Model skin tone |
+| `--hair-color <id>` | Model hair color |
+| `--background <id>` | Background color/texture |
+| `--background-type <id>` | Background type (studio, interior, exterior, texture) |
+| `--vibe <id>` | Photography mood/style |
+| `--photography-style <id>` | Overall photography style |
+| `--resolution <id>` | Output aspect ratio (default: `portrait`) |
+| `--occasion <id>` | Special occasion theme |
+
+### Generation
+
+| Flag | Description |
+|------|-------------|
+| `--quantity <n>` | Number of images to generate (default: `1`) |
+| `--muse-id <id>` | Muse ID for consistent model appearance |
+| `--muse-images <paths>` | Comma-separated Muse reference image paths |
+| `--no-enhance` | Skip LLM prompt enhancement |
+
+### Example
+
+```bash
+lumiere generate \
+  --images "ring.jpg" \
+  --template hand_model \
+  --detail nail_red \
+  --background velvet_black \
+  --vibe golden_hour \
+  --quantity 4
+```
+
+---
+
+## refine
+
+Apply refinement instructions to an existing generated image.
+
+```bash
+lumiere refine --image <path> --instruction <text> [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--image <path>` | **(required)** Path to image to refine |
+| `--instruction <text>` | **(required)** Refinement instruction |
+| `--size <percent>` | Resize jewelry to given percentage (e.g. `80` = smaller, `120` = larger) |
+
+```bash
+lumiere refine --image "output.png" --instruction "make the background warmer"
+lumiere refine --image "output.png" --instruction "adjust jewelry" --size 80
+```
+
+---
+
+## upscale
+
+Upscale an image to higher resolution.
+
+```bash
+lumiere upscale --image <path> [--scale <n>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--image <path>` | **(required)** Path to image |
+| `--scale <n>` | Scale factor (default: `2`) |
+
+---
+
+## muse
+
+Create a Muse (consistent character reference) from a source image. Used with the `half_body_muse` template for identity-consistent generations.
+
+```bash
+lumiere muse --name <name> --source <path> [--variations <n>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | **(required)** Name for the Muse |
+| `--source <path>` | **(required)** Path to source image |
+| `--variations <n>` | Number of variations to generate (default: `3`) |
+
+```bash
+lumiere muse --name "Sarah" --source "reference.jpg"
+lumiere generate --images "necklace.jpg" --template half_body_muse --muse-id sarah
+```
+
+---
+
+## video
+
+Generate a short video from a text prompt.
+
+```bash
+lumiere video --prompt <text> [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--prompt <text>` | **(required)** Video description |
+| `--aspect <ratio>` | Aspect ratio (`1:1`, `3:4`, `9:16`, `16:9`) |
+| `--duration <seconds>` | Duration in seconds |
+
+Video-enabled templates: `hand_model`, `neck_model`, `ear_model`, `flatlay_creative`, `floating_minimal`, `half_body_muse`.
+
+---
+
+## tired-girl
+
+Generate "tired girl" / "before" aesthetic images showing a model in casual, un-styled looks (no jewelry).
+
+```bash
+lumiere tired-girl [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--muse-id <id>` | Muse ID for identity reference |
+| `--image <path>` | Single reference image (if no Muse) |
+| `--styles <ids>` | Comma-separated style IDs |
+| `--quantity <n>` | Number of images (default: `1`) |
+
+### Available styles
+
+| ID | Description |
+|----|-------------|
+| `tired` | Slightly tired, soft under-eye shadows, relaxed expression |
+| `morning` | Freshly awake, morning light, sleepy energy |
+| `no_makeup` | Completely bare faced |
+| `crazy_hair` | Messy, unstyled wild hair |
+| `pyjama` | Cozy pajamas or loungewear |
+
+```bash
+lumiere tired-girl --muse-id sarah --styles "tired,no_makeup" --quantity 2
+```
+
+---
+
+## annotate
+
+Overlay text on an image with customizable styling.
+
+```bash
+lumiere annotate --input <path> --output <path> --text <text> [options]
+```
+
+### Required
+
+| Flag | Description |
+|------|-------------|
+| `--input <path>` | Input image path |
+| `--output <path>` | Output image path |
+| `--text <text>` | Text to overlay |
+
+### Text styling
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--font <name>` | `Poppins` | Font family |
+| `--size <px>` | auto | Font size in pixels |
+| `--weight <n>` | `700` | Font weight |
+| `--color <hex>` | `#FFFFFF` | Text color |
+| `--stroke-color <value>` | `rgba(0,0,0,0.6)` | Text outline color |
+| `--stroke-width <px>` | `fontSize * 0.08` | Text outline width |
+
+### Banner
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--banner` | off | Enable semi-transparent banner behind text |
+| `--banner-color <value>` | `rgba(0,0,0,0.45)` | Banner color |
+| `--banner-padding <px>` | `fontSize * 0.6` | Banner padding |
+| `--banner-radius <px>` | `fontSize * 0.4` | Banner corner radius |
+
+### Position
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--position <pos>` | `bottom-center` | One of: `top-center`, `top-left`, `top-right`, `bottom-center`, `bottom-center-high`, `bottom-left`, `bottom-right`, `center` |
+| `--padding <px>` | auto | Padding from edges |
+| `--max-width <ratio>` | auto | Max text width as ratio of image width (0-1) |
+
+```bash
+lumiere annotate \
+  --input "image.jpg" \
+  --output "branded.jpg" \
+  --text "New Collection" \
+  --position bottom-center \
+  --banner \
+  --size 48
+```
+
+---
+
+## grid
+
+Combine multiple images into a grid layout.
+
+```bash
+lumiere grid --inputs <paths> --output <path> [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--inputs <paths>` | | **(required)** Comma-separated image paths |
+| `--output <path>` | | **(required)** Output image path |
+| `--columns <n>` | `2` | Number of columns |
+| `--rows <n>` | `2` | Number of rows |
+| `--padding <px>` | `20` | Padding between tiles |
+| `--background <hex>` | `#000000` | Background color |
+| `--tile-width <px>` | auto | Fixed tile width |
+| `--tile-height <px>` | auto | Fixed tile height |
+
+```bash
+lumiere grid \
+  --inputs "img1.jpg,img2.jpg,img3.jpg,img4.jpg" \
+  --output "grid.jpg" \
+  --columns 2 --rows 2 \
+  --padding 10 --background "#FFFFFF"
+```
+
+---
+
+## list
+
+List available options for any category. Output is JSON.
+
+```bash
+lumiere list <type>
+```
+
+| Type | Description |
+|------|-------------|
+| `templates` | All templates with their customization options |
+| `ethnicities` | Model ethnicity options |
+| `skin-tones` | Skin tone options |
+| `hair-colors` | Hair color options |
+| `backgrounds` | Background color/texture options |
+| `background-types` | Background type options |
+| `vibes` | Photography mood options |
+| `photography-styles` | Overall photography style options |
+| `resolutions` | Aspect ratio options |
+| `occasions` | Special occasion themes |
+
+---
+
+## Templates
+
+### `hand_model` -- Hand Model
+
+Close-up of a model's hand, wrist, and forearm. Perfect for rings and bracelets.
+
+| Customization | Options |
+|---------------|---------|
+| **Nail Polish** (`--detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+
+---
+
+### `neck_model` -- Neckline Portrait
+
+Waist-up portrait focusing on the neck and collarbone. Ideal for necklaces and pendants.
+
+| Customization | Options |
+|---------------|---------|
+| **Wardrobe** (`--detail`) | `wear_skin` Bare Skin, `wear_silk` White Silk Shirt, `wear_black` Black Turtleneck, `wear_gown` Evening Gown, `wear_kaftan` Modern Kaftan |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+
+---
+
+### `ear_model` -- Ear Detail
+
+Intimate side profile shot. Best for earrings.
+
+| Customization | Options |
+|---------------|---------|
+| **Hairstyle** (`--detail`) | `hair_tucked` Tucked Behind Ear, `hair_updo` Elegant Updo, `hair_waves` Loose Waves, `hair_sleek` Sleek & Straight |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+
+---
+
+### `flatlay_creative` -- Creative Flatlay
+
+Artistic still-life composition on a surface. No model. Great for any jewelry type.
+
+| Customization | Options |
+|---------------|---------|
+| **Surface** (`--detail`) | `surf_marble` White Marble, `surf_stone` Dark Slate, `surf_velvet` Beige Velvet, `surf_wood` Aged Wood, `surf_sand` Fine Sand, `surf_travertine` Travertine, `surf_obsidian` Black Obsidian, `surf_mirrored` Mirrored Glass, `surf_brushed_metal` Brushed Metal, `surf_frosted_acrylic` Frosted Acrylic, `surf_pedestal` Geometric Pedestal, `surf_riser` Stone Riser |
+
+---
+
+### `floating_minimal` -- Floating Minimalist
+
+Jewelry suspended in mid-air with dramatic lighting. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Lighting** (`--detail`) | `light_soft` Soft & Diffused, `light_hard` Hard Contrast, `light_warm` Golden Glow, `light_cool` Cool Steel |
+
+---
+
+### `half_body_muse` -- The Editorial Muse
+
+Dynamic waist-up fashion shot. The only template that supports Muse (consistent model identity).
+
+| Customization | Options |
+|---------------|---------|
+| **Outfit** (`--detail`) | `outfit_director_choice` Creative Director's Choice, `outfit_blazer` Power Suit (Blazer), `outfit_tailored_jumpsuit` Tailored Jumpsuit, `outfit_evening` Evening Glamour, `outfit_leather_jacket` Leather Jacket, `outfit_linen` Resort Linen, `outfit_knit` Cashmere Knit, `outfit_silk` Silk Shirt, `outfit_turtleneck` Turtleneck, `outfit_tailored_trench` Tailored Trench |
+| **Nail Polish** (`--secondary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+| **Makeup** (`--tertiary-detail`) | `makeup_none` Bare, `makeup_minimal` Minimal, `makeup_soft` Soft Glam, `makeup_full` Full Glam, `makeup_editorial` Editorial |
+| **Pose** (`--quaternary-detail`) | `pose_winking`, `pose_grimace`, `pose_teasing`, `pose_kiss`, `pose_laughing`, `pose_pout`, `pose_power_tilt`, `pose_hand_ear`, `pose_profile`, `pose_over_shoulder`, `pose_peace` |
+| **Accessories & Styling** (`--quinary-detail`) | `accessory_sunglasses`, `accessory_silk_scarf`, `accessory_silk_headband`, `accessory_sheer_gloves`, `accessory_statement_belt`, `accessory_silk_bandana`, `accessory_silk_tie`, `accessory_hair_clip`, `accessory_beret`, `accessory_wide_brim_hat`, `accessory_leather_gloves` |
+
+
+---
+
+### `romance_proposal` -- Romance & Proposal
+
+Emotional engagement ring moments with a couple.
+
+| Customization | Options |
+|---------------|---------|
+| **Moment** (`--detail`) | `moment_proposal` The Proposal, `moment_said_yes` Just Said Yes, `moment_hand_in_hand` Hand in Hand, `moment_dinner` Intimate Dinner, `moment_promise` The Promise |
+| **Setting** (`--secondary-detail`) | `setting_garden` Garden, `setting_restaurant` Candlelit Restaurant, `setting_beach` Beach at Sunset, `setting_home` Cozy at Home, `setting_rooftop` Rooftop City Views, `setting_winter` Winter Snow |
+| **Nail Polish** (`--tertiary-detail`) | `nail_nude` Soft Nude, `nail_red` Classic Red, `nail_french` French Manicure, `nail_natural` Natural & Clean, `nail_dark` Noir / Dark |
+
+---
+
+### `museum_exhibit` -- Museum Exhibit
+
+Jewelry displayed as a priceless museum artifact. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Museum Style** (`--detail`) | `museum_classical` Classical Gallery, `museum_modern` Modern Art Museum, `museum_baroque` Baroque Palace, `museum_art_deco` Art Deco Gallery |
+| **Display Type** (`--secondary-detail`) | `display_vitrine` Glass Vitrine, `display_pedestal` Velvet Pedestal, `display_stand` Open Display, `display_wall` Wall Mount, `display_alcove` Illuminated Alcove |
+
+---
+
+### `romantic_mood` -- Romantic Mood
+
+Jewelry styled as a romantic still life with props. No model.
+
+| Customization | Options |
+|---------------|---------|
+| **Props** (`--detail`) | `prop_rose_petals` Rose Petals, `prop_candles` Candlelight, `prop_love_letter` Love Letter, `prop_silk_lace` Silk & Lace, `prop_fresh_roses` Fresh Roses, `prop_gift_box` The Gift |
+| **Mood** (`--secondary-detail`) | `mood_candlelight` Warm Candlelight, `mood_morning` Soft Morning Light, `mood_moody` Moody & Dark, `mood_golden` Golden Hour Glow, `mood_blush` Blush Pink Haze |
+
+---
+
+## Global Options
+
+### Ethnicities (`--ethnicity`)
+
+| ID | Name |
+|----|------|
+| `european` | European |
+| `moroccan` | Moroccan |
+| `middle_east` | Middle Eastern |
+| `african` | African |
+| `asian` | East Asian |
+
+### Skin Tones (`--skin-tone`)
+
+| ID | Name |
+|----|------|
+| `fair` | Porcelain |
+| `light` | Light |
+| `medium` | Tan |
+| `deep` | Deep |
+| `dark` | Ebony |
+
+### Hair Colors (`--hair-color`)
+
+| ID | Name |
+|----|------|
+| `dark` | Dark / Black |
+| `brunette` | Brunette |
+| `blonde` | Blonde |
+| `red` | Red / Auburn |
+| `grey` | Silver / Grey |
+
+### Backgrounds (`--background`)
+
+| ID | Name |
+|----|------|
+| `silk_cream` | Cream Silk |
+| `velvet_black` | Midnight Velvet |
+| `marble_white` | Carrara Marble |
+| `emerald_velvet` | Emerald Velvet |
+| `studio_grey` | Studio Grey |
+| `warm_beige` | Warm Beige |
+| `burgundy_velvet` | Burgundy Velvet |
+| `champagne_gold` | Champagne Gold |
+| `navy_sapphire` | Navy Sapphire |
+| `blush_rose` | Blush Rose |
+| `ivory_pearl` | Ivory Pearl |
+| `slate_charcoal` | Slate Charcoal |
+
+### Background Types (`--background-type`)
+
+| ID | Name |
+|----|------|
+| `studio` | Studio Flat |
+| `interior` | Luxury Interior |
+| `exterior` | Outdoors |
+| `texture` | Macro Texture |
+
+### Vibes (`--vibe`)
+
+| ID | Name |
+|----|------|
+| `golden_hour` | Golden Hour -- warm natural sunlight |
+| `moody_chic` | Moody Chic -- dramatic shadows, high contrast |
+| `clean_minimal` | Clean Minimal -- bright, airy, minimalist |
+| `romantic_soft` | Romantic -- soft focus, pastel tones |
+
+### Photography Styles (`--photography-style`)
+
+| ID | Name |
+|----|------|
+| `ethereal_dream` | Ethereal Dream |
+| `heritage_luxury` | High-Flash Raw |
+| `modern_edge` | Modern Edge |
+| `soft_natural` | Chromatic Gel |
+| `acid_lofi` | Acid Infrared |
+| `cyber_grit` | Cyber-Grit Noir |
+| `cinematic_editorial` | Cinematic Editorial |
+
+### Resolutions (`--resolution`)
+
+| ID | Aspect Ratio | Best for |
+|----|-------------|----------|
+| `square` | 1:1 | Instagram Feed |
+| `portrait` | 3:4 | Instagram Feed (vertical) |
+| `story` | 9:16 | Instagram Stories / Reels |
+| `landscape` | 16:9 | Website / Ads |
+
+### Occasions (`--occasion`)
+
+Occasions inject cultural/thematic elements (plus decor when available). They do not auto-configure background or vibe.
+
+| ID | Name |
+|----|------|
+| `moroccan_wedding` | Moroccan Wedding |
+| `eid_fitr` | Eid al-Fitr |
+| `eid_adha` | Eid al-Adha |
+| `henna_night` | Henna Night |
+| `ramadan` | Ramadan |
+| `valentines` | Valentine's Day |
+| `mothers_day` | Mother's Day |
+| `birthday` | Birthday |
+| `anniversary` | Anniversary |
+| `graduation` | Graduation |
+| `christmas` | Christmas |
+| `new_year` | New Year |
+
+---
+
+## SDK Usage
+
+```ts
+import { generateImages } from "studio-lumiere-cli";
+
+const result = await generateImages(
+  { apiKey: "your-key", outputDir: "outputs" },
+  {
+    inputImages: ["./ring.jpg"],
+    quantity: 4,
+    selections: {
+      templateId: "hand_model",
+      detailId: "nail_red",
+      backgroundId: "velvet_black",
+      vibeId: "golden_hour",
+      resolutionId: "portrait",
+    },
+  }
+);
+```
+
+## Notes
+
+- Templates, backgrounds, vibes, and all shared options are synced from the main Studio Lumiere web app at build time (`npm run sync`). The CLI always matches the web app.
+- The Muse flow generates variations and stores a local `muses.json` index under your output directory.
+- Video generation uses Veo via the Gemini SDK and returns an operation name plus the video file when available.