Guide to Using Gemini CLI with AGIPower

Gemini CLI is an open-source AI terminal agent tool released by Google that brings Gemini’s capabilities directly into your terminal. Built on the ReAct (Reason + Act) loop architecture, it can autonomously handle complex tasks such as coding, debugging, file operations, and content generation. Gemini CLI offers a 1M-token context window, a request rate limit of 60 requests/minute, and rich MCP tool integration. With AGIPower, you can configure a custom API endpoint for Gemini CLI, enabling more flexible model selection and a more stable service experience.

Prerequisites

Node.js 18+
AGIPower API Key (see Get a AGIPower API Key below)

Install Gemini CLI

npm (Recommended)

npm install -g @google/gemini-cli

pnpm

pnpm install -g @google/gemini-cli

npx (Try without installing)

npx @google/gemini-cli

Verify the installation:

gemini --version

After installation, type gemini in your terminal to start it.

Get a AGIPower API Key

Subscription API Key (Recommended)

Use cases: personal development, learning/exploration, lightweight team collaboration
Features: fixed monthly fee, predictable cost
API Key format: sk-ss-v1-xxx

How to get:
1. Visit https://agipower.ai/platform/subscription
2. Choose a plan
3. Create a subscription API Key in the console

Pay-as-you-go API Key

Use cases: production, commercial products, enterprise applications
Features: billed by actual usage, convenient for centralized cost accounting
API Key format: sk-xxx

How to get:
1. Visit https://agipower.ai/platform/pay-as-you-go
2. Top up your account
3. Create a pay-as-you-go API Key in the console

Configuration

A simple setup—connect in minutes with just 3 environment variables.

Step 1: Create the config directory

mkdir -p ~/.gemini

Step 2: Configure environment variables

You can configure environment variables in ~/.gemini/.env. Gemini CLI will automatically load them from this file:

GEMINI_API_KEY=sk-ss-v1-xxx  # [!code highlight]
GEMINI_MODEL=google/gemini-2.5-pro  # [!code highlight]
GOOGLE_GEMINI_BASE_URL=https://api.agipower.ai  # [!code highlight]

Alternatively, set them in your shell profile:

macOS/Linux/WSL

# Edit ~/.zshrc or ~/.bashrc
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GEMINI_MODEL="google/gemini-2.5-pro"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"

Windows PowerShell

# Edit your PowerShell profile
$env:GEMINI_API_KEY = "sk-ss-v1-xxx"
$env:GEMINI_MODEL = "google/gemini-2.5-pro"
$env:GOOGLE_GEMINI_BASE_URL = "https://api.agipower.ai"

# To make it persistent, add it to your PowerShell profile:
# notepad $PROFILE

Be sure to replace sk-ss-v1-xxx with your real AGIPower API Key. You can get your API Key in the AGIPower Console.

Step 3: Configure settings.json

Set the auth method to Gemini API Key to avoid being prompted to sign in with Google when Gemini CLI starts:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

GEMINI_API_KEY: your AGIPower API Key
GEMINI_MODEL: the model to use (any AGIPower-supported Google model)
GOOGLE_GEMINI_BASE_URL: AGIPower Vertex AI–compatible endpoint
selectedType: auth type—set to gemini-api-key to skip Google sign-in

Step 4: Verify connectivity

# Reload your profile (if you configured via shell profile)
source ~/.zshrc  # or source ~/.bashrc

# Minimal smoke test
gemini -p "Reply with OK only." --output-format json

If the response contains "response": "OK", the basic connection is working. Next, test read-only file analysis:

# Go to any project directory
cd my-project

# Reference a file for analysis
gemini -p "@README.md Summarize this file in one sentence." --output-format json

If it can read the file and return a summary, AGIPower + Gemini CLI read-only analysis is working.

Authentication

Gemini CLI natively supports multiple authentication methods:

