NanoBanana CLI

A command-line tool for AI image generation and editing using NanoBanana (Gemini-powered) through the AceDataCloud API.

Generate and edit AI images directly from your terminal — no MCP client required.

Features

• Image Generation — Generate images from text prompts with multiple models
• Image Editing — Edit, combine, and transform images with AI
• Multiple Models — nano-banana (fast), nano-banana-2 (improved), nano-banana-2.1 (efficient, 1K/2K/4K), nano-banana-pro (best, 4K)
• Flexible Output — Aspect ratios (1:1, 16:9, 9:16, etc.) and resolutions (1K/2K/4K)
• Task Management — Query tasks, batch query, wait with polling
• Rich Output — Beautiful terminal tables and panels via Rich
• JSON Mode — Machine-readable output with --json for piping

Quick Start

1. Get API Token

Get your API token from AceDataCloud Platform:

1. Sign up or log in
2. Navigate to the NanoBanana API page
3. Click "Acquire" to get your token

2. Install

# Install with pip
pip install nano-banana-pro-cli

# Or with uv (recommended)
uv pip install nano-banana-pro-cli

# Or from source
git clone https://github.com/AceDataCloud/NanoBananaCli.git
cd NanoBananaCli
pip install -e .

3. Configure

# Set your API token
export ACEDATACLOUD_API_TOKEN=your_token_here

# Or use .env file
cp .env.example .env
# Edit .env with your token

4. Use

# Generate an image from a prompt
nano-banana-pro generate "A cat sitting on a windowsill at sunset, warm lighting"

# Generate with specific model and aspect ratio
nano-banana-pro generate "Product photo of a watch" -m nano-banana-pro -a 16:9 -r 4K

# Generate and edit with Nano Banana 2.1
nano-banana-pro generate "A blue ceramic vase on a cream background" -m nano-banana-2.1 -r 2K
nano-banana-pro edit "Make the vase green" -i https://example.com/photo.jpg -m nano-banana-2.1 -r 4K

# Edit an image
nano-banana-pro edit "Make it look like an oil painting" -i https://example.com/photo.jpg

# Virtual try-on (combine person + clothing)
nano-banana-pro edit "Let this person wear this T-shirt" -i person.jpg -i shirt.jpg

# Check task status
nano-banana-pro task <task-id>

# Wait for completion with polling
nano-banana-pro wait <task-id> --interval 5

# List available models
nano-banana-pro models

Commands

Image Generation & Editing

Task Management

Utilities

Global Options

--token TEXT    API token (or set ACEDATACLOUD_API_TOKEN env var)
--version       Show version
--help          Show help message

Most commands support:

--json          Output raw JSON (for piping/scripting)
--model TEXT    NanoBanana model version (default: nano-banana)

Scripting & Piping

The --json flag outputs machine-readable JSON suitable for piping:

# Generate and extract task ID
TASK_ID=$(nano-banana-pro generate "a red circle" --json | jq -r '.task_id')

# Wait for completion and get image URL
nano-banana-pro wait $TASK_ID --json | jq -r '.data[0].image_url'

# Batch generate from a file of prompts
while IFS= read -r prompt; do
  nano-banana-pro generate "$prompt" --json >> results.jsonl
done < prompts.txt

Available Models

Specify -m nano-banana-2.1 explicitly; the default remains nano-banana. Both generation and editing support -r 1K, -r 2K, or -r 4K. There is no nano-banana-2.1:official variant.

Aspect Ratios

Configuration

Environment Variables

Development

Setup Development Environment

# Clone repository
git clone https://github.com/AceDataCloud/NanoBananaCli.git
cd NanoBananaCli

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

Run Tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=nanobanana_cli

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy nanobanana_cli

Build & Publish

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

Docker

# Pull the image
docker pull ghcr.io/acedatacloud/nano-banana-pro-cli:latest

# Run a command
docker run --rm -e ACEDATACLOUD_API_TOKEN=your_token \
  ghcr.io/acedatacloud/nano-banana-pro-cli generate "A beautiful sunset"

# Or use docker-compose
docker compose run --rm nano-banana-pro-cli generate "A beautiful sunset"

Project Structure

NanoBananaCli/
├── nanobanana_cli/            # Main package
│   ├── __init__.py
│   ├── __main__.py            # python -m nanobanana_cli entry point
│   ├── main.py                # CLI entry point
│   ├── core/                  # Core modules
│   │   ├── client.py          # HTTP client for NanoBanana API
│   │   ├── config.py          # Configuration management
│   │   ├── exceptions.py      # Custom exceptions
│   │   └── output.py          # Rich terminal formatting
│   └── commands/              # CLI command groups
│       ├── image.py           # Image generation & editing commands
│       ├── task.py            # Task management commands
│       └── info.py            # Info & utility commands
├── tests/                     # Test suite
├── .github/workflows/         # CI/CD (lint, test, publish to PyPI)
├── Dockerfile                 # Container image
├── deploy/                    # Kubernetes deployment configs
├── .env.example               # Environment template
├── pyproject.toml             # Project configuration
└── README.md

NanoBanana CLI vs MCP NanoBanana

Both tools use the same AceDataCloud API and share the same API token.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

Development Requirements

• Python 3.10+
• Dependencies: pip install -e ".[all]"
• Lint: ruff check . && ruff format --check .
• Test: pytest

License

This project is licensed under the MIT License — see the LICENSE file for details.