Skip to main content

​
Welcome!

This guide will get you from zero to your first working Gemini CLI command in just a few minutes.
Already installed? Jump to Start Your First Session.

​
Step 1: Install Gemini CLI

Choose your preferred installation method: Verify the installation: 
gemini --version
Need more installation options? See the Installation Guide for Anaconda, Docker, and other methods.

​
Step 2: Start Your First Session

Launch Gemini CLI: 
gemini
You’ll see a welcome screen with authentication options.

​
Step 3: Authenticate

Choose your authentication method based on your account type:
1

Select Authentication Method

When prompted “How would you like to authenticate for this project?”, choose:
  • Login with Google (recommended for most users)
  • Use Gemini API key (if you have an API key from AI Studio)
  • Vertex AI (for enterprise/cloud users)
2

Complete Authentication

For Login with Google:
  • A browser window will open
  • Sign in with your Google account
  • Grant permissions when prompted
  • Return to your terminal
For API Key:
  • Set your API key first: export GEMINI_API_KEY="your-key"
  • Then run gemini
3

Verify Authentication

Once authenticated, you’ll see the Gemini CLI prompt:
>
You’re ready to go!
Your credentials are cached locally, so you won’t need to authenticate again for future sessions.

​
Step 4: Try Your First Commands

Now let’s try some basic commands to see Gemini CLI in action:

​
Example 1: Ask a Question

> What files are in the current directory?
Gemini will analyze your directory and provide a helpful overview.

​
Example 2: Code Explanation

If you have code files in your directory: 
> Explain what this project does
Gemini will read your code files and provide a summary.

​
Example 3: Generate Code

> Create a simple Node.js HTTP server that responds with "Hello World"
Gemini will generate the code and ask for permission to write the file.
Gemini CLI always asks for permission before executing commands, writing files, or making changes to your system.

​
Step 5: Learn Essential Commands

Here are some key slash commands to enhance your workflow:

/help

Display all available commands
> /help

/chat

Start a new conversation
> /chat

/model

Switch between Gemini models
> /model gemini-2.5-flash

/stats

View token usage and quota
> /stats model

​
Real-World Examples

Let’s explore some practical use cases:

​
Create a New Project from Scratch

1

Navigate to Project Directory

mkdir my-discord-bot
cd my-discord-bot
gemini
2

Describe What You Want

> Write me a Discord bot that answers questions using a FAQ.md file I will provide
3

Let Gemini Work

Gemini will:
  • Create necessary files (package.json, bot.js, etc.)
  • Write the implementation
  • Ask for permission before writing files
  • Provide instructions for running the bot

​
Analyze an Existing Repository

1

Clone and Navigate

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
2

Ask for Analysis

> Give me a summary of all of the changes that went in yesterday
Or:
> Explain the overall architecture of this codebase
3

Review Results

Gemini will analyze git history and source files to provide insights.

​
Automate File Management

# Rename photos based on their content
> Rename the photos in my "photos" directory based on their contents

# Combine CSV files
> Combine Revenue-2023.csv and Revenue-2024.csv into a single file

# Generate documentation
> Create a README.md file explaining this project

​
Advanced Usage

​
Non-Interactive Mode (for Scripts)

Run Gemini CLI non-interactively for automation: 
gemini -p "Explain the architecture of this codebase"

​
Include Additional Directories

Provide more context from related directories: 
gemini --include-directories ../lib,../docs,../tests

​
Choose a Specific Model

# Use Gemini 2.5 Flash (faster)
gemini -m gemini-2.5-flash

# Or specify in interactive mode
> /model gemini-2.5-flash

​
Understanding Permissions

Gemini CLI asks for permission before:

File Operations

  • Reading files
  • Writing new files
  • Modifying existing files
  • Deleting files

System Operations

  • Running shell commands
  • Installing packages
  • Executing scripts
  • Network requests
Permission options:
  • Allow once - Grant permission for this action only
  • Allow all - Grant permission for all actions in this session
  • Deny - Reject the action
Be cautious with “Allow all” - review what Gemini plans to do before granting blanket permissions.

​
Check Your Usage

Monitor your token usage and quota: 
> /stats model
This shows:
  • Current session token usage
  • Overall quota for your account
  • Usage by model
  • Remaining quota
Free tier includes 60 requests/min and 1,000 requests/day for individual Google accounts.

​
Tips for Success

The more context you provide, the better results you’ll get:❌ “Create a server”✅ “Create a Node.js Express server with endpoints for GET /users and POST /users, using JSON file storage”
Create a GEMINI.md file in your project root to provide persistent context:
# Project Context

This is a Discord bot written in JavaScript.
Use CommonJS (require) instead of ES modules.
Follow the existing code style in bot.js.
For large projects, break work into smaller steps:
> First, analyze the current authentication system
> Now, design a new OAuth2 flow
> Finally, implement the OAuth2 flow we designed
Always review what Gemini plans to do:
  • Check file paths
  • Review commands before execution
  • Understand what will be modified

​
Keyboard Shortcuts

Speed up your workflow with these shortcuts:
ShortcutAction
Ctrl+CCancel current operation
Ctrl+DExit Gemini CLI
↑ / ↓Navigate command history
TabAuto-complete (when available)
See the Keyboard Shortcuts Reference for a complete list.

​
Troubleshooting

  • Clear cached credentials: rm -rf ~/.gemini/credentials
  • Try using an API key instead: export GEMINI_API_KEY="your-key"
  • Check your internet connection
  • Verify you’re in a supported location
  • Ensure you’re in the correct directory
  • Use --include-directories to add more context
  • Check file permissions
  • Try explicitly mentioning the file: “Read the contents of src/app.js”
  • Try a faster model: /model gemini-2.5-flash
  • Reduce context by limiting included directories
  • Check your internet connection
  • Consider if you’re hitting rate limits (check with /stats model)
  • Verify you granted permission when prompted
  • Check that required tools are installed (git, npm, etc.)
  • Review error messages carefully
  • Try running the command manually to debug

​
Next Steps

Now that you’re up and running, explore more features:

Commands Reference

Learn all available slash commands

Configuration Guide

Customize Gemini CLI to your workflow

MCP Server Integration

Extend Gemini CLI with custom tools

Examples & Tutorials

Explore real-world use cases

​
Get Help

Need assistance?
Join the community! Share your MCP servers, custom commands, and use cases on GitHub Discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us