Method	Use Case	Notes
Google Account (OAuth)	Local dev	Highest free tier: 60 RPM / 1000 RPD
API Key	CI/CD, scripts	Set via the `GEMINI_API_KEY` env var

When using AGIPower, choose the API Key method and set your AGIPower API Key in the GEMINI_API_KEY environment variable. To re-authenticate, run:

gemini --reauth

Core Features

GEMINI.md Context File

GEMINI.md is one of Gemini CLI’s core features, similar to Claude Code’s CLAUDE.md. It serves as persistent context that is automatically loaded at the start of each session, helping the AI understand the project background and conventions. Gemini CLI searches for and merges GEMINI.md files in the following order:

Location	Scope	Description
`~/.gemini/GEMINI.md`	Global	General instructions for all projects
`<project-root>/GEMINI.md`	Project	Project-specific rules and conventions
`<current-dir>/GEMINI.md`	Directory	Subdirectory-specific context

Describe the project’s tech stack and architecture
Specify coding style and naming conventions
Document build, test, and deployment workflows
List commonly used project commands
Support importing other files via @path/to/file.md

Common Slash Commands

Gemini CLI provides many built-in commands to manage sessions and configuration:

Command	Description
`/help`	Show help and the list of available commands
`/stats`	View token usage and statistics for the session
`/memory show`	Show the currently loaded GEMINI.md context
`/memory add <text>`	Add content to the AI’s memory
`/theme`	Switch the UI theme
`/tools`	List currently available tools
`/mcp`	Manage MCP server connections
`/chat`	Save and restore chat history
`/copy`	Copy the latest output to the clipboard

Custom Slash Commands

Gemini CLI supports custom commands stored in:

Global commands: ~/.gemini/commands/ — available across all projects
Project commands: <project-root>/.gemini/commands/ — available only in the current project

For example, create a /plan command:

# ~/.gemini/commands/plan.toml
[command]
description = "Plan changes without implementing"

[command.prompt]
content = """
Please analyze the following request and provide a detailed step-by-step plan.
Do NOT implement any changes — only plan them.

Request: $input
"""

MCP Integration

Gemini CLI supports MCP (Model Context Protocol) servers to extend tool capabilities:

# Add an MCP server
gemini mcp add <server-name> -- <command>

# List configured MCP servers
gemini mcp list

# Remove an MCP server
gemini mcp remove <server-name>

You can also configure MCP servers in settings.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

Non-Interactive Mode

Gemini CLI supports non-interactive usage, suitable for scripts and CI:

# One-off Q&A with JSON output
gemini -p "Explain what a REST API is" --output-format json

# Reference a file for analysis
gemini -p "@src/main.ts What is this file’s entry-point logic?" --output-format json

Supported Models

With AGIPower, you can use multiple Gemini models in Gemini CLI. Use the GEMINI_MODEL environment variable to specify a model:

# Set in .gemini/.env or your shell profile
export GEMINI_MODEL="google/gemini-2.5-pro"

Recommended models for Gemini CLI:

Model Name	Model Slug	Notes
Gemini 2.5 Pro	`google/gemini-2.5-pro`	Google’s flagship model (recommended)
Gemini 2.5 Flash	`google/gemini-2.5-flash`	Faster responses; ideal for rapid iteration

View available Google AI protocol models via the AGIPower model list
Use the model slug (e.g., google/gemini-2.5-pro)
To route to a specific provider, see the Provider Routing docs

Even if a model name switch works, it does not guarantee tool calling will work as well. Current limitations mainly come from AGIPower’s compatibility with the Gemini CLI Agent protocol, not just the model itself.

Known Issue: Tool Calls Error \

When the model tries to use built-in tools (such as Google Search), you may see the following error:

[API Error: {"error":{"code":"400","type":"invalid_params","message":"Invalid JSON payload received. Unknown name \"id\" at 'contents[...].parts[0].function_response': Cannot find field."}}]

