Nano Banana Gemini CLI Extension (gemini-cli-extensions/nanobanana)

Nano Banana Gemini CLI Extension

https://github.com/gemini-cli-extensions/nanobanana
Admin
A professional Gemini CLI extension for generating and manipulating images using the Gemini 2.5...

Tokens:11,465
Snippets:79
Trust Score:7.2
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Nano Banana - Gemini CLI Extension

Nano Banana is a professional Gemini CLI extension for generating and manipulating images using Google's Nano Banana models (gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-image). It provides a comprehensive MCP (Model Context Protocol) server that enables text-to-image generation, image editing, image restoration, icon generation, pattern creation, visual storytelling, and technical diagram generation through natural language prompts.

The extension integrates with the Gemini CLI via the `@modelcontextprotocol/sdk` and `@google/genai` packages, exposing seven specialized MCP tools that can be invoked through slash commands. It features smart file management with automatic filename generation based on prompts, duplicate prevention, and configurable search paths for input images. All generated images are saved to the `./nanobanana-output/` directory with optional preview functionality that opens images in the system's default viewer.

## Installation

Install the extension using the Gemini CLI extensions command.

```bash
# Install the extension from GitHub
gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

# Set your API key (required)
export NANOBANANA_API_KEY="your-api-key-here"

# Optionally select a different model (default: gemini-3.1-flash-image-preview)
export NANOBANANA_MODEL=gemini-3-pro-image-preview

# Restart Gemini CLI to activate the extension
```

## generate_image Tool

Generate single or multiple images from text prompts with support for artistic styles, variations, and batch generation. This tool accepts a prompt and optional parameters for controlling output count, styles, variations, format, seed, and preview behavior.

```bash
# Basic single image generation
/generate "a watercolor painting of a fox in a snowy forest"

# Generate 4 variations with different artistic styles
/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"

# Generate variations with different lighting and mood
/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# Output: dramatic lighting, soft lighting, cheerful mood, dramatic mood versions

# Combined styles and variations with auto-preview
/generate "friendly robot character" --styles="anime,minimalist" --variations="color-palette" --preview

# Simple batch generation with seed for reproducibility
/generate "tech startup logo" --count=6 --seed=42

# Grid output format
/generate "sunset over mountains" --count=3 --format=grid
```

```typescript
// MCP Tool Schema for generate_image
{
  name: 'generate_image',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Text prompt describing the image' },
      outputCount: { type: 'number', minimum: 1, maximum: 8, default: 1 },
      styles: { type: 'array', items: { type: 'string' } },
      // Available: photorealistic, watercolor, oil-painting, sketch, pixel-art,
      // anime, vintage, modern, abstract, minimalist
      variations: { type: 'array', items: { type: 'string' } },
      // Available: lighting, angle, color-palette, composition, mood, season, time-of-day
      format: { type: 'string', enum: ['grid', 'separate'], default: 'separate' },
      seed: { type: 'number' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt']
  }
}
```

## edit_image Tool

Edit existing images using natural language instructions. The tool searches for input files in the current directory, `./images/`, `./input/`, `./nanobanana-output/`, `~/Downloads/`, and `~/Desktop/`.

```bash
# Add elements to an existing image
/edit my_photo.png "add sunglasses to the person"

# Change the background with preview
/edit portrait.jpg "change background to a beach scene" --preview

# Modify specific aspects of an image
/edit landscape.png "make it look like autumn with orange and red leaves"

# Add text or objects
/edit product_shot.jpg "add a subtle shadow beneath the product"
```

```typescript
// MCP Tool Schema for edit_image
{
  name: 'edit_image',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Text prompt describing edits to make' },
      file: { type: 'string', description: 'Filename of the input image' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt', 'file']
  }
}

// File search paths (in order):
// 1. process.cwd()
// 2. ./images/
// 3. ./input/
// 4. ./nanobanana-output/
// 5. ~/Downloads/
// 6. ~/Desktop/
```

## restore_image Tool

Restore and enhance old, damaged, or low-quality images using AI-powered restoration with natural language instructions.

```bash
# Remove scratches and improve clarity
/restore old_family_photo.jpg "remove scratches and improve clarity"

# Enhance colors and fix physical damage
/restore damaged_photo.png "enhance colors and fix tears" --preview

# General quality improvement
/restore vintage_portrait.jpg "restore to original quality, fix fading and discoloration"

# Specific damage repair
/restore scanned_photo.png "remove dust spots and repair creases"
```

```typescript
// MCP Tool Schema for restore_image
{
  name: 'restore_image',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Text prompt describing restoration to perform' },
      file: { type: 'string', description: 'Filename of the input image to restore' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt', 'file']
  }
}
```

## generate_icon Tool

Generate app icons, favicons, and UI elements in multiple sizes with professional styling options including corner styles, backgrounds, and visual styles.

