Gemini CLI: Advanced Customization

Welcome to Part 3 of the Gemini CLI tutorial series. In the previous post, we explored the built-in tools and how they work.

Gemini CLI out-of-the-box is powerful. But customized for YOUR needs, it becomes unstoppable.

In this post, we’ll dive into configuration files (settings.json and .env) and show you how to customize Gemini CLI to match your specific needs and preferences.

The ~/.gemini/ Configuration Directory

When you first run Gemini CLI, it creates a configuration directory at ~/.gemini/ (in your home folder). This directory contains all your settings, authentication tokens, and customizations.

Let’s explore what’s in there:

ls -la ~/.gemini/

You should see files like:

• config.json or settings.json - Main configuration
• .env - Environment variables
• history - Conversation history
• extensions/ - Installed MCP servers and extensions

Configuration with settings.json

The settings.json file is where you define how Gemini CLI behaves. Here’s what you can configure:

Example Configuration

{ "model": "gemini-2.5-pro", "theme": "dark", "outputFormat": "markdown", "defaultContext": "default", "sandbox": false, "codeExecution": { "enabled": true, "languages": ["python", "javascript", "bash"] }, "tools": { "fileSystem": { "enabled": true, "maxSize": "100mb" }, "shell": { "enabled": true, "restrictedCommands": ["rm -rf /", "sudo"] }, "search": { "enabled": true } } }

Key Configuration Options

Model Selection

"model": "gemini-2.5-pro"

Available models:

• gemini-2.5-pro - Latest high-performance model
• gemini-2.0-flash - Fast, efficient model
• gemini-1.5-pro - Previous generation

Theme

"theme": "dark"

Options: dark, light, or a custom theme name

Output Format

"outputFormat": "markdown"

Options: markdown, text, html, json

Sandbox Mode

"sandbox": false

When true, isolates AI operations to prevent dangerous file or shell operations

Environment Variables with .env

The .env file stores sensitive information and environment-specific settings:

# .env file GEMINI_API_KEY=your-api-key-here GEMINI_MODEL=gemini-2.5-pro GEMINI_MAX_TOKENS=8000 GEMINI_TEMPERATURE=0.7 GEMINI_TOP_P=0.95

Key Environment Variables

# Authentication GEMINI_API_KEY=your-key # Gemini API key GOOGLE_APPLICATION_CREDENTIALS # Path to GCP service account JSON # Model Parameters GEMINI_MODEL=gemini-2.5-pro # Which model to use GEMINI_MAX_TOKENS=8000 # Max response length GEMINI_TEMPERATURE=0.7 # Creativity (0-1, higher = more creative) GEMINI_TOP_P=0.95 # Diversity (0-1) GEMINI_TOP_K=40 # Top K tokens to consider # Behavior GEMINI_SANDBOX=false # Enable/disable sandbox GEMINI_VERBOSE=true # Show detailed output GEMINI_CONTEXT_SIZE=50000 # Context window size

Creating Custom Commands (Slash Commands)

Gemini CLI supports custom slash commands. Create them in ~/.gemini/commands/:

Example: Custom Code Formatter Command

Create ~/.gemini/commands/format-code.json:

{ "name": "format", "description": "Format and clean up code with suggestions", "prompt": "Format and improve this code. Check for:\n- Proper indentation\n- Naming conventions\n- Error handling\n- Comments where needed\n\nCode:\n{input}" }

Use it:

/format [paste your code here]

Example: Custom Documentation Generator

Create ~/.gemini/commands/docgen.json:

{ "name": "docgen", "description": "Generate API documentation", "prompt": "Generate comprehensive API documentation in Markdown for this code. Include:\n- Function descriptions\n- Parameters and return types\n- Example usage\n- Error codes\n\nCode:\n{input}" }

Use it:

/docgen [paste your API code here]

Example: Quick Test Case Generator

Create ~/.gemini/commands/testgen.json:

{ "name": "testgen", "description": "Generate unit test cases", "prompt": "Generate pytest test cases for this function. Include:\n- Happy path tests\n- Edge cases\n- Error scenarios\n- Mocking where needed\n\nFunction:\n{input}" }

System Prompts and Instructions

Set default instructions for every conversation:

Create ~/.gemini/instructions.md:

# System Instructions for Gemini CLI ## You are a helpful coding assistant. ### Guidelines: - Always provide working code examples - Explain concepts clearly - Suggest best practices - Ask clarifying questions when needed ### Constraints: - Don't suggest using deprecated libraries - Always recommend security best practices - Test code before suggesting it

Gemini CLI will use these as baseline instructions for all conversations.

Managing Multiple Contexts

Separate your work by creating multiple contexts for different projects:

# List all contexts /context list # Create a new context for a project /context create my-project # Switch to a context /context switch my-project # View current context /context info

Each context maintains its own conversation history and can have different settings.

Advanced: Programmatic Configuration

You can also configure Gemini CLI programmatically. For example, set a project-specific config:

Create GEMINI.md in your project root:

# Project Configuration for Gemini CLI ## Model Settings - Model: gemini-2.5-pro - Max Tokens: 4000 - Temperature: 0.5 ## Project Context This is a Flask web application project. Consider: - Python best practices - Flask framework patterns - Database migration strategies ## Relevant Files - app.py - Main Flask application - requirements.txt - Python dependencies - config.py - Configuration settings

When you launch Gemini CLI from this project:

gemini

It automatically loads the GEMINI.md file as context!

Best Practices for Configuration

1. Use .env for secrets - Never commit API keys to version control
2. Create project-specific contexts - Keep work organized
3. Set appropriate sandbox settings - Balance flexibility with safety
4. Version your configurations - Commit settings.json to git (without secrets)
5. Document custom commands - Help your team understand available commands

Troubleshooting Configuration

Check current configuration:

/config show

Reset to defaults:

/config reset

View which config file is being used:

/config path

Part 4 Preview

In Part 4, we’ll dive deeper into the built-in tools available and show you how to use each one effectively with real-world examples.

In Part 5, we’ll explore MCP (Model Context Protocol) servers to dramatically expand Gemini CLI’s capabilities with integrations like GitHub, Firebase, and Google Workspace.

Resources

• Gemini CLI Configuration Docs
• Official Tutorial Series - Part 3
• GitHub Repository