Cause: When Gemini CLI sends tool call results to the API, it includes an id field in functionResponse. This field is not yet supported in some API versions, causing the request to be rejected.

Temporary workaround: Modify the locally installed Gemini CLI file and comment out passing callId.

Locate the file (replace the Node version in the path with your actual version):

~/.nvm/versions/node/<version>/lib/node_modules/@google/gemini-cli/node_modules/@google/gemini-cli-core/dist/src/core/turn.js

Find the handlePendingFunctionCall method (around line 183) and comment out callId,:

handlePendingFunctionCall(fnCall, traceId) {
    const name = fnCall.name || 'undefined_tool_name';
    const args = fnCall.args || {};
    const callId = fnCall.id ?? `${name}_${Date.now()}_${this.callCounter++}`;
    const toolCallRequest = {
        // callId,  // [!code warning]
        name,
        args,
        isClientInitiated: false,
        prompt_id: this.prompt_id,
        traceId,
    };

Save the file and restart Gemini CLI.

You must re-apply this change after each Gemini CLI update or reinstall
Once AGIPower completes function calling compatibility, this will be supported automatically and you won’t need this modification

Troubleshooting

Common Issues and Fixes

Issue: A Google OAuth sign-in page opens when starting Gemini CLI. Solution:

Check whether selectedType in ~/.gemini/settings.json is correctly set to "gemini-api-key"
Verify the config using cat ~/.gemini/settings.json

API Key error

Issue: The API Key is reported as invalid or unauthorized. Solution:

Check that the API Key is correct (subscription keys start with sk-ss-v1-, pay-as-you-go keys start with sk-)
Ensure the API Key is active and has sufficient balance
Verify the key status in the AGIPower Console

Connection failure

Issue: Gemini CLI cannot connect to AGIPower. Solution:

Check your network connection
Verify the Base URL is set to https://api.agipower.ai
Check whether firewall settings are blocking outbound connections
Try curl https://api.agipower.ai/models to test connectivity

.env file not taking effect

Issue: Variables set in ~/.gemini/.env do not take effect. Solution:

Gemini CLI loads .env using a nearest-first rule; once it finds the first one, it stops
Check whether there is already a .env or .gemini/.env in the current project directory (it will override the global config)
Check whether the same variables were already exported in your shell: env | grep -E "GEMINI_|GOOGLE_"
Check whether an earlier .env file exists in a parent directory that is being matched first
Reopen the terminal window, or run source ~/.zshrc to reload your profile

Issue: When attempting to have Gemini CLI edit files automatically, you see errors like:

Invalid JSON payload received. Unknown name "id" at 'contents[3].parts[0].function_response': Cannot find field.

Solution:

This is a known limitation—see the Tool Calls Error section
For now, limit usage to Q&A and read-only analysis
Do not rely on Gemini CLI for agent actions such as auto-editing or command execution
Once AGIPower completes function calling compatibility, this will be supported automatically

Model unavailable

Issue: A model is reported as unavailable or unsupported. Solution:

Check availability via the AGIPower model list
Verify the spelling of the model name in the GEMINI_MODEL environment variable
Try a default model such as google/gemini-2.5-pro
Confirm your account has access to the model

Occasional request timeouts

Issue: Read-only file analysis requests occasionally time out. Solution:

Retrying usually works
Reduce the size of the prompt and referenced files
If timeouts are frequent, try a smaller model (e.g., google/gemini-2.5-flash)
Check that your network connection is stable

Sandbox mode issues

Issue: Command execution fails after enabling sandbox mode. Solution:

Ensure Docker is installed
Check that Docker is running: docker ps
Try disabling sandbox mode to test: set "sandbox": false in settings.json
If using a custom sandbox, check the .gemini/sandbox.Dockerfile configuration

Advanced Configuration

Project-Level Configuration

Gemini CLI supports creating a separate configuration in the project root to override global settings:

mkdir -p <project-root>/.gemini

Project-level settings.json

// <project-root>/.gemini/settings.json
{
  "model": {
    "name": "google/gemini-2.5-pro"
  }
}

Project-level .env

# <project-root>/.gemini/.env
GEMINI_MODEL=google/gemini-2.5-pro

Use cases:

Different projects use different models
Teams standardize default behavior
Commercial projects use pay-as-you-go keys, personal projects use subscription keys

Do not commit .env files containing real API keys to your repository. If you need to share configuration with your team, consider committing only a settings.json template.

Session Retention

Gemini CLI supports retaining session history for reviewing previous conversations:

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d"
    }
  }
}