```bash
# Complete app icon set with rounded corners
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# Website favicon package
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"

# UI element with transparent background
/icon "notification bell" --type="ui-element" --style="flat" --background="transparent"

# Skeuomorphic app icon
/icon "camera app icon" --type="app-icon" --style="skeuomorphic" --sizes="128,256"

# Minimal modern icon with colored background
/icon "settings gear" --style="minimal" --background="blue" --preview
```

```typescript
// MCP Tool Schema for generate_icon
{
  name: 'generate_icon',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Description of the icon to generate' },
      sizes: { type: 'array', items: { type: 'number' } },
      // Common sizes: 16, 32, 64, 128, 256, 512, 1024
      type: { type: 'string', enum: ['app-icon', 'favicon', 'ui-element'], default: 'app-icon' },
      style: { type: 'string', enum: ['flat', 'skeuomorphic', 'minimal', 'modern'], default: 'modern' },
      format: { type: 'string', enum: ['png', 'jpeg'], default: 'png' },
      background: { type: 'string', default: 'transparent' },
      // Options: transparent, white, black, or color name
      corners: { type: 'string', enum: ['rounded', 'sharp'], default: 'rounded' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt']
  }
}
```

## generate_pattern Tool

Generate seamless patterns and textures for backgrounds, wallpapers, and design elements with control over density, color scheme, and tiling method.

```bash
# Seamless website background pattern
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# Material texture
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"

# Decorative wallpaper
/pattern "art deco design" --type="wallpaper" --style="geometric" --size="512x512"

# Floral pattern with medium density
/pattern "botanical leaves" --type="seamless" --style="floral" --density="medium" --preview

# Organic texture with mirror tiling
/pattern "marble texture" --type="texture" --style="organic" --repeat="mirror"
```

```typescript
// MCP Tool Schema for generate_pattern
{
  name: 'generate_pattern',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Description of the pattern to generate' },
      size: { type: 'string', default: '256x256' },
      // Common: 128x128, 256x256, 512x512
      type: { type: 'string', enum: ['seamless', 'texture', 'wallpaper'], default: 'seamless' },
      style: { type: 'string', enum: ['geometric', 'organic', 'abstract', 'floral', 'tech'], default: 'abstract' },
      density: { type: 'string', enum: ['sparse', 'medium', 'dense'], default: 'medium' },
      colors: { type: 'string', enum: ['mono', 'duotone', 'colorful'], default: 'colorful' },
      repeat: { type: 'string', enum: ['tile', 'mirror'], default: 'tile' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt']
  }
}
```

## generate_story Tool

Generate sequential images that tell a visual story, demonstrate a process, create tutorials, or visualize timelines with consistent visual style across frames.

```bash
# Product development process
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# Educational tutorial with comic layout
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"

# Brand evolution timeline
/story "company logo evolution" --steps=4 --type="timeline" --transition="smooth"

# Visual narrative story
/story "a seed growing into a tree" --steps=4 --type="story" --preview

# Step-by-step cooking tutorial
/story "how to make coffee" --steps=6 --type="tutorial" --style="consistent"
```

```typescript
// MCP Tool Schema for generate_story
{
  name: 'generate_story',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Description of the story or process to visualize' },
      steps: { type: 'number', minimum: 2, maximum: 8, default: 4 },
      type: { type: 'string', enum: ['story', 'process', 'tutorial', 'timeline'], default: 'story' },
      style: { type: 'string', enum: ['consistent', 'evolving'], default: 'consistent' },
      layout: { type: 'string', enum: ['separate', 'grid', 'comic'], default: 'separate' },
      transition: { type: 'string', enum: ['smooth', 'dramatic', 'fade'], default: 'smooth' },
      format: { type: 'string', enum: ['storyboard', 'individual'], default: 'individual' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt']
  }
}

// Each step is generated with context:
// - Story: "narrative sequence, {style} art style"
// - Process: "procedural step, instructional illustration"
// - Tutorial: "tutorial step, educational diagram"
// - Timeline: "chronological progression, timeline visualization"
```

## generate_diagram Tool

Generate professional technical diagrams, flowcharts, architecture diagrams, database schemas, wireframes, mind maps, and sequence diagrams from text descriptions.

```bash
# Development workflow flowchart
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"

# System architecture
/diagram "chat application architecture" --type="architecture" --style="technical"

# API documentation sequence diagram
/diagram "REST API authentication flow" --type="sequence" --layout="vertical"

# Database schema design
/diagram "social media database schema" --type="database" --annotations="detailed"

# UI wireframe mockup
/diagram "mobile app login screen" --type="wireframe" --style="clean"

# Concept mind map
/diagram "machine learning concepts" --type="mindmap" --layout="circular" --preview

# Network topology
/diagram "cloud infrastructure with load balancers" --type="network" --complexity="comprehensive"
```

