Gemini Research CLI

Deep Research Agent CLI — A command-line interface for Gemini's Deep Research Agent (April 2026 models). Autonomously plans, executes, and reports on complex research topics.

Perfect for deep dives into technical topics, market analysis, competitor research, and creating comprehensive knowledge bases from scratch.

✨ Features

• 🧠 Autonomous Planning — Defaults to a two-stage flow: gemini-3.1-pro-preview drafts a plan you can preview, then the Deep Research Agent executes it. Mimics the Gemini Web experience. Fallback chain: gemini-3-pro-preview → gemini-3-flash-preview → gemini-2.0-flash.
• 🚀 One-shot via --no-plan — Skip the pre-planner stage and let the Deep Research Agent plan and execute natively in one call (faster, cheaper, no preview).
• 🆕 April 2026 models — Defaults to deep-research-preview-04-2026 (~250k input tokens / ~80 queries). Add --max for deep-research-max-preview-04-2026 (~900k tokens / ~160 queries).
• 📡 Live streaming — --stream renders the research with thought summaries over SSE and auto-resumes from the last event_id on network drops.
• 🔁 Follow-ups — --followup <id> asks a clarifying question against a completed interaction via previous_interaction_id.
• 📚 File Search — --file-search-store <name> grounds the agent in your own File Search store (one or more, repeatable).
• 🖼️ Multimodal input — --attach <uri> attaches an image or PDF by URI (or data: URI). Repeatable.
• 🔄 Auto-Polling — Handles long-running background tasks with automatic status updates and 5xx retry.
• 📝 Markdown Export — Saves the final report to report-<slug>-<ts>.md (or --out <path>).
• 🚦 Interactive or scripted — Interactive prompt by default; -y skips confirmation for automation; -f reads the topic from a file.

📦 Quick Start

Prerequisites

• Node.js (v18+)
• Gemini API Key with access to the deep-research-* agents in the Interactions API

Installation

1. Clone the repository:

git clone https://github.com/abe238/gemini-deep-research.git
cd gemini-deep-research

2. Install dependencies:

npm install

3. Configure Environment:

cp .env.example .env
# Edit .env and paste your GEMINI_API_KEY

4. Build:

npm run build

5. Link (Optional):

npm link
# now you can run `gemini-research` from anywhere

Basic Usage

# Default: plan preview + auto-approve + research + save .md
gemini-research -y "The future of quantum computing in 2025"

# True one-shot — no pre-planner, agent plans and executes natively
gemini-research -y --no-plan "The future of quantum computing in 2025"

# Watch the research live (with thought summaries)
gemini-research -y --stream "The future of quantum computing in 2025"

# Comprehensive variant (more tokens / more queries)
gemini-research -y --max "Global EV battery supply chains, 2024–2026"

# Research from a file
gemini-research -y -f prompt.txt

# Pipe input
cat prompt.txt | gemini-research -y

# Follow-up on a previous report
gemini-research --followup <INTERACTION_ID> "Expand on the supply chain section."

# Ground the research in your own data
gemini-research -y --file-search-store fileSearchStores/my-store "Compare our Q1 report to public news"

# Multimodal: attach a PDF or image (URI form; use data: URI for local files)
gemini-research -y --attach https://example.com/report.pdf --attach-mime application/pdf "Summarize and contrast with public coverage"

# Validate the API contract without running a full research job
gemini-research -y --dry-run "Test prompt"

The CLI will:

1. (Default mode) Generate and display a research plan for review/approval.
2. Submit the plan (or raw topic, with --no-plan) to the Deep Research Agent.
3. Stream the agent's progress (--stream) or poll every 10s in the background.
4. Save the final report as report-<slug>-<timestamp>.md in the current directory.

⚙️ Options

Flag	Description
topic	Research topic (first positional argument)
-f, --file <path>	Read the topic from a local file
-y, --yes	Auto-approve the plan (one-shot mode)
--no-plan	Skip the gemini-3.1-pro pre-planner; raw topic → Deep Research Agent (native planning, one round-trip)
--max	Use deep-research-max-preview-04-2026 (comprehensive)
--model <id>	Override the agent model id explicitly
--stream	Stream the run live (SSE) with thought summaries and auto-reconnect via last_event_id
--no-thoughts	Disable thinking_summaries when streaming
--collab-plan	Experimental: sets agent_config.collaborative_planning=true so the agent exposes its own plan (replaces the gemini-3-pro pre-planner)
--followup <id>	Treat input as a follow-up to a completed interaction (previous_interaction_id)
--file-search-store <names...>	Attach one or more File Search stores (e.g. fileSearchStores/my-store)
--attach <uris...>	Attach an image/PDF by URI (or data: URI). Repeatable.
--attach-mime <mime>	MIME type for --attach (default image/jpeg; use application/pdf for PDFs)
--api-revision <rev>	Pin the Api-Revision header (e.g. 2026-05-20)
--out <path>	Output file path (default report-<slug>-<ts>.md in cwd)
--print	After saving, also print the report to stdout
--dry-run	Generate plan + create interaction, then exit (validates contract without running)
-V, --version	Print version
-h, --help	Print help
.env	Stores GEMINI_API_KEY (gitignored)

🏗️ Project Structure

gemini-deep-research/
├── dist/                  # Compiled JavaScript
├── docs/                  # Documentation
├── src/
│   └── cli.ts             # CLI + Interactions API client
├── .env                   # API Key (gitignored)
├── package.json
└── README.md

🛠️ Troubleshooting

• 404 Model Not Found — Ensure your GEMINI_API_KEY has access to deep-research-preview-04-2026 / deep-research-max-preview-04-2026 in the Interactions API. The older deep-research-pro-preview-12-2025 was the December 2025 preview and may eventually be deprecated.
• ENAMETOOLONG — The default slug is truncated to 50 chars to avoid this. Use --out to set a custom path.
• Timeout / Network Error — Polling retries transient errors; --stream reconnects via last_event_id. If a run sits idle >20 minutes, check connectivity.
• --collab-plan hangs — Experimental flag. The native collaborative-planning handshake may require explicit approval over a follow-up call; if it stalls, fall back to --no-plan or the default flow.

🤝 Contributing

npm run build

PRs welcome.

📄 License

ISC.

---

About the Builder

Hola. I'm Abe Diaz. By day, I'm Sr. Manager of Disaster Relief at Amazon, leading a team that uses AI and logistics to deliver 26+ million relief items and response technology across 200+ disasters worldwide. On weekends, I build artisanal developer tools like this :-P

• 💼 linkedin.com/in/abediaz
• 🌐 abediaz.ai
• 🐙 github.com/abe238
• 🐦 @abe238

Other Open Source Projects

Project	Description
gg-deploy	Domain → GitHub Pages in 60 seconds
aipm-resume-analyzer	Resume analysis against AI PM frameworks
project-kickoff	Scaffold AI production-ready projects