Deep Research Agent CLI - A powerful command-line interface for Gemini's Deep Research Agent, capable of autonomously planning, executing, and reporting on complex research topics.
Perfect for deep dives into technical topics, market analysis, competitor research, and creating comprehensive knowledge bases from scratch.
- 🧠 Autonomous Planning - Leverages Gemini 3 Flash Preview (with fallback to 2.0) to create detailed research plans before calling Deep Research Agent, this mimics the Gemini Web experience
- 📚 Deep Research - Executes multi-step research using Google Search and internal reasoning
- 🔄 Auto-Polling - Handles long-running background tasks with automatic status updates
- ⚡ Resilient - Auto-recovers from transient network issues during polling
- 📝 Markdown Export - Saves formatted reports directly to your local machine
- 🛡️ Safe Filenames - Automatically sanitizes output filenames for cross-platform compatibility
- 🚦 Interactive CLI - Simple interactive mode or direct command-line arguments
- 🎯 One-Shot Mode - Skip confirmation prompts with
-yflag for automation scripts
- Node.js (v18+)
- Gemini API Key (Interactions API enabled)
- Clone the repository:
git clone https://github.com/abe238/gemini-deep-research.git
cd gemini-deep-research- Install dependencies:
npm install- Configure Environment: Copy the example environment file and add your API key:
cp .env.example .env
# Edit .env and paste your GEMINI_API_KEY- Build the project:
npm run build- Link (Optional):
Allows you to run
gemini-researchfrom anywhere.
npm link# Research a specific topic directly
gemini-research "The future of quantum computing in 2025"
# One-shot mode (auto-approve plan, no confirmation prompt)
gemini-research -y "The future of quantum computing in 2025"
# Research from a file (Best for long, complex prompts)
gemini-research -f prompt.txt
# Combine file input with auto-approve for fully automated research
gemini-research -y -f prompt.txt
# Research from piped input
cat prompt.txt | gemini-research
# Run in interactive mode
gemini-research
# Show help
gemini-research --helpThe CLI will:
- Generate a research plan for your review (Yes/No to proceed).
- Initialize the Deep Research Agent.
- Start the research process in the background.
- Poll for progress (research can take 10+ minutes).
- Save the final report as a Markdown file.
| Flag/Option | Description |
|---|---|
topic |
The research topic (pass as first argument) |
-f, --file |
Read the research topic from a local file |
-y, --yes |
Auto-approve the research plan without confirmation (one-shot mode) |
-V, --version |
Output the version number |
-h, --help |
Display help for command |
.env |
File to store your GEMINI_API_KEY |
gemini-deep-research/
├── dist/ # Compiled JavaScript files
├── docs/ # Documentation
├── src/
│ └── cli.ts # Main CLI & API logic
├── .env # API Key configuration
├── package.json # Dependencies & Scripts
└── README.md # This documentation
- 404 Model Not Found: Ensure you are using a valid
GEMINI_API_KEYthat has access to thedeep-research-pro-preview-12-2025model in the Interactions API. - ENAMETOOLONG: The CLI automatically truncates filenames to 50 characters to prevent this, but ensure your filesystem supports standard long filenames.
- Timeout/Network Error: The tool is designed to be resilient to transient network drops. If the process hangs for >20 minutes without updates, check your connection and strict firewall settings.
Contributions are welcome! Please run the build script before submitting a PR.
npm run buildThis project is licensed under the ISC License.
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
| 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 |