Getting Started with Gemini CLI

Official References: Overview · Installation · Authentication · GEMINI.md

Why Gemini CLI feels different

Gemini CLI is Google's open-source terminal agent. Its current positioning is simple: bring Gemini models, local tools, web access, and project context into one CLI that works well for both interactive sessions and automation.

For this project, Gemini CLI matters most in three situations:

1. Large-repo understanding — the 1M-token context window is good for broad architectural passes.
2. Mixed local + web workflows — the tool system can read files, run shell commands, and fetch current information.
3. Reusable project guidance — GEMINI.md gives you persistent instructions without rewriting the same prompt every time.

Install it the practical way

Gemini CLI currently recommends Node.js 20+.

# npm global install
npm install -g @google/gemini-cli
 
# macOS / Linux
brew install gemini-cli
 
# no permanent install
npx @google/gemini-cli

Pick the right authentication path

The official docs split auth into a few clear cases:

1) Sign in with Google

gemini

Then choose the Google sign-in flow in the CLI.

2) Use a Gemini API key

Best for scripts, headless jobs, or minimal local setup:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini

3) Use Vertex AI

Best when your team already manages models through Google Cloud:

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
gemini

First commands and Core Workflows

Gemini CLI is strongest when you use its tool syntax instead of writing giant prompts manually.

Basic Interaction

# Start interactive mode
gemini
 
# Include files or directories with @
gemini "@package.json @src explain the app architecture"
 
# Run shell commands with !
!npm test

The Core Workflow: Research -> Strategy -> Execution

Instead of just chatting, guide the agent through explicit phases:

1. Research: Ask the agent to explore (grep_search, glob) and map the codebase.
2. Strategy: Ask it to design an approach before making changes.
3. Execution: Let it apply surgical changes (replace, write_file) and validate via shell tools.

Utilizing Plan Mode (/plan)

For large refactoring or architectural decisions, it is risky to let the agent start editing immediately. Use the /plan command to enter Plan Mode. In this read-only state, the agent cannot modify files or run destructive commands. It focuses entirely on navigating the code and drafting a rigorous design document. Once the plan is verified, switch back to the default mode to execute the changes safely.

GEMINI.md is the real unlock

Gemini CLI loads GEMINI.md hierarchically:

1. ~/.gemini/GEMINI.md (global preferences)
2. workspace context files (project-wide rules)
3. JIT context files inside subdirectories

Example project file

# Project: AI Native Notes
 
## Stack
- Next.js 16
- TypeScript
- next-intl
- MDX content under /content
 
## Content rules
- Keep frontmatter consistent across locales
- Prefer practical examples over marketing copy
- Preserve slug parity between ko/en/es

Gemini CLI vs Claude Code vs GPT Codex

Recommended next reads

• Repo-scale analysis: The 1M Token Advantage
• Delegating tasks: Sub-agents and Skills
• CI workflows: Headless Automation