SynStar AI Docs

Theme

Gemini CLI English Usage Guide ​

Basic 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 provides a lightweight way to access Gemini, offering the most direct path from prompt to model. By setting up a relay station (proxy), you can use Gemini CLI service normally 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 capabilities, file operations, Shell commands, web scraping

🔌 Extensible: Support for 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 Methods ​

Quick Installation ​

Run instantly with npx (no installation required) ​

# Using official repository
npx https://github.com/google-gemini/gemini-cli

Global installation with npm ​

npm install -g @google/gemini-cli

Installation with Homebrew (macOS/Linux) ​

brew install gemini-cli

System Requirements ​

Node.js version 20 or higher

macOS, Linux, or Windows

Configuring Relay Station (Proxy) Usage ​

1. Setting Environment Variables ​

Before using a relay station, you need to configure the following environment variables:

# Set API key
export GEMINI_API_KEY=sk-xxxxx

# Set API relay station address
export GOOGLE_GEMINI_BASE_URL=https://www.kkiai.com

# For cmd use the following

set GEMINI_API_KEY=sk-xxxxx
set GOOGLE_GEMINI_BASE_URL=https://www.kkiai.com

Note: You can also add these environment variables to .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 ​

gemini

Include multiple directories ​

gemini --include-directories ../lib,../docs

Use specific model ​

gemini -m gemini-2.5-flash

Script non-interactive mode ​

Get simple text response:

gemini -p "Explain the architecture of this codebase"

Get structured JSON output:

gemini -p "Explain the architecture of this codebase" --output-format json

Quick Examples ​

Start a new project ​

cd new-project/
gemini
> Write me a Discord bot that answers questions using the FAQ.md file I provide

Analyze existing code ​

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all changes from yesterday

📋 Main Features ​

Code Understanding and Generation ​

Query and edit large codebases

Generate new applications using multimodal capabilities from PDFs, images, or sketches

Debug issues and troubleshoot problems using natural language

Automation and Integration ​

Automate operational tasks such as querying pull requests or handling complex rebase operations

Connect new features 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 Feature 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 draft for GitHub issue #123
> Help me migrate this codebase to the latest version of Java. Start by making a plan

Automate Workflows ​

> Create a slide presentation showing git history from the past 7 days, grouped by feature and team member
> Create a full-screen web application for wall display showing our most interactive GitHub issues

System Interaction ​

> Convert all images in this directory to png and rename them using dates from exif data
> Organize my PDF invoices by expense month

GitHub Integration ​

Integrate Gemini CLI directly into your GitHub workflows using the Gemini CLI GitHub Action:

Pull Request Review: Automatic code review 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 while using Gemini CLI, refer to the following:

  1. Check if environment variables are set correctly:
echo $GEMINI_API_KEY
echo $GOOGLE_GEMINI_BASE_URL
  1. Check if network connection is stable and relay station is accessible:
curl -I https://www.kkiai.com

  1. Check for error messages, which usually indicate the problem

  2. If using SOCKS proxy, ensure the proxy format is correct, for example socks5://<user>:<pass>@<proxy>:<port>

  3. Use built-in command to report issues:

# Report bug directly in CLI
/bug

Release Notes ​

Preview ​

New preview versions are released every Tuesday at 23:59 UTC. Install using the preview tag:

npm install -g @google/gemini-cli@preview

Stable ​

New stable versions are released every Tuesday at 20:00 UTC. Install using the latest tag:

npm install -g @google/gemini-cli@latest

Nightly ​

Nightly versions are released daily at 00:00 UTC. Install using the nightly tag:

npm install -g @google/gemini-cli@nightly

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 Advisory: Security updates

Uninstall ​

If you need to uninstall Gemini CLI, please refer to the official uninstall guide.