> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agipower.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini cli

# 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](#get-a-agipower-api-key) below)

## Install Gemini CLI

```bash title="npm (Recommended)" theme={null}
npm install -g @google/gemini-cli
```

```bash title="pnpm" theme={null}
pnpm install -g @google/gemini-cli
```

```bash title="npx (Try without installing)" theme={null}
npx @google/gemini-cli
```

Verify the installation:

```bash theme={null}
gemini --version
```

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

## Get a AGIPower API Key

```text title="Subscription API Key (Recommended)" theme={null}
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
```

```text title="Pay-as-you-go API Key" theme={null}
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

```bash theme={null}
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:

```env theme={null}
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:

```bash title="macOS/Linux/WSL" theme={null}
# Edit ~/.zshrc or ~/.bashrc
export GEMINI_API_KEY="sk-ss-v1-xxx"  # [!code highlight]
export GEMINI_MODEL="google/gemini-2.5-pro"  # [!code highlight]
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"  # [!code highlight]
```

```powershell title="Windows PowerShell" theme={null}
# Edit your PowerShell profile
$env:GEMINI_API_KEY = "sk-ss-v1-xxx"  # [!code highlight]
$env:GEMINI_MODEL = "google/gemini-2.5-pro"  # [!code highlight]
$env:GOOGLE_GEMINI_BASE_URL = "https://api.agipower.ai"  # [!code highlight]

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

<Warning title="Important">
  Be sure to replace `sk-ss-v1-xxx` with your real AGIPower API Key. You can get your API Key in the [AGIPower Console](https://agipower.ai/settings/keys).
</Warning>

#### 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:

```json theme={null}
{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key" // [!code highlight]
    }
  }
}
```

<Tip title="Configuration Notes">
  * `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
</Tip>

#### Step 4: Verify connectivity

```bash theme={null}
# 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  # [!code highlight]
```

If the response contains `"response": "OK"`, the basic connection is working.

Next, test read-only file analysis:

```bash theme={null}
# 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  # [!code highlight]
```

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:

```bash theme={null}
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  |
| `&lt;project-root&gt;/GEMINI.md` | Project   | Project-specific rules and conventions |
| `&lt;current-dir&gt;/GEMINI.md`  | Directory | Subdirectory-specific context          |

<Tip title="GEMINI.md Writing Tips">
  * 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`
</Tip>

### 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 &lt;text&gt;` | 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**: `&lt;project-root&gt;/.gemini/commands/` — available only in the current project

For example, create a `/plan` command:

```toml theme={null}
# ~/.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:

```bash theme={null}
# 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`:

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}
```

### Non-Interactive Mode

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

```bash theme={null}
# 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:

```bash theme={null}
# Set in .gemini/.env or your shell profile
export GEMINI_MODEL="google/gemini-2.5-pro"  # [!code highlight]
```

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 |

<Info title="Get the model list">
  * View available Google AI protocol models via the [AGIPower model list](https://agipower.ai/models?sort=newest\&supported_protocol=google)
  * Use the model slug (e.g., `google/gemini-2.5-pro`)
  * To route to a specific provider, see the [Provider Routing docs](/en/guide/advanced/provider-routing)
</Info>

<Tip title="Switching models">
  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.
</Tip>

<h2 id="tool-call-error">
  Known Issue: Tool Calls Error \\
</h2>

<Warning title="Tool call error: Unknown name &#x22;id&#x22; at function_response">
  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.
</Warning>

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

1. 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
   ```

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

   ```js theme={null}
   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,
       };
   ```

3. Save the file and restart Gemini CLI.

<Tip title="Notes">
  * 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
</Tip>

## Troubleshooting

### Common Issues and Fixes

#### Gemini CLI prompts for Google sign-in after startup

**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](https://agipower.ai/settings/keys)

#### 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 `export`ed 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

#### function\_response-related errors when editing files

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

```text theme={null}
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](#tool-call-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](https://agipower.ai/models?sort=newest\&supported_protocol=google)
* 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:

```bash theme={null}
mkdir -p <project-root>/.gemini
```

```json title="Project-level settings.json" theme={null}
// <project-root>/.gemini/settings.json
{
  "model": {
    "name": "google/gemini-2.5-pro"
  }
}
```

```env title="Project-level .env" theme={null}
# <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

<Warning title="Security Notice">
  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.
</Warning>

### Session Retention

Gemini CLI supports retaining session history for reviewing previous conversations:

```json theme={null}
{
  "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

```bash title="Daily Development" theme={null}
# 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"
```

```bash title="Code Review" theme={null}
# 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"
```

```bash title="Rapid Iteration" theme={null}
# 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"
```

<Tip title="Contact Us">
  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](https://agipower.ai)
  * **Support email**: [support@agipower.ai](mailto:support@agipower.ai)
  * **Business inquiries**: [support@agipower.ai](mailto:support@agipower.ai)
  * **Twitter**: [@AGIPowerAI](https://twitter.com/AGIPowerAI)
  * **Discord community**: [http://discord.gg/vHZZzj84Bm](http://discord.gg/vHZZzj84Bm)

  For more contact channels and details, visit our [Contact Us page](/en/help/contact).
</Tip>