gemini-google-search-tool
A professional CLI tool and Python library for querying Gemini with Google Search grounding, connecting AI responses to real-time web content with automatic citations.
Table of Contents
About
What is Google Search Grounding?
Google Search grounding connects Gemini models to real-time web content through Google Search. When you query Gemini with grounding enabled, the model:
- Automatically determines if a search would improve the answer
- Generates and executes appropriate search queries
- Processes search results and synthesizes information
- Returns a grounded response with verifiable sources
This reduces hallucinations and provides up-to-date information beyond the model's training cutoff.
Why This CLI-First Tool?
This tool provides a CLI-first architecture designed for both humans and AI agents:
- Agent-Friendly Design: Structured commands and rich error messages enable AI agents (like Claude Code) to reason and act effectively in ReAct loops
- Composable Architecture: JSON output to stdout, logs to stderr—perfect for piping and automation
- Reusable Building Blocks: Commands serve as primitives for Claude Code skills, MCP servers, shell scripts, and custom workflows
- Dual-Mode Operation: Use it as a CLI tool or import as a Python library
- Production Quality: Type-safe (strict mypy), tested (pytest), with comprehensive error handling
Use Cases
- 📚 Real-Time Information: Access current events, news, and recent developments
- 🔍 Fact Verification: Ground responses in verifiable web sources
- 💡 Research Assistance: Gather information from multiple sources automatically
- 🤖 Agent Integration: Build AI workflows with reliable, up-to-date information
- 🔗 Citation Management: Track and display source attributions automatically
Features
Core Capabilities
- Real-Time Web Search: Automatic search execution with multi-query support
- Automatic Citations: Inline citations with source URIs and titles
- Model Selection: Choose between gemini-2.5-flash (fast) or gemini-2.5-pro (powerful)
- Flexible Input: Positional arguments or stdin for automation
- Multiple Output Formats: JSON (default) or markdown with citations
- Verbose Metadata: Full grounding details including search queries and supports
CLI-First Design
- Type Safety: Strict mypy checking, comprehensive type hints
- Error Handling: Rich error messages with suggested fixes
- Composability: JSON to stdout, logs to stderr for piping
- Documentation: Agent-friendly help with inline examples
- Testing: Comprehensive test suite with pytest
Installation
Prerequisites
- Python 3.14 or higher
- uv package manager (recommended)
- Google Gemini API key (get one free)
Install Globally with uv
# Install from source
git clone https://github.com/dnvriend/gemini-google-search-tool.git
cd gemini-google-search-tool
uv tool install .
# Verify installation
gemini-google-search-tool --version
Install with pip
pip install gemini-google-search-tool
Install with mise (recommended for development)
cd gemini-google-search-tool
mise trust
mise install
uv sync
uv tool install .
Shell Completion
Enable tab completion for your shell to improve the CLI experience:
Bash (add to ~/.bashrc):
eval "$(gemini-google-search-tool completion bash)"
Zsh (add to ~/.zshrc):
eval "$(gemini-google-search-tool completion zsh)"
Fish (run once):
mkdir -p ~/.config/fish/completions
gemini-google-search-tool completion fish > ~/.config/fish/completions/gemini-google-search-tool.fish
For more details:
gemini-google-search-tool completion --help