@obaidahmed/banana-cli

v1.0.1

Published

a month ago

A CLI tool for generating images using Google Gemini's image generation API

0High
0Medium
0Low

obaidahmed

gemini google ai image-generation cli nano-banana

banana-cli

A powerful CLI tool for generating and modifying images using Google Gemini's image generation API (nano-banana).

Features

Text-to-Image Generation - Generate images from text descriptions
Image-to-Image Modification - Transform existing images with text prompts
Multiple Models - Support for Gemini 2.0 Flash and Imagen 3
Flexible Output - Custom filenames, automatic timestamps, multiple formats
Aspect Ratio Control - 10 different aspect ratios (1:1, 16:9, 9:16, etc.)
Resolution Options - Generate images in 1K, 2K, or 4K resolution
AI Tool Integration - Designed to work with Claude Code, Gemini CLI, and other AI assistants
Cross-Platform - Works on macOS, Linux, and Windows
Zero Configuration - Works out of the box with just an API key

Installation

Global Installation (Recommended)

Install globally to use the banana command anywhere:

npm install -g @obaidahmed/banana-cli

Local Installation

Install as a project dependency:

npm install @obaidahmed/banana-cli

Then run via npx:

npx @obaidahmed/banana-cli -i "your prompt here"

Verify Installation

banana --version
# Output: 1.0.0

banana --help
# Shows all available options

Quick Start

1. Get your API Key

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy your new API key

2. Set up your API Key

Option A: Environment Variable (Recommended)

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GEMINI_API_KEY="your-api-key-here"

Option B: Pass as Argument

banana -k "your-api-key" -i "your prompt"

3. Generate your first image

banana -i "A cute cartoon monkey eating a banana"

This will create a file like generated_1234567890.png in your current directory.

Usage

Text-to-Image Generation

Generate images from text descriptions:

# Basic generation (output: generated_<timestamp>.png)
banana -i "A sunset over the ocean"

# With custom output filename
banana -i "A mountain landscape" -o landscape.png

# With specific model
banana -i "Abstract art" -m gemini-2.0-flash-exp

Image-to-Image Modification

Transform existing images using text prompts:

# Basic modification
banana -i "Make this image look like a watercolor painting" --image input.png

# With custom output
banana -i "Add snow to this scene" --image summer.png -o winter.png

# Style transfer
banana -i "Convert to anime style" --image photo.jpg -o anime.png

CLI Options

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --input <prompt> | -i | string | required | The text prompt describing the image to generate | | --key <apiKey> | -k | string | $GEMINI_API_KEY | Google Gemini API key | | --output <path> | -o | string | generated_<timestamp>.png | Output file path | | --image <path> | | string | | Input image for image-to-image modification | | --model <model> | -m | string | gemini-2.0-flash-exp | Model to use for generation | | --aspect-ratio <ratio> | -a | string | | Aspect ratio of output image | | --size <size> | -s | string | | Output image resolution | | --count <number> | -n | number | 1 | Number of images to generate (1-4) | | --version | -V | | | Display version number | | --help | -h | | | Display help information |

Configuration

API Key Setup

The API key can be provided in two ways:

Environment Variable (Recommended)

Set the GEMINI_API_KEY environment variable:

# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="AIza..."

# Windows Command Prompt
set GEMINI_API_KEY=AIza...

# Windows PowerShell
$env:GEMINI_API_KEY="AIza..."

Command Line Argument

Pass the key directly:

banana -k "AIza..." -i "your prompt"

Available Models

| Model ID | Description | Best For | |----------|-------------|----------| | gemini-2.0-flash-exp | Gemini 2.0 Flash (Experimental) | Fast, general-purpose image generation | | imagen-3.0-generate-002 | Imagen 3 | High-quality, detailed images |

Usage:

# Use default model (gemini-2.0-flash-exp)
banana -i "A forest path"

# Use Imagen 3
banana -i "A forest path" -m imagen-3.0-generate-002

Aspect Ratios

Supported aspect ratios for image generation:

| Ratio | Use Case | |-------|----------| | 1:1 | Square images, social media posts, profile pictures | | 2:3 | Portrait photos, book covers | | 3:2 | Landscape photos, prints | | 3:4 | Portrait mode, tablets | | 4:3 | Standard displays, presentations | | 4:5 | Instagram portrait | | 5:4 | Large format prints | | 9:16 | Mobile screens, stories, reels | | 16:9 | Widescreen, desktop wallpapers, YouTube thumbnails | | 21:9 | Ultra-wide displays, cinematic |

Note: Aspect ratio support varies by model. If not supported, the option will be ignored.

# Square image
banana -i "A logo design" -a 1:1