Session history is stored in ~/.gemini/history/. Adjust maxAge as needed, or set it to false to disable retention.

Recommended Configurations for Different Scenarios

Daily Development

# Balance performance and cost
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-pro"

Code Review

# Prioritize reasoning capability
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-pro"

Rapid Iteration

# Prioritize response speed
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-flash"

If you run into any issues while using the service, or if you have suggestions and feedback, feel free to reach out through:

Official website: https://agipower.ai
Support email: support@agipower.ai
Business inquiries: support@agipower.ai
Twitter: @AGIPowerAI
Discord community: http://discord.gg/vHZZzj84Bm

For more contact channels and details, visit our Contact Us page.

About AGIPower

API Reference

Best Practices

Help Center

Gemini cli

Guide to Using Gemini CLI with AGIPower

Prerequisites

Install Gemini CLI

Get a AGIPower API Key

Configuration

Step 1: Create the config directory

Step 2: Configure environment variables

Step 3: Configure settings.json

Step 4: Verify connectivity

Authentication

Core Features

GEMINI.md Context File

Common Slash Commands

Custom Slash Commands

MCP Integration

Non-Interactive Mode

Supported Models

Known Issue: Tool Calls Error \

Troubleshooting

Common Issues and Fixes

API Key error

Connection failure

.env file not taking effect

Model unavailable

Occasional request timeouts

Sandbox mode issues

Advanced Configuration

Project-Level Configuration

Session Retention

Recommended Configurations for Different Scenarios

About AGIPower

API Reference

Best Practices

Help Center

Documentation Index

​Guide to Using Gemini CLI with AGIPower

​Prerequisites

​Install Gemini CLI

​Get a AGIPower API Key

​Configuration

​Step 1: Create the config directory

​Step 2: Configure environment variables

​Step 3: Configure settings.json

​Step 4: Verify connectivity

​Authentication

​Core Features

​GEMINI.md Context File

​Common Slash Commands

​Custom Slash Commands

​MCP Integration

​Non-Interactive Mode

​Supported Models

​Known Issue: Tool Calls Error \

​Troubleshooting

​Common Issues and Fixes

​Gemini CLI prompts for Google sign-in after startup

​API Key error

​Connection failure

​.env file not taking effect

​function_response-related errors when editing files

​Model unavailable

​Occasional request timeouts

​Sandbox mode issues

​Advanced Configuration

​Project-Level Configuration

​Session Retention

​Recommended Configurations for Different Scenarios

Guide to Using Gemini CLI with AGIPower

Prerequisites

Install Gemini CLI

Get a AGIPower API Key

Configuration

Step 1: Create the config directory

Step 2: Configure environment variables

Step 3: Configure settings.json

Step 4: Verify connectivity

Authentication

Core Features

GEMINI.md Context File

Common Slash Commands

Custom Slash Commands

MCP Integration

Non-Interactive Mode

Supported Models

Known Issue: Tool Calls Error \

Troubleshooting

Common Issues and Fixes

Gemini CLI prompts for Google sign-in after startup

API Key error

Connection failure

.env file not taking effect

function_response-related errors when editing files

Model unavailable

Occasional request timeouts

Sandbox mode issues

Advanced Configuration

Project-Level Configuration

Session Retention

Recommended Configurations for Different Scenarios