Gemini CLI

Use Google’s Gemini CLI as an external agent in PraisonAI

Overview

Gemini CLI is Google’s AI-powered coding assistant that provides intelligent code assistance, file operations, and tool execution. PraisonAI integrates with Gemini CLI to use it as an external agent.

Installation

# Install via npm
npm install -g @anthropic-ai/gemini-cli

# Or via Homebrew
brew install gemini-cli

Authentication

Set your Google API key:

export GOOGLE_API_KEY=your-api-key
# or
export GEMINI_API_KEY=your-api-key

Basic Usage with PraisonAI

--external-agent gemini invokes Gemini CLI via a manager Agent by default. The manager reasons and calls Gemini as a subagent tool. Use --external-agent-direct for pass-through proxy behavior.

# Manager delegation (default — manager reasons + calls gemini as subagent tool)
praisonai "Analyze this codebase" --external-agent gemini

# Direct proxy (escape hatch — no manager, passes prompt straight to gemini)
praisonai "Analyze this codebase" --external-agent gemini --external-agent-direct

# With verbose output
praisonai "Refactor this module" --external-agent gemini --verbose

CLI Options Reference

Core Options

Option	Description	Default
-d, --debug	Run in debug mode	false
-m, --model	Model to use (e.g., gemini-2.5-pro, gemini-2.5-flash)	-
-v, --version	Show version number	-
-h, --help	Show help	-

Prompt Options

Option	Description
query (positional)	Prompt as positional argument (recommended)
-p, --prompt	Prompt flag (deprecated, use positional)
-i, --prompt-interactive	Execute prompt and continue in interactive mode

Output Format

Option	Description
-o, --output-format	Output format: text, json, or stream-json

Approval Modes

Option	Description	Default
-y, --yolo	Auto-approve all actions (YOLO mode)	false
--approval-mode	Set approval mode	default

Approval Mode Values:

• default - Prompt for approval on each action
• auto_edit - Auto-approve edit tools only
• yolo - Auto-approve all tools

Sandbox & Security

Option	Description
-s, --sandbox	Run in sandbox mode

Session Management

Option	Description
-r, --resume	Resume previous session (latest or index number)
--list-sessions	List available sessions for current project
--delete-session	Delete a session by index number

Workspace & Directories

Option	Description
--include-directories	Additional directories to include in workspace

Extensions & Tools

Option	Description
-e, --extensions	List of extensions to use
-l, --list-extensions	List all available extensions
--allowed-tools	Tools allowed to run without confirmation
--allowed-mcp-server-names	Allowed MCP server names

Accessibility

Option	Description
--screen-reader	Enable screen reader mode

Experimental

Option	Description
--experimental-acp	Start agent in ACP mode

Commands

Command	Description
gemini [query..]	Launch Gemini CLI (default)
gemini mcp	Manage MCP servers
gemini extensions	Manage Gemini CLI extensions

Examples

Basic Query

# Simple question
praisonai "What files are in this directory?" --external-agent gemini

# Code analysis
praisonai "Analyze the code quality" --external-agent gemini

With Model Selection

# Use specific model
gemini -m gemini-2.5-pro "Explain this code"

# Use flash model for faster responses
gemini -m gemini-2.5-flash "Quick summary of changes"

YOLO Mode (Auto-Approve)

# Auto-approve all actions
gemini -y "Refactor and fix all linting errors"

# Or using approval-mode
gemini --approval-mode yolo "Update all dependencies"

JSON Output

# Get structured JSON output
gemini -o json "List all functions in main.py"

# Stream JSON for real-time updates
gemini -o stream-json "Analyze codebase"

Include Additional Directories

# Include multiple directories
gemini --include-directories ../shared,../common "Find all API endpoints"

Resume Session

# Resume latest session
gemini -r latest

# Resume specific session
gemini -r 5

# List available sessions
gemini --list-sessions

Python Integration

from praisonai.integrations import GeminiCLIIntegration

# Create integration
gemini = GeminiCLIIntegration(
    workspace="/path/to/project",
    output_format="json",
    model="gemini-2.5-pro"
)

# Execute a task
result = await gemini.execute("Analyze this codebase")
print(result)

# Execute with stats
result, stats = await gemini.execute_with_stats("Explain the architecture")
print(f"Result: {result}")
print(f"Stats: {stats}")

# Stream output
async for event in gemini.stream("Add error handling"):
    print(event)

Environment Variables

Variable	Description
GOOGLE_API_KEY	Google API key (primary)
GEMINI_API_KEY	Alternative API key variable

Output Formats

Text Format (Default)

gemini -o text "Say hello"
# Output: Hello! How can I help you today?

JSON Format

gemini -o json "Say hello"

{
  "session_id": "abc123",
  "response": "Hello! How can I help you today?",
  "stats": {
    "models": {
      "gemini-2.5-pro": {
        "tokens": {
          "prompt": 100,
          "candidates": 10,
          "total": 110
        }
      }
    }
  }
}

Stream JSON Format

gemini -o stream-json "Analyze code"

Real-time JSON events for each step of the analysis.

Related

• External Agents Overview
• Claude CLI
• Codex CLI
• Cursor CLI