# Widescreen wallpaper
banana -i "Mountain panorama" -a 16:9

# Mobile wallpaper
banana -i "Abstract patterns" -a 9:16

Image Sizes

| Size | Resolution | Use Case | |------|------------|----------| | 1K | ~1024 pixels | Web, social media, quick previews | | 2K | ~2048 pixels | High-quality prints, detailed work | | 4K | ~4096 pixels | Large prints, professional use |

Note: Image size support varies by model. Higher resolutions may take longer to generate.

# Standard resolution
banana -i "A portrait" -s 1K

# High resolution
banana -i "Detailed illustration" -s 4K

Examples

Basic Examples

# Simple image generation
banana -i "A golden retriever puppy playing in autumn leaves"

# Save to specific location
banana -i "Neon cityscape at night" -o ./images/city.png

# Use Imagen 3 for higher quality
banana -i "Photorealistic portrait of an astronaut" -m imagen-3.0-generate-002

Advanced Examples

# Widescreen wallpaper in high resolution
banana -i "Epic fantasy landscape with floating islands and waterfalls" \
  -a 16:9 \
  -s 2K \
  -o wallpaper.png

# Mobile wallpaper
banana -i "Minimalist geometric patterns in pastel colors" \
  -a 9:16 \
  -o mobile-wallpaper.png

# Generate multiple variations
banana -i "Logo design for a coffee shop called 'Morning Brew'" \
  -n 4 \
  -o logo.png
# Creates: logo.png, logo_2.png, logo_3.png, logo_4.png

Image Modification Examples

# Style Transfer
banana -i "Transform into Van Gogh's Starry Night style" \
  --image photo.jpg \
  -o starry-photo.png

# Add Elements
banana -i "Add a rainbow in the background" \
  --image landscape.jpg \
  -o landscape-rainbow.png

# Color Changes
banana -i "Change the car color from blue to red" \
  --image blue-car.jpg \
  -o red-car.png

# Season Change
banana -i "Convert this summer scene to winter with snow" \
  --image summer-park.jpg \
  -o winter-park.png

# Artistic Remix
banana -i "Reimagine as a cyberpunk scene" \
  --image city-street.jpg \
  -o cyberpunk-street.png

# Background Change
banana -i "Place this product on a marble countertop" \
  --image product.png \
  -o product-styled.png

MCP Server (Model Context Protocol)

banana-cli includes a built-in MCP server that exposes image generation as tools for AI assistants. This allows Claude Code, Gemini CLI, and other MCP-compatible tools to generate and modify images.

MCP Tools Available

| Tool | Description | |------|-------------| | generate_image | Generate an image from a text description | | modify_image | Modify an existing image based on instructions |

Setup for Claude Code

Install banana-cli globally:
```
npm install -g @obaidahmed/banana-cli
```

Set your API key:

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

Add to Claude Code settings:

Open your Claude Code settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add the banana MCP server:

{
  "mcpServers": {
    "banana": {
      "command": "banana-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or if using npx (without global install):

{
  "mcpServers": {
    "banana": {
      "command": "npx",
      "args": ["-y", "@obaidahmed/banana-cli", "banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Code to load the new MCP server.

Use in conversations:

You: Generate an image of a cute robot cooking pasta

Claude: I'll generate that image for you using the banana tool.
[Uses generate_image tool]

Image generated successfully: /path/to/generated_1234567890.png

Setup for Gemini CLI

Install banana-cli:
```
npm install -g @obaidahmed/banana-cli
```

Add to Gemini CLI settings (~/.gemini/settings.json):

{
  "mcpServers": {
    "banana": {
      "command": "banana-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Setup for OpenAI Codex / Other Tools

For tools that support MCP servers, use similar configuration:

{
  "mcpServers": {
    "banana": {
      "command": "banana-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCP Tool Schemas

generate_image

{
  "name": "generate_image",
  "description": "Generate an image from a text description",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Text description of the image to generate"
      },
      "output": {
        "type": "string",
        "description": "Output file path (optional)"
      },
      "model": {
        "type": "string",
        "enum": ["gemini-2.0-flash-exp", "imagen-3.0-generate-002"]
      },
      "aspectRatio": {
        "type": "string",
        "enum": ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
      },
      "size": {
        "type": "string",
        "enum": ["1K", "2K", "4K"]
      }
    },
    "required": ["prompt"]
  }
}

modify_image

{
  "name": "modify_image",
  "description": "Modify an existing image based on instructions",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Instructions for modifying the image"
      },
      "inputImage": {
        "type": "string",
        "description": "Path to the input image file"
      },
      "output": {
        "type": "string",
        "description": "Output file path (optional)"
      },
      "model": {
        "type": "string",
        "enum": ["gemini-2.0-flash-exp", "imagen-3.0-generate-002"]
      }
    },
    "required": ["prompt", "inputImage"]
  }
}

Testing the MCP Server

You can test the MCP server manually:

# Start the server (it communicates via stdin/stdout)
GEMINI_API_KEY="your-key" banana-mcp

# The server will wait for JSON-RPC messages on stdin

Direct CLI Usage with AI Tools

You can also use the CLI directly without MCP:

Claude Code (Direct)

You: Generate an image of a robot chef and save it as robot-chef.png

Claude: I'll generate that image for you.
> banana -i "A friendly robot chef wearing an apron, cooking in a modern kitchen" -o robot-chef.png

Shell Scripts & Automation

#!/bin/bash
# generate-thumbnails.sh - Generate thumbnails for blog posts

POSTS_DIR="./posts"
IMAGES_DIR="./images"

for post in "$POSTS_DIR"/*.md; do
  title=$(head -1 "$post" | sed 's/# //')
  filename=$(basename "$post" .md)

  banana -i "Blog thumbnail for article titled: $title" \
    -a 16:9 \
    -o "$IMAGES_DIR/$filename-thumb.png"
done

Programmatic Usage

While banana-cli is primarily a CLI tool, you can use it programmatically:

import { execSync } from 'child_process';

function generateImage(prompt: string, output?: string): string {
  const args = [`-i`, `"${prompt}"`];
  if (output) args.push(`-o`, output);

  const result = execSync(`banana ${args.join(' ')}`, {
    encoding: 'utf-8',
    env: { ...process.env, GEMINI_API_KEY: 'your-key' }
  });

  return result;
}

// Usage
generateImage('A cute cat', 'cat.png');

Error Handling

Common Errors and Solutions

| Error | Cause | Solution | |-------|-------|----------| | API key is required | No API key provided | Set GEMINI_API_KEY env var or use -k flag | | Invalid API key | Incorrect or expired key | Verify your key at AI Studio | | Content blocked | Prompt violated safety filters | Modify your prompt to comply with content policies | | No images generated | API returned text only | Try rephrasing your prompt | | Input image not found | Invalid --image path | Check the file path exists | | Rate limit exceeded | Too many requests | Wait a moment and try again |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error (see error message for details) |

Troubleshooting

Image not generating

Check your API key:

echo $GEMINI_API_KEY
# Should output your API key

Test with a simple prompt:

banana -i "A red circle on white background" -o test.png

Check for error messages in the output

Wrong aspect ratio / size

Not all models support all aspect ratios and sizes
Try without -a or -s flags first
Check model documentation for supported options

Slow generation

4K images take longer than 1K
Complex prompts may take longer
Consider using gemini-2.0-flash-exp for faster results

Image looks wrong

Be more specific in your prompt
Add style descriptors: "digital art", "photorealistic", "cartoon style"
For image-to-image, be clear about what to change vs. keep

Development

Prerequisites

Node.js >= 18.0.0
npm or yarn

Setup

# Clone the repository
git clone https://github.com/obaid/banana-cli.git
cd banana-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run dev -- -i "prompt" | Run in development mode | | npm test | Run unit tests | | npm run test:watch | Run tests in watch mode | | npm run test:integration:quick | Run quick integration test | | npm run test:integration | Run full integration test suite |

Project Structure

banana-cli/
├── src/
│   ├── index.ts        # CLI entry point
│   ├── cli.ts          # Argument parsing & execution logic
│   ├── api.ts          # Gemini API client
│   └── types.ts        # TypeScript type definitions
├── tests/
│   ├── api.test.ts     # API unit tests
│   ├── cli.test.ts     # CLI unit tests
│   ├── fixtures/       # Test fixtures (images)
│   └── integration/    # Integration tests
├── dist/               # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Running Tests

# Unit tests (fast, no API calls)
npm test

# Integration tests (requires GEMINI_API_KEY)
export GEMINI_API_KEY="your-key"
npm run test:integration:quick  # Quick smoke test
npm run test:integration        # Full test suite

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch:
```
git checkout -b feature/amazing-feature
```
Make your changes and add tests
Run tests:
```
npm test
```
Commit your changes:
```
git commit -m "Add amazing feature"
```
Push to your fork:
```
git push origin feature/amazing-feature
```
Open a Pull Request

Guidelines

Follow existing code style
Add tests for new features
Update documentation as needed
Keep commits focused and atomic

Changelog

v1.0.0

Initial release
Text-to-image generation
Image-to-image modification
Support for Gemini 2.0 Flash and Imagen 3
Aspect ratio and size options
Multiple output formats

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Made with AI by the community