nb (nanobanana)

Free AI-powered image generation from your terminal

Generate, edit, and enhance images using Google's Gemini API with simple natural language commands.

Why nb?

• Free to Use - Leverage Google's Gemini API (free tier available)
• Lightning Fast - Powered by Gemini 2.5 Flash Image model
• 8 Specialized Commands - Generate, edit, restore, icons, patterns, stories, diagrams, and more
• Smart Image Processing - Built-in WebP conversion and quality optimization
• Natural Language - Just describe what you want in plain English
• 10+ Art Styles - Photorealistic, watercolor, anime, pixel-art, and more
• Multiple Aspect Ratios - Perfect for any use case from social media to print
• Zero Config - Just add your API key and start creating

Quick Start

Try it instantly (no installation required)

# Generate your first AI image in seconds
npx nanobanana-cli generate "sunset over mountains"

Install globally for faster access

# Using npm
npm install -g nanobanana-cli

# Using Bun (recommended)
bun install -g nanobanana-cli

# Then use the short command
nb generate "cyberpunk city at night"

Installation & Setup

1. Get Your Free Gemini API Key

Visit Google AI Studio and get your free API key (no credit card required).

2. Set Your API Key

# On macOS/Linux
export GEMINI_API_KEY=your_api_key_here

# On Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key_here"

# Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export GEMINI_API_KEY=your_api_key_here' >> ~/.zshrc

3. Create Your First Image

nb generate "a majestic dragon flying over a castle"

Your image will be saved in the ./output folder automatically!

Commands & Examples

Generate Images

Create stunning AI images from text descriptions with style options and aspect ratios.

# Basic image generation
nb generate "sunset over mountains"

# Generate multiple images at once
nb generate "futuristic robot" --num-images 4

# Apply artistic styles
nb generate "forest landscape" --style watercolor
nb generate "city street" --style anime
nb generate "portrait" --style photorealistic

# Custom aspect ratios for different platforms
nb generate "mobile wallpaper" --aspect-ratio 9:16
nb generate "youtube thumbnail" --aspect-ratio 16:9
nb generate "instagram post" --aspect-ratio 1:1

# Advanced: combine all options
nb generate "cyberpunk street scene at night" \
  --num-images 3 \
  --style digital-art \
  --aspect-ratio 16:9 \
  --format webp \
  --quality 85

Available Styles: photorealistic, watercolor, oil-painting, anime, sketch, digital-art, 3d-render, pixel-art, minimalist, abstract

Aspect Ratios: 1:1, 2:3, 3:2, 4:3, 5:4, 9:16, 16:9, 21:9

Edit Images

Transform existing images with natural language instructions.

# Add elements to images
nb edit photo.jpg "add a rainbow in the sky"
nb edit landscape.png "add snow to the mountains"

# Remove unwanted elements
nb edit photo.jpg "remove the person in the background"
nb edit image.png "remove watermark"

# Change image style
nb edit photo.jpg "make it look like a watercolor painting"
nb edit portrait.png "convert to black and white with vintage film grain"

# Advanced editing with masks
nb edit input.png "change the sky to sunset" --mask sky-mask.png

# Save optimized for web
nb edit photo.jpg "enhance colors and contrast" \
  --format webp \
  --quality 80

Restore & Enhance Images

Bring old or low-quality images back to life.

# Basic image restoration
nb restore old-photo.jpg

# High-quality enhancement
nb restore vintage-photo.jpg --quality high

# Denoise and enhance
nb restore noisy-image.png --denoise

# Restore and optimize
nb restore old-picture.jpg \
  --quality high \
  --format webp \
  --image-quality 90

Generate App Icons

Create professional app icons in multiple sizes instantly.

# Standard icon set
nb icon "minimalist rocket logo"

# Custom sizes
nb icon "coffee cup app icon" --sizes 256,512

# All common sizes (default)
nb icon "music note logo" --sizes 256,512,1024

# Generate as WebP for modern platforms
nb icon "mountain peak logo" \
  --sizes 256,512 \
  --format webp \
  --quality 90

Perfect for: iOS apps, Android apps, web favicons, PWAs

Create Seamless Patterns

Generate tileable patterns and textures for backgrounds and designs.

# Simple pattern
nb pattern "geometric hexagons"

# Custom color palette
nb pattern "floral design" --colors "pink,lavender,white"

# Control pattern density
nb pattern "stars and moons" --density high
nb pattern "subtle dots" --density low

# Non-tileable backgrounds
nb pattern "abstract watercolor splash" --tileable false

# Web-optimized pattern
nb pattern "circuit board design" \
  --colors "green,black" \
  --format webp \
  --quality 75

Great for: Website backgrounds, textile design, game assets, social media

Visual Storytelling

Generate sequential images for comics, storyboards, or presentations.

# 4-scene story
nb story "a seed growing into a blooming flower"

# Custom scene count
nb story "day to night transition over a city" --scenes 6

# Cinematic widescreen
nb story "hero's journey through mystical lands" \
  --scenes 5 \
  --aspect-ratio 21:9

# Instagram story format
nb story "morning coffee routine" \
  --scenes 4 \
  --aspect-ratio 9:16

Perfect for: Storyboards, comics, presentations, social media stories

Technical Diagrams

Create diagrams, flowcharts, and technical visualizations.

# Flowcharts
nb diagram "user authentication flow" --type flowchart
nb diagram "checkout process with payment gateway" --type flowchart

# Architecture diagrams
nb diagram "microservices architecture with API gateway" --type architecture
nb diagram "cloud infrastructure on AWS" --type architecture

