banannate

    _                                       _
   | |__   __ _ _ __   __ _ _ __  _ __   __ _| |_ ___
   | '_ \ / _` | '_ \ / _` | '_ \| '_ \ / _` | __/ _ \
   | |_) | (_| | | | | (_| | | | | | | | (_| | ||  __/
   |_.__/ \__,_|_| |_|\__,_|_| |_|_| |_|\__,_|\__\___|🙊🙈🙉

A CLI tool for generating images using Google's Gemini Models (gemini-2.5-flash-image,gemini-3-pro-image-preview). Built with Bun for fast, efficient image generation from text prompts.

Features

• 🎨 Pro-Level Style Transfer - Don't just rely on text. Pass up to 14 reference images to "teach" the model the exact aesthetic, lighting, or brand style you’re looking for.
• 💎 4K & Native Aspect Ratios -Generate everything from 1:1 social tiles to 21:9 cinematic banners in 1K, 2K, or 4K resolution with simple flags.
• 📝 Markdown-Powered Prompts - Stop fighting with bash strings. Write your complex prompts in a .md file and let banannate read it directly. Perfect for prompt engineering and version control.
• 📊 Developer-First UX
  • Real-time token usage stats (Input/Output/Total).
  • Beautiful CLI progress UI with elapsed time.
  • Single-binary distribution (no node_modules required).
  • Zero external dependencies.

Requirements

• Google API key with Gemini API access
• Bun runtime (only required if building from source)

Installation

Homebrew (macOS)

The easiest way to install banannate on macOS:

# Add the tap
brew tap hvasconcelos/banannate

# Install banannate
brew install banannate

Set up your API key:

export GEMINI_API_KEY="your-api-key-here"

Or add it to your shell profile (~/.zshrc, ~/.bashrc):

echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.zshrc

To update to the latest version:

brew upgrade banannate

To uninstall:

brew uninstall banannate
brew untap hvasconcelos/banannate  # Optional: remove the tap

From Source

If you prefer to build from source or are on a different platform:

1. Clone or download this repository:

git clone <your-repo-url>
cd banannate

2. Install dependencies:

bun install

3. Set up your API key (choose one method):

Option 1: Environment variable (recommended)

export GEMINI_API_KEY="your-api-key-here"

Option 2: Pass via command line

bun index.ts --api-key "your-api-key-here" ...

Usage

Basic Examples

Generate a simple image:

banannate --prompt "A sunset over mountains" --output sunset.png

Use a markdown file for the prompt:

banannate --prompt-file prompt.md --output result.png

Generate with reference images:

banannate --prompt "Similar style" --images ref.jpg,ref2.png --output styled.png

Custom aspect ratio and resolution:

banannate --prompt-file prompt.md --aspect-ratio 16:9 --size 4K --output banner.png

Command Line Options

Required (one of)

• --prompt TEXT - Image generation prompt (text)
• --prompt-file PATH - Read prompt from a markdown file

Required

• --output PATH - Output file path for the generated PNG image

Optional

• --images PATH,PATH - Comma-separated list of reference images (max 14)
• --aspect-ratio RATIO - Image aspect ratio: 1:1, 16:9, 9:16, or 21:9
• --size SIZE - Image resolution: 1K, 2K, or 4K
• --api-key KEY - Override the GEMINI_API_KEY environment variable
• --model MODEL - Model name (default: gemini-3-pro-image-preview)
  • gemini-2.5-flash-image - Fast, efficient image generation
  • gemini-3-pro-image-preview - High-quality image generation (default)
• --help - Show help message

Configuration

Environment Variables

• GEMINI_API_KEY - Your Google API key (required if --api-key not provided)

Image Constraints

• Max reference images: 14
• Max image size: 20MB per image (warning displayed if exceeded)
• Supported formats: JPEG, PNG, GIF, WebP

Output

The tool generates:

1. A PNG image at the specified output path
2. Token usage statistics showing:
   • Input tokens
   • Output tokens
   • Total tokens used

Example output:

Image saved to: result.png

Token Usage:
  Input:  1,234 tokens
  Output: 567 tokens
  Total:  1,801 tokens

Error Handling

The CLI provides helpful error messages for common issues:

• Missing or invalid API key
• Rate limit exceeded
• Invalid request parameters
• File not found errors
• API service issues

Examples

Basic generation

banannate --prompt "A serene lake at dawn" --output lake.png

Fast generation with flash model

banannate --prompt "Quick sketch of a mountain" --model gemini-2.5-flash-image --output quick.png

High-resolution banner

banannate \
  --prompt "Modern tech startup office" \
  --aspect-ratio 21:9 \
  --size 4K \
  --output banner.png

Style transfer with reference

banannate \
  --prompt "Apply this artistic style to a mountain landscape" \
  --images style-reference.jpg \
  --output styled-mountain.png

Using a prompt file

Create a file prompt.md:

A futuristic city at night with neon lights,
flying cars, and towering skyscrapers.
Cyberpunk aesthetic with rain-slicked streets.

Then run:

banannate --prompt-file prompt.md --output cyberpunk-city.png

Building a Standalone Executable

You can build banannate as a standalone executable that can be distributed without requiring Bun to be installed on the target system.

Build for your current platform

bun build --compile --minify --sourcemap ./index.ts --outfile banannate

This creates a single executable file named banannate (or banannate.exe on Windows).

Build for specific platforms

Build for Linux:

bun build --compile --target=bun-linux-x64 ./index.ts --outfile banannate-linux

Build for macOS:

bun build --compile --target=bun-darwin-x64 ./index.ts --outfile banannate-macos

Build for macOS ARM (Apple Silicon):

bun build --compile --target=bun-darwin-arm64 ./index.ts --outfile banannate-macos-arm64

Build for Windows:

bun build --compile --target=bun-windows-x64 ./index.ts --outfile banannate-windows.exe

Using the executable

After building, you can run the executable directly without bun:

# Instead of: bun index.ts --prompt "..." --output result.png
./banannate --prompt "A sunset over mountains" --output sunset.png

Installing globally (optional)

To make the executable available system-wide:

On Linux/macOS:

# Move to a directory in your PATH
sudo mv banannate /usr/local/bin/

# Make it executable (if needed)
chmod +x /usr/local/bin/banannate

# Now you can run it from anywhere
banannate --prompt "..." --output result.png

On Windows:

# Move to a directory in your PATH, or add the directory to PATH
move banannate-windows.exe C:\Windows\System32\banannate.exe

# Now you can run it from anywhere
banannate --prompt "..." --output result.png

Development

The project uses TypeScript and Bun's built-in APIs:

• Bun.file() for file operations
• Native fetch for API calls
• No external dependencies required

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on how to get started.