deepviz

A CLI tool for Gemini API Deep Research and NanoBanana (infographics generation).

Features

End-to-end pipeline from Deep Research to NanoBanana infographics generation

• 🔍 Deep Research: Conduct comprehensive research and analysis using Google's Deep Research API
• 🎨 Infographics Generation: Automatically transform research results into visual infographics with NanoBanana
• ⚡ Flexible Workflow: Execute full pipeline, research-only, or image-only modes
• 🔧 Highly Configurable: Customize via command-line flags, environment variables, or config file
• 🌍 Multi-language Support: Generate infographics in any language (default: Japanese)
• 📦 XDG Base Directory Compliant: Follows standard directory conventions

Installation

From source

make build
make install  # Install to ~/.local/bin/

Multi-platform builds

Build for all supported platforms:

make build-all

This creates binaries in dist/ for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64)

Quick Start

1. Set your API key:

   export GEMINI_API_KEY="your-api-key"

2. Run end-to-end pipeline (Research → Infographics):

   deepviz --prompt "Kubernetes best practices"

3. Check the output:

   ls ~/.local/share/deepviz/

Authentication

Gemini API key is required. Set it via environment variable:

export GEMINI_API_KEY="your-api-key"

You can also set it in the configuration file (~/.config/deepviz/config.yaml):

api_key: your-api-key-here

Get your API key from: https://aistudio.google.com/apikey

Usage Examples

Full pipeline (Research → Image generation)

deepviz --prompt "Kubernetes best practices"

Research only

deepviz --research-only --prompt "PostgreSQL performance tuning"

Image generation only

deepviz --image-only --prompt "Microservices architecture overview diagram"

Using a prompt file

deepviz --file prompt.txt

Generate infographics in English

export DEEPVIZ_IMAGE_LANG="English"
deepviz --prompt "Docker container best practices"

Custom aspect ratio and size

deepviz --prompt "System architecture" --aspect-ratio 1:1 --image-size 4K

Verbose logging for debugging

deepviz --verbose --prompt "Cloud security"

Configuration Management

Initialize configuration file

deepviz config init

Show current configuration

deepviz config show

Configuration file location

$XDG_CONFIG_HOME/deepviz/config.yaml (default: ~/.config/deepviz/config.yaml)

Configuration file example

# Output directory
output_dir: ~/.local/share/deepviz

# API authentication
api_key: your-api-key-here

# Deep Research settings
deep_research_agent: deep-research-pro-preview-12-2025
poll_interval: 10
poll_timeout: 600

# Image generation settings
model: gemini-3-pro-image-preview
aspect_ratio: "16:9"
image_size: 2K
image_lang: Japanese
auto_open: true

Configuration priority (highest to lowest)

1. Command-line flags
2. Environment variables
3. Configuration file (config.yaml)
4. Default values

Command-Line Options

Basic Options

Option	Short	Description	Default
--prompt	-p	Inline prompt text	-
--file	-f	Read prompt from file	-
--output	-o	Output directory	~/.local/share/deepviz
--verbose	-v	Enable verbose logging (DEBUG level)	false

Workflow Control

Option	Description	Default
--research-only	Execute research only (skip image generation)	false
--no-image	Alias for --research-only	false
--image-only	Execute image generation only (skip research)	false
--no-open	Disable auto-open after image generation	false

Image Generation Options

Option	Description	Default	Available Values
--model	Image generation model	gemini-3-pro-image-preview	gemini-3-pro-image-preview, gemini-2.0-flash-exp
--aspect-ratio	Image aspect ratio	16:9	16:9, 4:3, 1:1, 9:16, 3:4
--image-size	Image resolution	2K	2K (2048x1152), 4K (3840x2160)

Subcommands

Command	Description
config show	Display current configuration
config init	Initialize configuration file
completion [bash|zsh|fish|powershell]	Generate shell completion script

Environment Variables

Basic Configuration

Environment Variable	Description	Default
GEMINI_API_KEY or DEEPVIZ_API_KEY	Gemini API key (required)	-
DEEPVIZ_OUTPUT_DIR	Output directory	~/.local/share/deepviz
GEMINI_MODEL or DEEPVIZ_MODEL	Image generation model	gemini-3-pro-image-preview
DEEPVIZ_ASPECT_RATIO	Image aspect ratio	16:9
DEEPVIZ_IMAGE_SIZE	Image resolution	2K
DEEPVIZ_IMAGE_LANG	Language for image generation	Japanese
DEEPVIZ_AUTO_OPEN	Auto-open image after generation	true

Advanced Configuration

Environment Variable	Description	Default
GEMINI_DEEP_RESEARCH_AGENT or DEEPVIZ_DEEP_RESEARCH_AGENT	Deep Research agent name	deep-research-pro-preview-12-2025
DEEPVIZ_POLL_INTERVAL	Polling interval in seconds	10
DEEPVIZ_POLL_TIMEOUT	Polling timeout in seconds	600

Output

Output directory structure

Default: $XDG_DATA_HOME/deepviz (typically ~/.local/share/deepviz)

~/.local/share/deepviz/
├── research/
│   └── 20251224_103045.md              # Research result (Markdown)
├── images/
│   └── 20251224_103045.png             # Generated infographics
├── responses/
│   └── 20251224_103045_image.json      # Image generation API response (JSON)
└── logs/
    └── 20251224_103045.log              # Execution log (JSON)

File naming

All output files use timestamp format: YYYYMMDD_HHMMSS (e.g., 20251224_103045)

Custom output directory

You can customize the output directory:

# Via command-line flag
deepviz --output ./my-output --prompt "Custom output location"

# Via environment variable
export DEEPVIZ_OUTPUT_DIR="./my-output"
deepviz --prompt "Custom output location"

Shell Completion

Generate shell completion scripts:

Bash

source <(deepviz completion bash)
echo "source <(deepviz completion bash)" >> ~/.bashrc

Zsh

source <(deepviz completion zsh)
echo "source <(deepviz completion zsh)" >> ~/.zshrc

Fish

deepviz completion fish | source
deepviz completion fish > ~/.config/fish/completions/deepviz.fish

PowerShell

deepviz completion powershell | Out-String | Invoke-Expression

Development

make fmt       # Format code
make lint      # Static analysis
make test      # Run tests
make coverage  # Coverage report
make help      # Show help