Gemini CLI User Guide#
Introduction#
Gemini CLI is an open-source command-line AI tool provided by Google that brings the power of Gemini directly to your terminal. It offers a lightweight way to access Gemini, providing the most direct path from prompt to model. By configuring a proxy, you can use Gemini CLI services even in network-restricted environments.🚀 Why Choose Gemini CLI?#
🧠 Powerful Gemini 2.5 Pro: Access to 1 million token context window
🔧 Built-in Tools: Google Search grounding, file operations, Shell commands, web scraping
🔌 Extensible: Supports MCP (Model Context Protocol) for custom integrations
💻 Terminal-First: Designed for developers who work in the command line
🛡️ Open Source: Apache 2.0 License
📦 Installation#
Quick Install#
Run Instantly with npx (No Installation Required)#
Global Installation with npm#
Install with Homebrew (macOS/Linux)#
System Requirements#
Node.js version 20 or higher
Configuring the Proxy#
1. Set Environment Variables#
Before using the proxy, you need to configure the following environment variables:Note: You can also add these environment variables to your .bashrc, .zshrc, or other shell configuration files so they are automatically set each time you start the terminal.
🚀 Quick Start#
Basic Usage#
Start in Current Directory#
Include Multiple Directories#
Use a Specific Model#
Non-Interactive Script Mode#
Get a simple text response:Get structured JSON output:Quick Examples#
Start a New Project#
Analyze Existing Code#
📋 Main Features#
Code Understanding and Generation#
Query and edit large codebases
Generate new applications from PDFs, images, or sketches using multimodal capabilities
Debug issues and troubleshoot using natural language
Automation and Integration#
Automate operational tasks like querying pull requests or handling complex rebases
Connect new capabilities using MCP servers
Run non-interactively in scripts for workflow automation
Advanced Features#
Get real-time information using built-in Google Search
Conversation checkpoints to save and restore complex sessions
Custom context files (GEMINI.md) to tailor behavior for your project
Common Commands and Examples#
Explore Codebase#
> Describe the main components of this system architecture
> What security mechanisms are in place?
> Provide a step-by-step onboarding document for new developers
Work with Existing Code#
> Implement a first draft for GitHub issue #123
> Help me migrate this codebase to the latest version of Java. Start with a plan
Automate Workflows#
> Create a slideshow showing the git history from the past 7 days, grouped by feature and team member
> Create a full-screen web app for wall display showing our most interactive GitHub issues
System Interaction#
> Convert all images in this directory to png and rename them using the date from exif data
> Organize my PDF invoices by spending month
GitHub Integration#
Use the Gemini CLI GitHub Action to integrate Gemini CLI directly into your GitHub workflows:Pull Request Reviews: Automated code reviews with contextual feedback and suggestions
Issue Triage: Automatically label and prioritize GitHub issues based on content analysis
On-Demand Help: Mention @gemini-cli in issues and pull requests for help with debugging, explanations, or task delegation
Custom Workflows: Build automated, scheduled, and on-demand workflows tailored to your team's needs
Troubleshooting#
If you encounter issues during use, consider the following:1.
Check if environment variables are set correctly: 2.
Check if network connection is stable and proxy is accessible: 3.
Check for error message output, which usually indicates the problem
4.
If using SOCKS proxy, ensure the proxy format is correct, e.g., socks5://<user>:<pass>@<proxy>:<port>
5.
Use built-in command to report issues: Release Notes#
Preview#
New preview versions are released every Tuesday at UTC 23:59. Install using the preview tag:Stable#
New stable versions are released every Tuesday at UTC 20:00. Install using the latest tag:Nightly#
Nightly versions are released every day at UTC 00:00. Install using the nightly tag:MCP Server Usage#
Configure MCP servers in ~/.gemini/settings.json to extend Gemini CLI with custom tools:> @github list my open pull requests
> @slack send a summary of today's commits to #dev channel
> @database run a query to find inactive users
Official Roadmap: View upcoming features
NPM Package: Package registry
GitHub Issues: Report bugs or request features
Security Advisories: Security updates
Uninstall#
If you need to uninstall Gemini CLI, please refer to the official uninstall guide.Modified at 2026-09-28 09:50:55
