Documentation/Basic Configuration

Basic Configuration

Essential

Configure Gemini CLI for your workflow with API keys, environment variables, and customizable settings. Get up and running quickly with these essential configurations.

Quick Setup Checklist

Set up API authentication (Google AI Studio or Vertex AI)

Configure environment variables

Customize settings.json (optional)

Test your configuration

Authentication Setup

Google AI Studio (Recommended)

Free tier with generous limits, perfect for individual developers

Get your API key from Google AI Studio

# Set API key (replace with your actual key)
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

# Make it permanent (Bash)
echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
source ~/.bashrc

Vertex AI

Enterprise-grade with Google Cloud integration

Requires Google Cloud Project with Vertex AI enabled

# Authenticate with Google Cloud
gcloud auth application-default login

# Set required environment variables
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true

Environment Variables Reference

Variable	Required	Description
GEMINI_API_KEY	Required	Your Gemini API key from Google AI Studio
GEMINI_MODEL	Optional	Default model (e.g., "gemini-2.5-flash")
GOOGLE_CLOUD_PROJECT	Vertex AI	Your Google Cloud Project ID
GOOGLE_CLOUD_LOCATION	Vertex AI	Project location (e.g., "us-central1")
GEMINI_SANDBOX	Optional	Enable sandboxing ("true", "docker", "podman")

Settings File Configuration

Create a settings.json file to customize your Gemini CLI experience. Settings can be global (~/.gemini/settings.json) or project-specific (.gemini/settings.json).

Example Configuration

A complete settings.json with commonly used options

{
  "theme": "GitHub",
  "sandbox": "docker",
  "autoAccept": false,
  "toolDiscoveryCommand": "bin/get_tools",
  "toolCallCommand": "bin/call_tool",
  "fileFiltering": {
    "respectGitIgnore": true,
    "enableRecursiveFileSearch": true
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    }
  },
  "telemetry": {
    "enabled": false,
    "target": "local",
    "logPrompts": false
  },
  "usageStatisticsEnabled": true,
  "preferredEditor": "vscode"
}

Core Settings

theme

Visual theme ("Default", "GitHub", "Dark")

sandbox

Enable sandboxing for safety

autoAccept

Auto-approve safe tool calls

Advanced Settings

mcpServers

Configure external tool servers

telemetry

Control data collection

fileFiltering

Control file discovery behavior

Testing Your Configuration

1. Verify Installation

gemini --version

2. Test Authentication

gemini -p "Hello! Can you confirm you can access the Gemini API?"

3. Check Configuration

gemini /about

Common Configuration Issues

API Key Not Working

Ensure your API key is valid and properly set. Check for extra spaces or quotes.

Vertex AI Authentication Fails

Run gcloud auth application-default login and verify your project permissions.

Command Not Found

If running from source, use node packages/cli/dist/index.js

Ready to explore more?

Command Reference Troubleshooting Guide