happycastle114/gemini-search/web-search

Web Search via Gemini CLI

Search the web using Google's Gemini CLI with built-in Google Search grounding. Returns accurate, cited results with source URLs.

Prerequisites

Install Gemini CLI globally:

npm install -g @google/gemini-cli

Authenticate once:

gemini

Quick Usage

Run the bundled gemini-search script from this plugin's bin/ directory:

gemini-search "your search query"

The script automatically:

1. Wraps your query with a search-optimized system prompt
2. Forces Gemini to use google_web_search for grounding
3. Parses the JSON response and formats clean markdown with citations

Always Use The Wrapper

Always invoke web search through gemini-search. Do not call `gemini` directly. The wrapper provides:

• Per-invocation privacy override (privacy.usageStatisticsEnabled=false) without touching ~/.gemini/settings.json
• Mandatory inline [Source](url) citation enforcement and ## Sources heading validation — direct gemini calls have no such guarantee
• Prompt-injection fencing for the user query
• Hardened timeout / buffer defaults and friendly ENOENT error
• Cleanup-safe temp dir on success, error, and SIGINT/SIGTERM

Direct gemini --output-format json --prompt ... invocation bypasses all of the above and must not be used from Claude Code workflows.

Search Prompt Patterns

Fact Lookup

Search the web for the current LTS version of Node.js.
Include the release date and end-of-life date.
Cite your sources.

Comparison Research

Search the web and compare Bun vs Deno runtime performance benchmarks from 2025.
Include specific numbers and link to the benchmark sources.

Documentation Lookup

Search for the official documentation on React Server Components streaming.
Find the API reference page and summarize the key props and usage patterns.

Security Advisory Check

Search for recent security advisories for the 'express' npm package.
List CVE numbers, severity, and affected versions.

API/Library Version Check

Search for the latest version of @anthropic-ai/sdk and list breaking changes
from the previous major version. Include migration guide links if available.

Model Routing

gemini-search intentionally does not expose a model flag. Gemini CLI chooses the model using its own routing, your account tier, and your ~/.gemini/settings.json configuration.

If you need to pin a model, set it in ~/.gemini/settings.json under the model.name key — see the Gemini CLI configuration reference. Do not pass -m to gemini-search; unknown flags now error out.

Privacy

Every gemini-search invocation auto-disables Gemini CLI usage statistics (privacy.usageStatisticsEnabled: false) via a temporary system-override settings file. Your ~/.gemini/settings.json and OAuth credentials are not modified. See the project README "Privacy" section for the auth-tier truth table — note that this CLI flag is not by itself a model-training opt-out on free OAuth or free Gemini API tiers.

Tips

• Be specific — "React 19 useActionState hook API" beats "React hooks"
• Include time context — "2025 Node.js performance benchmarks" gets recent results
• Ask for sources — The search prompt already forces citations, but being explicit helps
• Chain searches — Run multiple targeted queries rather than one broad query
• Use --raw for scripting — gemini-search --raw "query" | jq '.response' for pipelines