```typescript
// MCP Tool Schema for generate_diagram
{
  name: 'generate_diagram',
  inputSchema: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'Description of the diagram content' },
      type: {
        type: 'string',
        enum: ['flowchart', 'architecture', 'network', 'database', 'wireframe', 'mindmap', 'sequence'],
        default: 'flowchart'
      },
      style: { type: 'string', enum: ['professional', 'clean', 'hand-drawn', 'technical'], default: 'professional' },
      layout: { type: 'string', enum: ['horizontal', 'vertical', 'hierarchical', 'circular'], default: 'hierarchical' },
      complexity: { type: 'string', enum: ['simple', 'detailed', 'comprehensive'], default: 'detailed' },
      colors: { type: 'string', enum: ['mono', 'accent', 'categorical'], default: 'accent' },
      annotations: { type: 'string', enum: ['minimal', 'detailed'], default: 'detailed' },
      preview: { type: 'boolean', default: false }
    },
    required: ['prompt']
  }
}
```

## Natural Language Interface

The `/nanobanana` command provides a flexible natural language interface that intelligently routes requests to the appropriate specialized tool based on the user's intent.

```bash
# Image generation (routes to generate_image)
/nanobanana create a logo for my tech startup
/nanobanana I need 5 different versions of a cat illustration in various art styles

# Image editing (routes to edit_image)
/nanobanana fix the lighting in sunset.jpg and make it more vibrant

# Icon generation (routes to generate_icon)
/nanobanana create app icons for my weather app in all standard sizes

# Pattern generation (routes to generate_pattern)
/nanobanana make a seamless geometric pattern for my website background

# Story generation (routes to generate_story)
/nanobanana create a 4-step visual showing how photosynthesis works

# Diagram generation (routes to generate_diagram)
/nanobanana draw a flowchart showing user authentication process
```

## FileHandler Utility

The FileHandler class manages all file I/O operations including smart filename generation, input file discovery, and base64 image encoding/decoding.

```typescript
import { FileHandler } from './fileHandler.js';

// Ensure output directory exists (creates ./nanobanana-output/)
const outputPath = FileHandler.ensureOutputDirectory();

// Generate a unique filename from prompt
const filename = FileHandler.generateFilename(
  "sunset over mountains",  // prompt
  "png",                    // format: 'png' | 'jpeg'
  0                         // index for variations
);
// Returns: "sunset_over_mountains.png" (or "_1.png" if exists)

// Find an input file across search paths
const result = FileHandler.findInputFile("photo.jpg");
// Returns: { found: true, filePath: "/path/to/photo.jpg", searchedPaths: [...] }
// Or: { found: false, searchedPaths: [...] }

// Save base64 image data to file
const fullPath = await FileHandler.saveImageFromBase64(
  base64Data,    // base64 encoded image string
  outputPath,    // output directory path
  filename       // filename to save as
);

// Read an image file as base64
const base64 = await FileHandler.readImageAsBase64("/path/to/image.png");
```

## ImageGenerator Class

The core ImageGenerator class handles all Gemini API interactions, authentication, prompt building, and response processing.

```typescript
import { ImageGenerator } from './imageGenerator.js';

// Validate authentication (checks environment variables)
// Priority: NANOBANANA_API_KEY > NANOBANANA_GEMINI_API_KEY >
//           NANOBANANA_GOOGLE_API_KEY > GEMINI_API_KEY > GOOGLE_API_KEY
const authConfig = ImageGenerator.validateAuthentication();

// Create generator instance
const generator = new ImageGenerator(authConfig);

// Generate text-to-image
const response = await generator.generateTextToImage({
  prompt: "a watercolor painting of a fox",
  outputCount: 3,
  mode: 'generate',
  styles: ['watercolor', 'oil-painting'],
  variations: ['lighting', 'mood'],
  format: 'separate',
  preview: true
});
// Returns: { success: true, message: "...", generatedFiles: ["/path/to/image.png", ...] }

// Edit an existing image
const editResponse = await generator.editImage({
  prompt: "add sunglasses to the person",
  inputImage: "portrait.jpg",
  mode: 'edit',
  preview: false
});

// Generate story sequence
const storyResponse = await generator.generateStorySequence(
  { prompt: "a seed growing into a tree", outputCount: 4, mode: 'generate' },
  { type: 'process', style: 'consistent', transition: 'smooth' }
);
```

## Summary

Nano Banana provides a comprehensive image generation toolkit for the Gemini CLI with seven specialized tools covering all common image creation and manipulation use cases. The extension excels at text-to-image generation with fine-grained control over artistic styles and variations, making it ideal for generating multiple design iterations, creating consistent visual assets, and rapid prototyping of visual content. The specialized tools for icons, patterns, stories, and diagrams provide domain-specific optimizations that produce better results than generic image generation.

The extension integrates seamlessly with Gemini CLI workflows through the MCP protocol, supporting both specific slash commands (`/generate`, `/edit`, `/restore`, `/icon`, `/pattern`, `/story`, `/diagram`) for precise control and a natural language interface (`/nanobanana`) for flexible interactions. The smart file management system with automatic filename generation, duplicate prevention, and configurable search paths makes it easy to work with generated images across projects. Cross-platform preview support (macOS, Windows, Linux) enables rapid iteration by automatically opening generated images in the system's default viewer when the `--preview` flag is specified.