"Free? That can't be as good as Claude Code..." That was my first thought when I heard about Gemini CLI. Google had just released their AI terminal as open source.
Spoiler: After intensive use, I have to say - for some tasks it's even better. Especially when you're working with large codebases. The 1-million-token context window is not a marketing gag, but a real game-changer. According to Google I/O 2025, over 7 million developers worldwide are already using Gemini models - a fivefold increase compared to the previous year. And with the new Gemini 3 Pro model, Google has stepped it up again.
In this article, I'll show you all Gemini CLI commands - from installation to hidden MCP integrations. This is the most complete reference you'll find. After this guide, you'll know every available command and exactly when to use Gemini CLI instead of Claude Code.
- Gemini CLI offers over 30 different commands for AI-powered development directly in the terminal
- /chat, /memory, /model and /directory are the most important slash commands for daily workflow
- Gemini 3 Pro is now available and brings improved agentic coding capabilities
- Advanced commands enable MCP integration, session management, token counting and auto-routing between models
Installing Gemini CLI: Three paths to success
Installing Gemini CLI is refreshingly straightforward. You only need Node.js 18+ (I recommend version 20) and an internet connection:
# Method 1: Get started immediately (without installation)
npx https://github.com/google-gemini/gemini-cli
# Method 2: Install globally (my recommendation)
npm install -g @google/gemini-cli
# Method 3: Homebrew (for Mac/Linux fans)
brew install gemini-clinpx command is convenient for the first test, but the constant downloading gets annoying with daily use.Authentication: OAuth vs. API Key
Google offers three authentication methods. After extensive testing, I recommend OAuth - it's free and has the most generous limits:
# Option 1: Google OAuth (free, recommended)
gemini # Opens browser for login
# Option 2: API key (for automation)
export GEMINI_API_KEY="your-key-from-aistudio.google.com"
gemini
# Option 3: Vertex AI (for enterprises)
export GOOGLE_API_KEY="enterprise-key"
export GOOGLE_GENAI_USE_VERTEXAI=true
geminiBasic commands: The daily workflow
Let's start with the commands I actually use every day. The Gemini CLI commands are more clearly structured than Claude Code and fit perfectly into a terminal-centric workflow.
Starting interactive mode
# Simple start in current directory
gemini
# With specific directories
gemini --include-directories ../lib,../docs
# With specific model (Flash is faster, Pro is smarter)
gemini -m gemini-2.5-flash
# With Gemini 3 Pro (if available)
gemini -m gemini-3-pro-preview
# With automatic tool approval (YOLO mode)
gemini --yolo--yolo) automatically executes all tool calls. Only use this in projects where nothing can break!Non-interactive mode (for scripts)
For automation and CI/CD pipelines, non-interactive mode is worth its weight in gold:
# Quick question without session
gemini -p "Explain the architecture of this codebase"
# Analyze file
gemini -p "Find bugs in this file @./src/main.js"
# With Unix pipes
echo "Write a unit test for function add(a,b)" | gemini
# Analyze git diff
git diff | gemini -p "Write a commit message for these changes"All slash commands in detail
Here's the complete list of all slash commands. I've sorted them by usage frequency - the most important ones first:
Command | Description | Example / Tip |
|---|---|---|
/help | Shows all available commands | [object Object], or ,[object Object] |
/model | Selects AI model (Auto, Pro, Flash, Flash-Lite) | Switch between Gemini 3 Pro and Flash |
/clear | Clears screen and context | [object Object], or ,[object Object] |
/memory add | Adds important info to AI memory | /memory add Always use TypeScript |
/tools | Lists available tools | /tools desc |
/chat save | Saves current conversation | /chat save feature-implementation |
/chat resume | Resumes a previous conversation | /chat resume feature-implementation |
/chat list | Shows all saved conversations | /chat list |
/chat delete | Deletes a saved conversation | /chat delete old-session |
/chat share | Exports conversation as Markdown/JSON | /chat share file.md |
/resume | Searches and resumes sessions interactively | Interactive browser interface |
/stats | Shows token usage and session duration | /stats |
/compress | Replaces context with summary | /compress |
/mcp | Manages MCP servers | /mcp list |
/mcp auth | Authenticates with MCP server | /mcp auth github |
/mcp desc | Shows MCP tool descriptions | /mcp desc |
/mcp schema | Shows JSON schema of MCP tools | Useful for MCP development |
/mcp refresh | Reloads MCP connections | /mcp refresh |
/exit | Exits Gemini CLI cleanly | [object Object], or ,[object Object] |
/copy | Copies last response to clipboard | /copy |
/memory show | Shows entire AI memory | Check regularly what the AI knows |
/memory refresh | Reloads memory from GEMINI.md | /memory refresh |
/memory list | Shows all memory file paths | /memory list |
/restore | Restores files before tool execution | /restore [tool_call_id] |
/tools desc | Shows tool descriptions | /tools descriptions |
/settings | Opens settings editor | Activate preview features for Gemini 3 |
/theme | Changes color scheme | Dark mode for long sessions |
/vim | Activates Vim mode (NORMAL/INSERT) | A must for Vim enthusiasts |
/privacy | Shows privacy info and consent options | Important for GDPR compliance |
/bug | Reports bug to Google | /bug "Description" |
/directory add | Adds additional working directories | /directory add ../lib |
/directory show | Shows all added directories | /dir show |
/editor | Selects preferred text editor | /editor |
/extensions | Lists active CLI extensions | /extensions |
/auth | Switches authentication method | /auth |
/about | Shows version information | /about |
/init | Generates GEMINI.md context file | /init |
/memory add command is underrated! I add project-specific rules like "Always use English comments" or "Prefer functional programming". This saves massive time.File referencing with @ symbol
One of the most elegant features of Gemini CLI is file referencing. Instead of awkwardly copying files, you simply use the @ symbol:
# Analyze single file
"Explain this function to me @./src/utils.js"
# Include entire directory
"Refactor the API @./api/"
# Multiple files at once
"Find similarities between @./old.js and @./new.js"
# With wildcards (experimental)
"Check all tests @./tests/*.spec.js"Shell integration: The ! operator
With the exclamation mark, you execute shell commands directly from Gemini CLI:
# Single command
!git status
# Switch to shell mode
!
# Now you're in a persistent shell
# Type 'exit' to leave
# Pipe output directly to Gemini
!npm test
"Explain these errors and suggest fixes"CLI flags
Gemini's CLI flags are more powerful than they appear at first glance. Here are all the important options:
Flag | Description | Example |
|---|---|---|
-m, --model | Selects the AI model | gemini -m gemini-3-pro-preview |
-p | Non-interactive mode with prompt | gemini -p "Analyze package.json" |
-i, --prompt-interactive | Starts interactive session with prompt | gemini -i "Explain the architecture" |
--yolo | Auto-approves all tool calls | gemini --yolo |
--include-directories | Loads additional directories | gemini --include-directories ./src,./tests |
--sandbox | Safe execution with Docker/Podman | gemini --sandbox |
-d, --debug | Activates debug output | gemini -d |
--checkpointing | Saves project snapshots before changes | gemini --checkpointing |
--output-format json | Structured JSON output for scripts | gemini -p "..." --output-format json |
--output-format stream-json | Real-time streaming as JSON events | For real-time processing |
--no-history | Disables session history | gemini --no-history |
Shortcuts
These shortcuts make the difference between "okay" and "really productive":
Keyboard Shortcut | Function | When to use? |
|---|---|---|
Ctrl+L | Clear screen | When terminal gets too full |
Ctrl+V | Paste text/image | Analyze screenshots directly |
Ctrl+Y | Toggle YOLO mode | Quickly switch between modes |
Ctrl+X | Open external editor | For long prompts |
Tab | Auto-completion | For filenames after @ |
Ctrl+C | Cancel | When Gemini takes too long |
Model selection and Gemini 3 Pro
With the /model command, you select the optimal model for your task. Google offers four tiers:
Model | Description | Usage |
|---|---|---|
| Auto (Recommended) | System automatically chooses based on task | Default for most tasks |
| Pro | Gemini 3 Pro or 2.5 Pro for complex tasks | Agentic coding, deep reasoning |
| Flash | Gemini 2.5 Flash - Balance of speed and quality | Quick answers, simple refactorings |
| Flash-Lite | Gemini 2.5 Flash-Lite - Maximum speed | Trivial tasks, quick questions |
Activating Gemini 3 Pro: The new flagship model is available for Google AI Ultra subscribers and users with a paid API key. Here's how to activate it:
# 1. Update Gemini CLI to version 0.16+
npm update -g @google/gemini-cli
# 2. Enable preview features
/settings
# → Set "Preview features" to true
# 3. Select model
/model
# → Select "Pro" - this will use Gemini 3 ProMCP
Model Context Protocol (MCP) is the reason I prefer Gemini CLI over Claude Code for certain tasks. You can integrate any services:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
},
"trust": false,
"includeTools": ["create_repository", "search_repositories"],
"excludeTools": ["delete_repository"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost/db"
},
"trust": true
}
}
}After configuration, you have access to extended features:
# Use GitHub integration
"Create a new repository for my React project"
# Gemini automatically uses the GitHub MCP server
# Database queries
"Show me all users who registered this week"
# Executes SQL and shows results
# Manage MCP servers
/mcp list # Lists all servers and tools
/mcp desc # Shows tool descriptions
/mcp schema # JSON schema for developers
/mcp auth github # Authenticates with MCP server
/mcp refresh # Reloads connections/mcp refresh or restarting Gemini CLI helps.Custom commands
One of my favorite features: You can create your own commands. Custom commands are defined in .toml files - either project-specific or global:
# Project-specific: .gemini/commands/test-all.toml
# Global: ~/.gemini/commands/test-all.toml
# Only "prompt" is required
prompt = """
Run the following tests sequentially and give me a summary:
1. npm test
2. npm run lint
3. npm run typecheck
4. npm run test:e2e
Show only errors and warnings, no successful tests.
"""
# Optional fields:
# description = "Runs complete test suite"
# model = "gemini-2.5-flash"After saving, you can simply type /test-all. For namespaced commands, use subfolders: .gemini/commands/git/commit.toml becomes /git:commit.
gemini "/test-all" executes the command directly - perfect for CI/CD pipelines.Token optimization
The free limits are generous, but with a few tricks you can get even more out of them:
# Compress context regularly
/compress
# Only load relevant directories
gemini --include-directories ./src --exclude node_modules,dist
# Flash model for simple tasks
gemini -m gemini-2.5-flash
# Disable history for large sessions
gemini --no-history
# Checkpoints for intermediate states
/chat save checkpoint-1
# Jump back on problems
/restore checkpoint-1Debugging
Even Google's AI has a bad day sometimes. Here are my proven solutions for the most common problems:
Problem | Probable Cause | Solution |
|---|---|---|
| Authentication fails | Outdated token | Clear browser cache, log in again |
| MCP server doesn't connect | Missing dependencies | Install npx, /mcp refresh |
| Token limit reached | Too much context | Use /compress or /clear |
| Slow responses | Pro model overloaded | Switch to Flash model |
| Shell commands don't work | Sandbox mode active | Start without --sandbox |
| Files not found | Wrong path | Use absolute paths |
For stubborn problems, there are debug commands:
# Verbose mode for details
gemini -d
# System information
/stats
# MCP debug
gemini --mcp-debug
# Check tool schemas
/tools schema
# Complete reset
rm -rf ~/.gemini/cache
gemini
