Agentic AI Tools
Gemini CLI Setup Guide
Set up Google's official Gemini CLI - an open-source agentic AI assistant with 1M token context and generous free tier, perfect for research workflows.
Overview
Gemini CLI is Google's official open-source AI agent that brings the power of Gemini models directly into your terminal. Launched in June 2025, it's built specifically for agentic workflows with massive context windows and generous free tier limits.
Key Benefits for Research:
- 1 million token context: Load entire dissertations or 50+ papers at once
- Free tier: 60 requests/min, 1,000 requests/day (no credit card needed!)
- Open source: Apache 2.0 license, full transparency
- MCP integration: Connect to Zotero, filesystems, web search
- Project memory: GEMINI.md for research protocols
- ReAct loop: Reason → Act → Observe for complex tasks
Info
Why Gemini CLI? The 1M token context window means you can load your ENTIRE literature collection in a single session. Perfect for comprehensive synthesis tasks that require seeing the big picture across dozens of papers simultaneously!
Official Resources:
- GitHub Repository (8.6K stars)
- Official Documentation
- Announcement Blog
Step 1: Installation
1.1 Prerequisites
System Requirements:
- Node.js 18 or newer
- Terminal/command-line access
- Google account (for free API key)
Check Node.js:
node --version1.2 Install Gemini CLI
Via npm:
npm install -g @google/gemini-cliVerify installation:
gemini --versionFirst launch:
cd ~/your-research-project
geminiTip
GitHub Releases: Check latest releases for version updates and changelog.
Step 2: Get Free Google AI Studio API Key
2.1 Create API Key
- Visit Google AI Studio
- Sign in with your Google account
- Click "Create API key"
- Copy the key (starts with
AIza...)
Free tier limits:
- 60 requests per minute
- 1,000 requests per day
- Resets daily at midnight Pacific Time
- No credit card required!
2.2 Configure API Key
Set environment variable:
export GOOGLE_API_KEY="AIza..."
# Make permanent (add to ~/.zshrc or ~/.bashrc):
echo 'export GOOGLE_API_KEY="AIza..."' >> ~/.zshrc
source ~/.zshrcVerify:
echo $GOOGLE_API_KEY # Should display your keyStep 3: First Steps with Gemini CLI
3.1 Launch and Test
Start Gemini CLI:
cd ~/Research-Project
geminiTest with a simple prompt:
What are the key components of a systematic literature review?If you get a response, you're all set!
3.2 Project Memory with GEMINI.md
Create GEMINI.md in your project root:
# Research Project: [YOUR TOPIC]
## Project Goal
[Describe your research objective]
## File Structure
- /literature/ - Papers in markdown format
- /analysis/ - Data and synthesis
- /drafts/ - Paper sections
- /outputs/ - Final exports
## Research Protocol
- Citation style: APA 7th Edition
- Analysis approach: [Your methodology]
- Quality checks: [Your criteria]
## Key Context
- Research domain: [Your field]
- Theoretical framework: [Your approach]
- Target audience: [Journal or academic level]Gemini CLI reads this at the start of every conversation!
Step 4: Leveraging the 1M Context Window
4.1 Load Entire Literature Corpus
The killer feature: Analyze 50+ papers simultaneously
"Analyze all papers in @/literature/ (contains 47 papers).
Identify the 5 most common theoretical frameworks used.
For each framework, list which papers use it and how
their applications differ."Why this matters:
- Traditional LLMs: 200K context (5-10 papers max)
- Gemini CLI: 1M context (50+ papers easily!)
- See patterns across your ENTIRE literature set
4.2 Dissertation-Scale Analysis
Load entire dissertation draft:
"Review my complete dissertation in @/drafts/ (6 chapters, ~40K words).
Check for:
- Argument coherence across chapters
- Citation coverage and balance
- Transition quality between sections
- Theoretical consistency throughout"4.3 Comprehensive Synthesis
Multi-paper synthesis:
"Using Sequential Thinking, synthesize all 47 papers in @/literature/:
1. Extract all theoretical constructs mentioned
2. Map relationships between constructs
3. Identify consensus vs contradictory findings
4. Propose an integrated framework
5. Suggest future research directions"Step 5: MCP Integration
5.1 Built-in MCP Support
Gemini CLI includes MCP integration out of the box!
Configure MCP servers:
Create ~/.gemini/config.json:
{
"mcpServers": {
"zotero": {
"command": "zotero-mcp",
"args": [],
"env": {
"ZOTERO_LOCAL": "true"
}
},
"filesystem": {
"command": "mcp-server-filesystem",
"args": ["/Users/[username]/Research"]
}
}
}5.2 Use MCP Tools in Prompts
Search Zotero from terminal:
"Search my Zotero library for papers on organizational scaling
published after 2023. Show titles, authors, and citation keys."Filesystem operations:
"Read all markdown files in @/literature/ and create a master
bibliography in APA 7th format."Tip
For complete MCP setup, see MCP Explorer Guide and Zotero Setup Guide.
Step 6: Custom Slash Commands
6.1 Create Commands Directory
mkdir -p .gemini/commands6.2 Example Research Commands
Create .gemini/commands/summarize.md:
Create a structured summary of this paper:
Paper: $ARGUMENTS
## Summary Format
- **Citation**: [Author(s), Year, Title]
- **Research Question**:
- **Methodology**:
- **Sample**:
- **Key Findings**: (3-5 bullets)
- **Theoretical Contribution**:
- **Limitations**:
- **Future Research**:
Use academic language, cite page numbers.Create .gemini/commands/themes.md:
Analyze these papers for common themes:
Papers: $ARGUMENTS
## Thematic Analysis
1. Identify 5-7 major themes
2. For each theme:
- List papers that discuss it
- Summarize key arguments
- Note points of agreement/disagreement
- Assess theoretical depth
Output as structured markdown.Step 7: Research Workflows
7.1 Comprehensive Literature Analysis
Single massive prompt for entire corpus:
"I'm providing my complete literature set (47 papers in @/literature/).
Phase 1: Read all papers and extract:
- Research questions
- Methodologies
- Key findings
- Theoretical frameworks
Phase 2: Identify patterns:
- Which methods are most common?
- What theories dominate?
- Where are the contradictions?
Phase 3: Gap analysis:
- What questions aren't being asked?
- What methods are underused?
- What theories need development?
Work through this systematically and save outputs to @/analysis/"7.2 Cross-Paper Validation
Fact-checking across corpus:
"Verify this claim across all papers in @/literature/:
'Organizational scaling requires both strategy and structure.'
Show which papers support, contradict, or nuance this claim.
Provide specific page references."7.3 Theoretical Framework Building
Integrate findings:
"Based on all papers in @/literature/, propose a novel
theoretical framework integrating:
- Key constructs identified across papers
- Relationships between constructs
- Boundary conditions
- Testable propositions
Use the 1M context to ensure nothing is missed!"Step 8: Comparison with Other CLIs
8.1 Gemini CLI vs Claude Code
| Feature | Gemini CLI | Claude Code |
|---|---|---|
| Cost | FREE (1K req/day) | Paid ($20/mo) |
| Context | 1M tokens | 200K tokens |
| Provider | Google only | Anthropic only |
| Open Source | ✅ Yes (Apache 2.0) | ❌ No |
| Quality | Excellent | Excellent |
| Best For | Budget + massive context | Premium quality + support |
When to use Gemini CLI:
- Free tier is enough for your needs
- Need to analyze 30+ papers simultaneously
- Want open-source transparency
- Experimenting with large-scale synthesis
When to use Claude Code:
- Budget allows ($20/mo)
- Need premium reasoning quality
- Want enterprise support
- Prefer polished UX
8.2 Gemini CLI vs OpenCode
| Feature | Gemini CLI | OpenCode |
|---|---|---|
| Models | Gemini only | 75+ providers |
| Context | 1M | Varies by model |
| Interface | Standard CLI | Beautiful TUI |
| Free Tier | ✅ Generous | Depends on provider |
| Best For | Google ecosystem | Model flexibility |
Use both when:
- Gemini CLI for heavy lifting (massive context)
- OpenCode for model experimentation (compare Claude, GPT, DeepSeek)
Step 9: Advanced Features
9.1 Background Tasks
Run long analyses asynchronously:
"Analyze all 47 papers in @/literature/ in the background.
Extract methodologies and create comparison table.
Notify when complete."9.2 Chain Actions
Multi-step workflows:
"Chain these actions:
1. Read all papers in @/literature/
2. Extract theoretical frameworks
3. Create comparison matrix
4. Identify most and least used theories
5. Save analysis to @/outputs/framework_analysis.md"9.3 GitHub Actions Integration
Gemini CLI can integrate with GitHub workflows:
- Automated literature updates
- Citation checking in PRs
- Documentation generation
See: Gemini CLI GitHub Actions
Step 10: Best Practices for Research
10.1 Maximize Free Tier
Daily limit strategies:
- 1,000 requests = ~20-30 comprehensive literature analyses
- Front-load heavy tasks in morning
- Save simple queries for end of day
- Limits reset at midnight PT
10.2 Context Window Optimization
Load smartly:
- Group related papers for thematic analysis
- Use full 1M for comprehensive synthesis
- Break into phases if hitting limits
10.3 Quality Control
Verify outputs:
- Check citations against Zotero library
- Cross-reference extracted data
- Review for hallucinations
- See: Failure Museum
Step 11: Integration with Research Memex
11.1 Zotero → Gemini CLI Pipeline
Workflow:
- Collect papers in Zotero
- Export to markdown via OCR Guide
- Load into Gemini CLI (all 50+ papers!)
- Comprehensive analysis with 1M context
11.2 Gemini CLI → Obsidian
Export insights:
- Complete analysis in Gemini CLI
- Save markdown outputs
- Import to Obsidian
- Link with literature notes
11.3 Gemini CLI → Zettlr
Draft papers:
- Generate synthesis in Gemini CLI
- Export to markdown
- Import to Zettlr
- Add @citekeys and export to Word/PDF
Step 12: Troubleshooting
Installation Issues
"Command not found: gemini"
- Reinstall:
npm install -g @google/gemini-cli - Check PATH:
echo $PATH - Restart terminal
"Permission denied"
- Use:
sudo npm install -g @google/gemini-cli - Or fix npm permissions
API Key Issues
"Unauthorized" or "Invalid API key"
- Verify key is set:
echo $GOOGLE_API_KEY - Check for extra spaces or quotes
- Regenerate key at AI Studio
Rate Limit Errors
"Quota exceeded"
- You've hit daily limit (1,000 requests)
- Wait until midnight PT for reset
- Or upgrade to paid tier (if needed)
Context Errors
"Context too large"
- Even 1M has limits!
- Split into smaller chunks
- Prioritize most relevant papers
Step 13: Example Research Project
13.1 Setup
Create project:
mkdir Systematic-Review-Gemini
cd Systematic-Review-Gemini
geminiInitialize GEMINI.md:
# Systematic Literature Review: AI in Education
## Goal
Synthesize 50+ papers on AI's impact on student learning (2020-2025)
## File Structure
- /literature/ - All 50 papers as markdown
- /analysis/ - Thematic analysis, extraction tables
- /synthesis/ - Draft sections
## Protocol
- Citation: APA 7th
- Inclusion: Peer-reviewed, empirical, English
- Analysis: Thematic synthesis + meta-analysis
## Context Advantage
With 1M tokens, I can load ALL 50 papers simultaneously for:
- Comprehensive thematic analysis
- Cross-paper validation
- Gap identification across entire corpus13.2 Massive Context Analysis
Load all 50 papers:
"Read all 50 papers in @/literature/ (approx 800K tokens).
Task: Comprehensive meta-synthesis
1. Extract all reported effect sizes
2. Group by intervention type
3. Analyze by student age group
4. Identify methodological patterns
5. Flag contradictory findings
6. Propose integrated theory
Save complete analysis to @/analysis/meta_synthesis.md"This is impossible with smaller context windows!
Step 14: Advanced Use Cases
14.1 Dissertation Review
Check entire dissertation:
"Load my complete dissertation from @/drafts/ (6 chapters, 45K words).
Review for:
- Argument coherence across all chapters
- Citation balance (am I over-citing certain papers?)
- Theoretical consistency
- Transition quality between chapters
- Missing literature I should address
Provide chapter-by-chapter feedback."14.2 Literature Gap Finder
Comprehensive gap analysis:
"Analyze all papers in @/literature/ for research gaps.
Systematically check:
- Methodological gaps (which methods are underused?)
- Theoretical gaps (which theories lack development?)
- Empirical gaps (which contexts are understudied?)
- Temporal gaps (what recent trends aren't covered?)
For each gap, assess significance and feasibility."14.3 Multi-Paper Validation
Cross-validate claims:
"I claim: 'AI tools improve student outcomes but reduce
critical thinking skills.'
Search all 50 papers in @/literature/:
- Which support this claim? (quote specific findings)
- Which contradict it? (provide counter-evidence)
- Which nuance it? (add boundary conditions)
Build an evidence table with page references."Step 15: Comparison with Claude Code
When to Use Gemini CLI vs Claude Code
Use Gemini CLI for:
- ✅ Budget-conscious research (free tier!)
- ✅ Massive literature analysis (30-50+ papers)
- ✅ Comprehensive dissertation review
- ✅ Exploratory synthesis (try before you buy)
- ✅ Open-source preference
Use Claude Code for:
- ✅ Premium reasoning quality needed
- ✅ Complex theoretical arguments
- ✅ Enterprise support required
- ✅ Budget allows ($20/mo)
Use BOTH when:
- Gemini CLI for massive-context first pass
- Claude Code for refined analysis and argumentation
- Compare outputs for quality control
Info
Cost Strategy: Use Gemini CLI's free tier for 90% of work (screening, extraction, thematic coding). Reserve Claude Code for final 10% (theoretical framing, critical arguments). This optimizes both cost and quality!
Step 16: Learning Resources
16.1 Official Documentation
16.2 Tutorials & Articles
16.3 Community
- GitHub Issues: Report bugs, request features
- Discussions: Share workflows and tips
- Stack Overflow: Tag
gemini-cli
Checklist
By the end of this guide, you should have:
- Installed Gemini CLI via npm
- Created free Google AI Studio API key
- Set GOOGLE_API_KEY environment variable
- Launched Gemini CLI successfully
- Created GEMINI.md project file
- Tested file references with @ syntax
- Loaded 10+ papers to test massive context
- Created at least one custom slash command
- Tested MCP integration (Zotero or filesystem)
- Compared with Claude Code for your use case
Tip
Pro Tip: The 1M context window is game-changing for literature reviews. Load your ENTIRE corpus and ask cross-cutting questions that traditional tools can't handle!
What's Next
Gemini CLI is the free entry point. The natural next step is the CLI Setup Guide, which sets it next to Claude Code and OpenCode so you can decide where your real work lives.