# Network diagrams
nb diagram "home office network setup" --type network

# Database schemas
nb diagram "e-commerce database schema" --type erd

# Mind maps
nb diagram "project planning brainstorm" --type mindmap

# Sequence diagrams
nb diagram "API request response cycle" --type sequence

Diagram Types: flowchart, sequence, architecture, network, erd, mindmap

Perfect for: Documentation, presentations, planning, teaching

Natural Language Interface

Can't remember the exact command? Just describe what you want!

# The AI will figure out the best approach
nb "create a beautiful sunset landscape"
nb "make a logo with a rocket ship"
nb "generate a futuristic robot"
nb "photorealistic mountain scenery at golden hour"

Real-World Use Cases

For Content Creators

• Blog Graphics: nb generate "modern minimalist blog header" --aspect-ratio 21:9
• Social Media: nb generate "engaging instagram post about coffee" --aspect-ratio 1:1
• YouTube Thumbnails: nb generate "exciting tech review thumbnail" --aspect-ratio 16:9

For Developers

• App Icons: nb icon "clean todo app icon" --sizes 256,512,1024
• Placeholder Images: nb generate "user avatar placeholder" --num-images 10
• UI Mockups: nb generate "modern dashboard interface" --style minimalist

For Designers

• Concept Art: nb generate "sci-fi vehicle design" --style digital-art --num-images 5
• Patterns: nb pattern "art deco geometric" --colors "gold,black,white"
• Mood Boards: nb generate "cozy cafe interior" --num-images 6 --style photorealistic

For Educators

• Diagrams: nb diagram "water cycle" --type flowchart
• Visual Aids: nb generate "ancient Roman architecture" --style photorealistic
• Storyboards: nb story "photosynthesis process" --scenes 4

Image Processing Options

All commands support advanced image processing for optimal file sizes and quality.

Format Conversion

# WebP (smallest, best for web)
nb generate "landscape" --format webp --quality 75

# JPEG (balanced)
nb generate "portrait" --format jpg --quality 85

# PNG (lossless, largest)
nb generate "logo" --format png --quality 90

File Size Examples

• Original PNG (1024x1024): ~1.0 MB
• WebP Quality 75: ~27 KB (97% smaller!)
• JPEG Quality 80 (1024x1024): ~100 KB

Output & Metadata

All generated images are automatically saved to ./output (customizable with -o flag).

Each image includes:

• Image file: PNG, JPG, or WebP format
• Metadata JSON: Contains prompt, model info, timestamp, and generation parameters

output/
├── nb-generate-2025-10-04T14-30-15-1.png
├── nb-generate-2025-10-04T14-30-15-1.json
├── nb-edit-2025-10-04T14-32-20.webp
└── nb-edit-2025-10-04T14-32-20.json

Customize output directory:

nb generate "logo" --output ./my-images

Pro Tips & Tricks

Batch Generation

# Generate multiple variations
nb generate "logo concept" --num-images 10

Consistent Results

# Use seed for reproducible images
nb generate "character design" --seed 42

Web Optimization

# Perfect for web - small size, high quality
nb generate "hero image" \
  --format webp \
  --quality 75 \
  --aspect-ratio 16:9

Creative Prompts

# Be specific for better results
nb generate "a serene Japanese garden with cherry blossoms, koi pond, and stone lanterns at sunset, photorealistic, high detail"

# Combine styles
nb generate "cyberpunk samurai" --style "digital-art"

FAQ

Q: Is Gemini API really free?

A: Yes! Google offers a generous free tier for the Gemini API. Perfect for personal projects and testing.

Q: What image sizes can I generate?

A: Images are generated at different sizes based on aspect ratio. 1:1 generates 1024x1024, 16:9 generates 1344x768, etc. Use --aspect-ratio to control dimensions.

Q: Can I use generated images commercially?

A: Check Google's Gemini API Terms of Service for the latest usage guidelines.

Q: How do I update to the latest version?

A: Run npm update -g nanobanana-cli or bun update -g nanobanana-cli

Q: Where are my images saved?

A: By default in ./output folder. Use -o flag to change the location.

Q: Can I use this without installing?

A: Yes! Use npx nanobanana-cli [command] to run without global installation.

Troubleshooting

API Key Not Found

# Make sure your API key is set
echo $GEMINI_API_KEY

# If empty, set it again
export GEMINI_API_KEY=your_api_key_here

Images Not Generating

• Check your API key is valid at Google AI Studio
• Verify you haven't exceeded free tier limits
• Try a simpler prompt first

Command Not Found

# If 'nb' command not found after global install
npm list -g nanobanana-cli

# Try reinstalling
npm install -g nanobanana-cli --force

Sharp Library Errors (macOS M1/M2)

# Reinstall sharp with native bindings
npm rebuild sharp

Contributing

We welcome contributions! Here's how you can help:

• Report bugs at GitHub Issues
• Suggest features or improvements
• Improve documentation
• Star the repo if you find it useful!

License

MIT © Dipendra Sharma

Acknowledgements

This project was inspired by nanobanana by the Gemini CLI Extensions community.

Developed with assistance from Claude Code, Anthropic's AI-powered coding assistant.

Built with:

• Google Gemini API - AI image generation
• Bun - Fast TypeScript runtime
• Sharp - High-performance image processing
• Commander.js - CLI framework

Show Your Support

If you find nb useful, please:

• Star this repo on GitHub
• Check it out on npm
• Share it with others
• Tell your friends!

Made with care for developers, designers, and creators

Report Bug · Request Feature · Documentation