Getting Started with Google's Gemini CLI

Google’s Gemini CLI brings AI assistance directly to your terminal—where developers already spend most of their time. If you’re comfortable with command-line tools and want to integrate AI into your existing workflow, this open-source tool offers a compelling alternative to GUI-based coding assistants.

This guide covers everything you need to start using Gemini CLI: installation, authentication, basic commands, and practical workflows that fit naturally into your development process.

What is Gemini CLI?

Gemini CLI is Google’s open-source terminal AI agent that connects you directly to Gemini 2.5 Pro (with fallback to Flash). Unlike browser-based AI tools, it runs right in your terminal alongside git, npm, and other command-line utilities you already use.

Key features that set it apart:

• 1M token context window: Work with entire codebases without losing context
• Multimodal input: Process images, PDFs, and sketches alongside code
• MCP support: Extend functionality through Model Context Protocol servers
• Google Search integration: Ground responses with real-time web data
• Free tier: 60 requests/minute, 1,000 requests/day with a personal Google account

Prerequisites and Installation

System Requirements

Before installing Gemini CLI, ensure you have:

• Node.js version 18 or higher
• npm (comes with Node.js)
• A terminal application
• Internet connection for authentication

Installing Gemini CLI

You have two installation options:

Option 1: Run directly with npx

npx @google/gemini-cli

Option 2: Global installation (recommended)

npm install -g @google/gemini-cli
gemini

The global installation provides a permanent gemini command accessible from any directory.

Authentication and Setup

When you first run gemini, you’ll go through a quick setup process:

1. Choose a theme: Select your preferred color scheme for the CLI interface
2. Select authentication method:
   • Personal Google Account (recommended for getting started)
   • Google Workspace Account
   • API Key

Google Account Authentication

The simplest way to get started is with a personal Google account:

1. Run gemini in your terminal
2. Choose “Personal Google Account” when prompted
3. Follow the browser authentication flow
4. Return to your terminal

This gives you immediate access to the free tier limits.

API Key Authentication

For automation or higher limits:

1. Generate a key at Google AI Studio
2. Set it as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

Troubleshooting Workspace Authentication

Google Workspace accounts require additional setup:

1. Create a Google Cloud Project
2. Enable the Generative Language API
3. Set the project ID:

export GOOGLE_CLOUD_PROJECT="your-project-id"

Essential Commands and Usage

Command Types

Gemini CLI uses three command patterns:

Slash commands (/) - Control the CLI

• /help - Show available commands
• /auth - Change authentication method
• /clear - Clear the screen
• /exit - Exit the CLI

File commands (@) - Include file content

• @file.js - Include a single file
• @src/ - Include all files in a directory

Shell commands (!) - Execute terminal commands

• !ls -la - Run a single command
• ! - Toggle shell mode

Basic Workflow Examples

Exploring a codebase:

cd my-project
gemini
> Explain the architecture of this project

Fixing a bug:

gemini
> @src/api.js has a TypeError on line 42. Analyze and fix it

Generating tests:

gemini
> Write unit tests for @utils/validation.js using Jest

One-Shot Commands

For quick tasks without entering interactive mode:

# Generate documentation
gemini -p "Create a README based on @package.json"

# Fix linting errors
gemini -p "Fix ESLint errors in @src/"

# Analyze recent changes
gemini -p "Summarize the last 5 git commits"

Practical Use Cases

1. Code Understanding and Navigation

Gemini CLI excels at helping you understand unfamiliar codebases:

> Map out how authentication flows through this application
> Which files implement the payment processing logic?
> Explain how @services/auth.js interacts with the database

2. Automated Refactoring

The large context window enables complex refactoring across multiple files:

> Refactor all API endpoints to use async/await instead of callbacks
> Update all imports to use ES6 modules

3. Test-Driven Development

Create a feedback loop for test-driven fixes:

> Fix failing tests in this project. Run npm test after each change and continue until all pass

4. Documentation Generation

Generate or update documentation based on actual code:

> Create API documentation for all endpoints in @routes/
> Update CHANGELOG.md based on recent commits

Configuration with GEMINI.md

Customize Gemini CLI’s behavior by creating a GEMINI.md file in your project root:

# Project Configuration

## Coding Standards
- Use TypeScript with strict mode
- Follow ESLint configuration
- Prefer functional programming patterns

## Architecture Notes
- API routes are in /routes
- Business logic lives in /services
- Database models are in /models

## External Documentation
https://docs.ourframework.com/latest

The CLI automatically reads these files to understand your project context.

Comparing with Other AI CLIs

How Gemini CLI stacks up against alternatives:

• vs Claude MCP: Larger context window (1M vs 200K tokens), multimodal support
• vs GitHub Copilot CLI: Free tier available, works outside VS Code
• vs Cursor: Terminal-based workflow, no IDE dependency

The main differentiator is Gemini’s massive context window—ideal for large codebases or complex refactoring tasks.

Conclusion

Gemini CLI integrates naturally into terminal-based workflows, providing AI assistance without context switching. Its open-source nature and generous free tier make it accessible for individual developers while offering paths to scale for teams and automation.

Now that you have Gemini CLI running, try these tasks to explore its capabilities:

1. Navigate to an existing project and ask for an architecture overview
2. Use multimodal input: sketch a UI component and ask Gemini to implement it
3. Set up MCP servers for extended functionality
4. Create project-specific GEMINI.md files for better context

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.