genmix 1.0.5 → 1.1.5

package/README.md

@@ -166,6 +166,8 @@ await generator.generate(prompt, options)
 | `options.numberOfImages` | number        | Number of images to generate                | 1       |
 | `options.quality`        | string        | Quality: '1K', '2K', '4K'                   | -       |
 | `options.aspectRatio`    | string        | Aspect ratio: '1:1', '16:9', '4:3', etc.    | -       |
+| `options.width`          | number        | Final output width in pixels (requires `height`) | -   |
+| `options.height`         | number        | Final output height in pixels (requires `width`) | -   |
 
 ### save() Method
 
@@ -203,6 +205,25 @@ await generator.save({ filename: 'my-image' });
 await generator.save();
 ```
 
+### Smart target size in library mode (non-CLI)
+
+You can request high generation quality and still force an exact final output size directly in `generate()`:
+
+```javascript
+const generator = new GeminiGenerator();
+
+await generator.generate('App icon, flat minimal style', {
+  quality: '4K', // generation quality (independent)
+  width: 400,
+  height: 400
+});
+
+// width/height resize is automatically applied on save()
+await generator.save({ filename: 'icon-400x400', extension: 'png' });
+```
+
+If you also pass `aspectRatio`, it must match the ratio derived from `width`/`height`.
+
 **Note:** 
 - When multiple images are generated and a custom filename is provided, they will be saved as `filename_0.jpg`, `filename_1.jpg`, etc.
 - The method uses Sharp for image conversion, supporting high-quality format conversion
@@ -330,6 +351,112 @@ genmix/
 
 4. **Result Caching**: Images are automatically saved with unique hash based on the prompt
 
+## CLI Usage
+
+### Global CLI Installation
+
+Install GenMix globally to use it from the command line:
+
+```bash
+npm install -g genmix
+```
+
+### First run and API key persistence
+
+If no API key is available, the CLI asks for it on first use and saves it to:
+
+```text
+~/.genmix/config.json
+```
+
+You can set or update it explicitly anytime:
+
+```bash
+genmix --config
+```
+
+API key resolution order in CLI:
+1. `GEMINI_API_KEY` environment variable
+2. Saved config (`~/.genmix/config.json`)
+3. Interactive prompt (then persisted)
+
+### Basic CLI commands
+
+```bash
+# Show help
+genmix --help
+
+# Generate from prompt
+genmix "A futuristic city with flying cars, cyberpunk style"
+
+# Generate multiple images
+genmix "A cozy cabin in winter" -n 2 -q 2K -r 16:9 -m flash
+```
+
+### Output file path or directory
+
+`--output` accepts either:
+- a directory path, or
+- a full output file path (including filename + extension)
+
+```bash
+# Save to a directory (auto-generated hash filename)
+genmix "Watercolor fox logo" --output ./output
+
+# Save to exact file path and filename
+genmix "Watercolor fox logo" --output ./output/logo-fox.png
+```
+
+### Smart target size (independent from generation quality)
+
+You can ask the model for high generation quality (for example `4K`) and still force a final exact output size.
+
+When you pass target dimensions, GenMix CLI:
+1. Derives the generation ratio automatically (for example `400x400` -> `1:1`, `1920x1080` -> `16:9`)
+2. Generates using your selected quality (`1K`, `2K`, or `4K`)
+3. Resizes the final image to the exact dimensions you requested
+
+```bash
+# Ask for 4K quality, deliver exact 400x400 output
+genmix "app icon, flat minimal style" -q 4K --width 400 --height 400 --output ./output/icon.png
+```
+
+If you also pass `--ratio`, it must match the derived ratio from the target size.
+
+### References with optional text description
+
+Use `--ref <path:text>` to add reference images with optional guidance text:
+
+```bash
+# Reference path only
+genmix "Restyle this room" --ref ./room.jpg
+
+# Reference path + description
+genmix "Restyle this room" --ref "./room.jpg:keep composition and camera angle"
+
+# Multiple references with descriptions
+genmix "Create product ad scene" \
+  --ref "./product.png:use as main subject" \
+  --ref "./bg.jpg:use as background mood"
+```
+
+### CLI options
+
+```text
+-n, --number <N>          Number of images (default: 1)
+-q, --quality <1K|2K|4K>  Image quality (default: 1K)
+-r, --ratio <ratio>       Aspect ratio (default: 1:1)
+-m, --model <pro|flash>   Model (default: flash)
+-o, --output <path>       Output directory or full output file path
+-f, --format <format>     Output format when output is a directory (default: jpg)
+--width <px>              Final output width in pixels (requires --height)
+--height <px>             Final output height in pixels (requires --width)
+--ref <path:text>         Reference image, optional description after ":"
+--no-sharp                Save raw model bytes without Sharp conversion (disables resizing)
+--config                  Set/update persisted API key
+--help                    Show help
+```
+
 ## Additional Resources
 
 - [Code Examples](./demo/)

package/cli.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const GeminiGenerator = require('./generators/GeminiGenerator');
+
+const CONFIG_DIR = path.join(os.homedir(), '.genmix');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif', 'tiff', 'tif', 'gif']);
+
+function color(code, message) {
+    return `\x1b[${code}m${message}\x1b[0m`;
+}
+
+function info(message) {
+    console.log(color('36', message));
+}
+
+function success(message) {
+    console.log(color('32', message));
+}
+
+function error(message) {
+    console.error(color('31', message));
+}
+
+function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        return {};
+    }
+
+    try {
+        const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+        if (!raw.trim()) {
+            return {};
+        }
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch (err) {
+        throw new Error(`Failed reading config at ${CONFIG_PATH}: ${err.message}`);
+    }
+}
+
+function saveConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf8');
+}
+
+function promptQuestion(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+async function promptApiKey() {
+    const apiKey = (await promptQuestion('Enter your Gemini API key: ')).trim();
+    if (!apiKey) {
+        throw new Error('API key cannot be empty.');
+    }
+    return apiKey;
+}
+
+function printHelp() {
+    console.log(`
+Usage:
+  genmix "prompt text" [options]
+  genmix --config
+  genmix --help
+
+Options:
+  -n, --number <N>        Number of images (default: 1)
+  -q, --quality <1K|2K|4K> Image quality (default: 1K)
+  -r, --ratio <ratio>     Aspect ratio (default: 1:1)
+  --width <px>            Final output width in pixels (requires --height)
+  --height <px>           Final output height in pixels (requires --width)
+  -m, --model <pro|flash> Model (default: flash)
+  -o, --output <path>     Output directory OR full output file path
+  -f, --format <format>   Output format when output is a directory (default: jpg)
+  --no-sharp              Save raw model bytes without Sharp conversion
+  --ref <path:text>       Reference image; optional description after ":" (repeatable)
+  --help                  Show this help message
+  --config                Set or update persisted API key
+
+Examples:
+  genmix "cyberpunk city at night"
+  genmix "logo in watercolor style" -n 2 -q 2K -o ./output
+  genmix "app icon" -q 4K --width 400 --height 400 --output ./renders/icon.png
+  genmix "new version of this room" --ref room.jpg:"keep composition"
+  genmix "portrait variation" --ref subject.png --output ./renders/portrait.png
+`);
+}
+
+function parseRefValue(value) {
+    const firstColonIndex = value.indexOf(':');
+    if (firstColonIndex === -1) {
+        return { imagePath: value.trim(), description: '' };
+    }
+
+    const imagePath = value.slice(0, firstColonIndex).trim();
+    const description = value.slice(firstColonIndex + 1).trim();
+    return { imagePath, description };
+}
+
+function parseArgs(argv) {
+    const parsed = {
+        promptParts: [],
+        references: [],
+        numberOfImages: 1,
+        quality: '1K',
+        aspectRatio: null,
+        aspectRatioWasProvided: false,
+        model: 'flash',
+        output: '.',
+        format: 'jpg',
+        targetWidth: null,
+        targetHeight: null,
+        useSharp: true,
+        showHelp: false,
+        runConfig: false
+    };
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+
+        if (arg === '--help' || arg === '-h') {
+            parsed.showHelp = true;
+            continue;
+        }
+
+        if (arg === '--config') {
+            parsed.runConfig = true;
+            continue;
+        }
+
+        if (arg === '-n' || arg === '--number') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.numberOfImages = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-q' || arg === '--quality') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.quality = next;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-r' || arg === '--ratio') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.aspectRatio = next;
+            parsed.aspectRatioWasProvided = true;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--width') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.targetWidth = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--height') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.targetHeight = Number(next);
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-m' || arg === '--model') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.model = String(next).toLowerCase();
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-o' || arg === '--output') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.output = next;
+            i += 1;
+            continue;
+        }
+
+        if (arg === '-f' || arg === '--format') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.format = String(next).replace(/^\./, '').toLowerCase();
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--ref') {
+            if (!next) throw new Error(`${arg} requires a value.`);
+            parsed.references.push(parseRefValue(next));
+            i += 1;
+            continue;
+        }
+
+        if (arg === '--no-sharp') {
+            parsed.useSharp = false;
+            continue;
+        }
+
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+
+        parsed.promptParts.push(arg);
+    }
+
+    if (!parsed.runConfig && !parsed.showHelp && parsed.promptParts.length === 0) {
+        throw new Error('Missing prompt text. Use genmix "your prompt".');
+    }
+
+    if (!Number.isInteger(parsed.numberOfImages) || parsed.numberOfImages <= 0) {
+        throw new Error('Number of images must be a positive integer.');
+    }
+
+    const quality = parsed.quality.toUpperCase();
+    if (!['1K', '2K', '4K'].includes(quality)) {
+        throw new Error('Quality must be one of: 1K, 2K, 4K.');
+    }
+    parsed.quality = quality;
+
+    if (!['flash', 'pro'].includes(parsed.model)) {
+        throw new Error('Model must be "flash" or "pro".');
+    }
+
+    const hasOnlyOneDimension = (parsed.targetWidth === null) !== (parsed.targetHeight === null);
+    if (hasOnlyOneDimension) {
+        throw new Error('Both --width and --height are required together.');
+    }
+
+    const hasTargetDimensions = parsed.targetWidth !== null && parsed.targetHeight !== null;
+    if (hasTargetDimensions) {
+        if (!Number.isInteger(parsed.targetWidth) || parsed.targetWidth <= 0) {
+            throw new Error('Width must be a positive integer.');
+        }
+        if (!Number.isInteger(parsed.targetHeight) || parsed.targetHeight <= 0) {
+            throw new Error('Height must be a positive integer.');
+        }
+    }
+
+    if (!parsed.useSharp && hasTargetDimensions) {
+        throw new Error('Resizing requires Sharp. Remove --no-sharp to use --width/--height.');
+    }
+
+    if (!parsed.aspectRatioWasProvided && !hasTargetDimensions) {
+        parsed.aspectRatio = '1:1';
+    }
+
+    for (const ref of parsed.references) {
+        if (!ref.imagePath) {
+            throw new Error('Reference path cannot be empty.');
+        }
+    }
+
+    parsed.prompt = parsed.promptParts.join(' ').trim();
+    return parsed;
+}
+
+function resolveOutput(outputArg, format) {
+    const extension = path.extname(outputArg).replace(/^\./, '').toLowerCase();
+    const isFilePath = extension && IMAGE_EXTENSIONS.has(extension);
+
+    if (isFilePath) {
+        const absolute = path.resolve(process.cwd(), outputArg);
+        return {
+            directory: path.dirname(absolute),
+            filename: path.basename(absolute, path.extname(absolute)),
+            extension
+        };
+    }
+
+    return {
+        directory: path.resolve(process.cwd(), outputArg),
+        filename: null,
+        extension: format
+    };
+}
+
+async function ensureApiKey() {
+    const config = loadConfig();
+    const envApiKey = process.env.GEMINI_API_KEY;
+    if (envApiKey && envApiKey.trim()) {
+        return envApiKey.trim();
+    }
+    if (config.apiKey && config.apiKey.trim()) {
+        return config.apiKey.trim();
+    }
+
+    info('No API key found. Let us configure it now.');
+    const newApiKey = await promptApiKey();
+    saveConfig({ ...config, apiKey: newApiKey });
+    success(`API key saved to ${CONFIG_PATH}`);
+    return newApiKey;
+}
+
+async function runConfigCommand() {
+    const existing = loadConfig();
+    if (existing.apiKey) {
+        info(`Existing API key found in ${CONFIG_PATH}.`);
+    } else {
+        info('No saved API key found.');
+    }
+
+    const newApiKey = await promptApiKey();
+    saveConfig({ ...existing, apiKey: newApiKey });
+    success(`API key saved to ${CONFIG_PATH}`);
+}
+
+async function runGeneration(args) {
+    const apiKey = await ensureApiKey();
+    const generator = new GeminiGenerator({ apiKey });
+
+    if (args.model === 'pro') {
+        generator.pro();
+    } else {
+        generator.flash();
+    }
+
+    for (const ref of args.references) {
+        generator.addReference(ref.imagePath, ref.description);
+    }
+
+    info('Generating image(s)...');
+    const generation = await generator.generate(args.prompt, {
+        numberOfImages: args.numberOfImages,
+        quality: args.quality,
+        aspectRatio: args.aspectRatio,
+        width: args.targetWidth,
+        height: args.targetHeight
+    });
+
+    if (generation.text) {
+        info(`Model response: ${generation.text}`);
+    }
+
+    if (!generation.images || generation.images.length === 0) {
+        info('No images were returned by the model.');
+        return;
+    }
+
+    const saveOptions = resolveOutput(args.output, args.format);
+    saveOptions.useSharp = args.useSharp;
+    if (args.targetWidth && args.targetHeight) {
+        info(`Resizing final output to ${args.targetWidth}x${args.targetHeight}.`);
+    }
+    const savedPaths = await generator.save(saveOptions);
+    savedPaths.forEach((savedPath) => {
+        success(`Saved: ${savedPath}`);
+    });
+}
+
+async function main() {
+    try {
+        const args = parseArgs(process.argv.slice(2));
+
+        if (args.showHelp) {
+            printHelp();
+            return;
+        }
+
+        if (args.runConfig) {
+            await runConfigCommand();
+            return;
+        }
+
+        await runGeneration(args);
+    } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+    }
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = {
+    parseArgs,
+    resolveOutput
+};

package/docs/decisions/genmix-cli-output-path-and-reference-text.md

@@ -0,0 +1,12 @@
+---
+id: ydgrqwuq05
+type: decision
+title: 'Decision: GenMix CLI output and refs'
+created: '2026-03-19 12:44:27'
+---
+# Decision: GenMix CLI output path and reference text
+
+**What**: The CLI supports `--output` as either a directory or a full output file path, and supports `--ref` values as `path` or `path:description`.
+**Where**: `cli.js` argument parsing and output resolution.
+**Why**: Users need deterministic output naming/location and richer reference guidance for prompt conditioning.
+**Alternatives rejected**: Separate flags for `--ref-path` + `--ref-text` were rejected because repeated `--ref` with `path:description` is simpler for command-line ergonomics.

package/docs/decisions/genmix-cli-smart-target-size.md

@@ -0,0 +1,12 @@
+---
+id: af6zbnxehw
+type: decision
+title: 'Decision: Smart CLI target size flow'
+created: '2026-03-19 13:28:11'
+---
+# Decision: Smart CLI target size flow
+
+**What**: Added `--size WxH` and `--width/--height` to derive generation aspect ratio automatically and then resize final output to exact dimensions.
+**Where**: `cli.js` and CLI docs in `README.md`.
+**Why**: Users need exact output dimensions (e.g. 400x400) while keeping generation quality independent (e.g. 4K).
+**Alternatives rejected**: Keeping resize manual in code-only API was rejected because CLI users need first-class support.

package/docs/patterns/genmix-cli-avoid-redundant-flags.md

@@ -0,0 +1,12 @@
+---
+id: dw7miivs7w
+type: pattern
+title: 'Lesson: Keep CLI surface minimal'
+created: '2026-03-19 13:34:50'
+---
+# Pattern: Keep CLI surface minimal
+
+**What**: Prefer one clear way to express output dimensions in CLI. Removed redundant `--size` in favor of `--width` + `--height`.
+**Where used**: `cli.js` argument parsing/help and `README.md` CLI documentation.
+**When to apply**: When multiple flags encode the same behavior and one can be removed without losing capability.
+**Why**: Simpler UX, less ambiguity, fewer parsing edge cases.

package/docs/patterns/genmix-single-source-validation.md

@@ -0,0 +1,12 @@
+---
+id: ly0zl6yegp
+type: pattern
+title: 'Lesson: Avoid CLI-core validation duplication'
+created: '2026-03-19 13:36:41'
+---
+# Pattern: Single-source validation in core
+
+**What**: Keep dimension/aspect-ratio derivation and validation in `GeminiGenerator` (core), not duplicated in `cli.js`.
+**Where used**: `cli.js` now only parses input and basic presence/type checks; `_normalizeGenerateOptions()` in `GeminiGenerator` handles semantic validation.
+**When to apply**: Any feature shared by CLI and library/API usage.
+**Why**: Prevent drift, inconsistent behavior, and double-maintenance bugs.

package/generators/BaseGenerator.js

@@ -29,9 +29,13 @@ class BaseGenerator {
      * @param {Object} [options.formatOptions] - Format-specific options (quality, compressionLevel, palette, colours, etc.)
      * @returns {Promise<string[]>} Promise that resolves to array of saved file paths.
      */
-    async save({directory = '.', filename = null, extension = 'jpg', formatOptions = null} = {}) {
+    async save({directory = '.', filename = null, extension = 'jpg', formatOptions = null, useSharp = true} = {}) {
         const targetImages = this.lastGeneration?.images;
         const targetPrompt = this.lastGeneration?.prompt;
+        const inheritedFormatOptions = this.lastGeneration?.formatOptions || null;
+        const effectiveFormatOptions = formatOptions
+            ? { ...(inheritedFormatOptions || {}), ...formatOptions }
+            : inheritedFormatOptions;
 
         if (!targetImages || !Array.isArray(targetImages) || targetImages.length === 0) {
             console.warn('No images to save.');
@@ -48,8 +52,8 @@ class BaseGenerator {
         }
 
         // Use format from formatOptions if provided, otherwise use extension
-        if (formatOptions && formatOptions.format) {
-            extension = formatOptions.format;
+        if (effectiveFormatOptions && effectiveFormatOptions.format) {
+            extension = effectiveFormatOptions.format;
         }
 
         // Normalize extension
@@ -69,32 +73,43 @@ class BaseGenerator {
         
         for (let index = 0; index < targetImages.length; index++) {
             const imgData = targetImages[index];
-            const base64Data = imgData.replace(/^data:image\/\w+;base64,/, "");
+            const mimeMatch = imgData.match(/^data:image\/([a-zA-Z0-9.+-]+);base64,/);
+            const sourceFormat = mimeMatch ? mimeMatch[1].toLowerCase() : null;
+            const normalizedSourceFormat = sourceFormat === 'jpeg' ? 'jpg' : sourceFormat;
+            const base64Data = imgData.replace(/^data:image\/[a-zA-Z0-9.+-]+;base64,/, "");
             const buffer = Buffer.from(base64Data, 'base64');
 
+            const effectiveExtension = useSharp ? fileExtension : (normalizedSourceFormat || fileExtension);
+
             let fileName;
             if (filename) {
                 // Use custom filename, add index if multiple images
                 if (targetImages.length > 1) {
-                    fileName = `${filename}_${index}.${fileExtension}`;
+                    fileName = `${filename}_${index}.${effectiveExtension}`;
                 } else {
-                    fileName = `${filename}.${fileExtension}`;
+                    fileName = `${filename}.${effectiveExtension}`;
                 }
             } else {
                 // Use hash-based filename
                 const hash = this.generateHash(targetPrompt + '_' + index);
-                fileName = `${hash}.${fileExtension}`;
+                fileName = `${hash}.${effectiveExtension}`;
             }
             
             const outputPath = path.join(directory, fileName);
 
+            if (!useSharp) {
+                fs.writeFileSync(outputPath, buffer);
+                savedPaths.push(outputPath);
+                continue;
+            }
+
             // Convert image format using sharp
             try {
                 let sharpInstance = sharp(buffer);
                 
                 // Resize if dimensions are specified in formatOptions
-                if (formatOptions && formatOptions.width && formatOptions.height) {
-                    sharpInstance = sharpInstance.resize(formatOptions.width, formatOptions.height, {
+                if (effectiveFormatOptions && effectiveFormatOptions.width && effectiveFormatOptions.height) {
+                    sharpInstance = sharpInstance.resize(effectiveFormatOptions.width, effectiveFormatOptions.height, {
                         fit: 'fill'
                     });
                 }
@@ -102,29 +117,29 @@ class BaseGenerator {
                 // Build format-specific options
                 const sharpFormatOptions = {};
                 
-                if (formatOptions) {
-                    if (sharpFormat === 'jpg' && formatOptions.quality) {
-                        sharpFormatOptions.quality = formatOptions.quality;
+                if (effectiveFormatOptions) {
+                    if (sharpFormat === 'jpg' && effectiveFormatOptions.quality) {
+                        sharpFormatOptions.quality = effectiveFormatOptions.quality;
                     } else if (sharpFormat === 'png') {
-                        if (formatOptions.compressionLevel !== undefined) {
-                            sharpFormatOptions.compressionLevel = formatOptions.compressionLevel;
+                        if (effectiveFormatOptions.compressionLevel !== undefined) {
+                            sharpFormatOptions.compressionLevel = effectiveFormatOptions.compressionLevel;
                         }
-                        if (formatOptions.quality !== undefined) {
-                            sharpFormatOptions.quality = formatOptions.quality;
+                        if (effectiveFormatOptions.quality !== undefined) {
+                            sharpFormatOptions.quality = effectiveFormatOptions.quality;
                         }
-                        if (formatOptions.effort !== undefined) {
-                            sharpFormatOptions.effort = formatOptions.effort;
+                        if (effectiveFormatOptions.effort !== undefined) {
+                            sharpFormatOptions.effort = effectiveFormatOptions.effort;
                         }
-                        if (formatOptions.palette) {
+                        if (effectiveFormatOptions.palette) {
                             sharpFormatOptions.palette = true;
                             // Add dithering for better quality with palette
                             sharpFormatOptions.dither = 1.0;
                         }
-                        if (formatOptions.colours) {
-                            sharpFormatOptions.colours = formatOptions.colours;
+                        if (effectiveFormatOptions.colours) {
+                            sharpFormatOptions.colours = effectiveFormatOptions.colours;
                         }
-                    } else if (sharpFormat === 'webp' && formatOptions.quality) {
-                        sharpFormatOptions.quality = formatOptions.quality;
+                    } else if (sharpFormat === 'webp' && effectiveFormatOptions.quality) {
+                        sharpFormatOptions.quality = effectiveFormatOptions.quality;
                     }
                 }
                 

package/generators/GeminiGenerator.js

@@ -67,6 +67,55 @@ class GeminiGenerator extends BaseGenerator {
         return this;
     }
 
+    _gcd(a, b) {
+        let x = Math.abs(a);
+        let y = Math.abs(b);
+        while (y !== 0) {
+            const t = y;
+            y = x % y;
+            x = t;
+        }
+        return x || 1;
+    }
+
+    _deriveAspectRatio(width, height) {
+        const divisor = this._gcd(width, height);
+        return `${width / divisor}:${height / divisor}`;
+    }
+
+    _normalizeGenerateOptions(options = {}) {
+        const normalizedOptions = { ...options };
+        const hasWidth = normalizedOptions.width !== undefined && normalizedOptions.width !== null;
+        const hasHeight = normalizedOptions.height !== undefined && normalizedOptions.height !== null;
+
+        if (hasWidth !== hasHeight) {
+            throw new Error('Both options.width and options.height are required together.');
+        }
+
+        if (hasWidth && hasHeight) {
+            const width = Number(normalizedOptions.width);
+            const height = Number(normalizedOptions.height);
+
+            if (!Number.isInteger(width) || width <= 0) {
+                throw new Error('options.width must be a positive integer.');
+            }
+            if (!Number.isInteger(height) || height <= 0) {
+                throw new Error('options.height must be a positive integer.');
+            }
+
+            const derivedRatio = this._deriveAspectRatio(width, height);
+            if (normalizedOptions.aspectRatio && normalizedOptions.aspectRatio !== derivedRatio) {
+                throw new Error(`Aspect ratio mismatch: options.aspectRatio ${normalizedOptions.aspectRatio} does not match options.width/options.height (${derivedRatio}).`);
+            }
+
+            normalizedOptions.aspectRatio = derivedRatio;
+            normalizedOptions.width = width;
+            normalizedOptions.height = height;
+        }
+
+        return normalizedOptions;
+    }
+
     /**
      * @param {string} prompt
      * @param {Object} [options]
@@ -74,19 +123,22 @@ class GeminiGenerator extends BaseGenerator {
      * @param {string} [options.numberOfImages] - Number of images to generate
      * @param {string} [options.quality] - Image quality: '1K', '2K', '4K'
      * @param {string} [options.aspectRatio] - Aspect ratio like '1:1', '16:9', etc.
+     * @param {number} [options.width] - Final output width in pixels (requires options.height)
+     * @param {number} [options.height] - Final output height in pixels (requires options.width)
      * @returns {Promise<{images: string[], text: string, raw: any}>}
      */
     async generate(prompt, options = {}) {
+        const normalizedOptions = this._normalizeGenerateOptions(options);
         // If the user asks for multiple images, we might need to make parallel requests
         // if the API doesn't support candidateCount > 1 for images.
         // Based on search results, candidateCount > 1 can cause 400 errors.
-        const numberOfImages = options.numberOfImages || 1;
+        const numberOfImages = normalizedOptions.numberOfImages || 1;
 
         let result;
         if (numberOfImages > 1) {
-            result = await this.generateMultiple(prompt, numberOfImages, options);
+            result = await this.generateMultiple(prompt, numberOfImages, normalizedOptions);
         } else {
-            result = await this._generateSingleRequest(prompt, options);
+            result = await this._generateSingleRequest(prompt, normalizedOptions);
         }
 
         // Store result in state for saveImages()
@@ -94,7 +146,10 @@ class GeminiGenerator extends BaseGenerator {
             prompt: prompt,
             images: result.images,
             text: result.text,
-            raw: result.raw
+            raw: result.raw,
+            formatOptions: normalizedOptions.width && normalizedOptions.height
+                ? { width: normalizedOptions.width, height: normalizedOptions.height }
+                : null
         };
 
         this.references = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genmix",
-  "version": "1.0.5",
+  "version": "1.1.5",
   "description": "AI-powered image generator using Google Gemini API. Supports image generation from text prompts and image modification with reference images.",
   "license": "MIT",
   "author": "Martin Clasen",
@@ -17,10 +17,14 @@
     "style-transfer",
     "generative-ai",
     "genmix",
+    "cli",
     "clasen"
   ],
   "type": "commonjs",
   "main": "index.js",
+  "bin": {
+    "genmix": "./cli.js"
+  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },