Gemini CLI

Gemini CLI is an open-source terminal agent launched by Google, allowing users to understand projects, analyze files, and use commands and tools after obtaining authorization within the terminal. By configuring the Gemini API address, API Key, and model ID, Gemini CLI can use AGTCloud's Gemini Generate Content compatible entry.

This tutorial only covers the basic connection and security verification process of the Gemini CLI. File modification, shell commands, function calls, and other agent capabilities depend on the target model and the actual support of the corresponding model for Gemini Parts, Function Call, and other protocol structures.

Preparation

Before you start, please confirm that you have:

• Install Node.js 20 or higher;
• Prepare Bash, Zsh, or PowerShell terminals;
• Create the AGTCloud API Key on the API Keys page;
• Copy the model ID from the Model Marketplace which is available to the current API Key and supports Gemini Generate Content;
• Prepare a test directory that does not contain sensitive code and production credentials.

MODEL_ID is the placeholder to be replaced, not the actual model name. Please use the model ID visible with the current API Key that supports Gemini Generate Content.

Install Gemini CLI

It is recommended to install the current stable version. Different installation methods yield the same gemini command.

npm install -g @google/gemini-cli

Check the version after installation:

gemini --version

If it prompts that the command cannot be found, please open the terminal again and confirm that the npm global command directory has been added to the PATH.

Configure AGTCloud

The Gemini CLI requires four environment variables: API Key, model ID, custom Gemini API address, and Bearer authentication method.

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

Configuration item description

This tutorial does not set GOOGLE_GENAI_API_VERSION, so Gemini CLI uses the Gemini API's default v1beta version. Do not put the full generateContent request path in the Base URL.

Save user-level configuration

After confirming that the temporary configuration works, you can save the variables in Gemini CLI's user-level .env file. This file may contain a real API Key, so do not commit it to a code repository.

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI searches for environment files in the current working directory and its parent directories. A project-level .env or .gemini/.env file may take precedence over the user-level configuration. If your settings are not taking effect, check these files first.

Fixed API Key Authentication Method

Gemini CLI supports various Google authentication methods. When using through AGTCloud, you should choose Gemini API Key, rather than Google login or Vertex AI.

Merge the following configuration into the user-level settings.json without overwriting the existing theme, permissions, or other settings:

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

Configuration file location:

After saving, exit Gemini CLI completely and restart it. selectedType selects API Key authentication, while GEMINI_API_KEY_AUTH_MECHANISM=bearer makes Gemini CLI send the Bearer header required by AGTCloud. Both settings are required.

Choose a model

The default model is determined by GEMINI_MODEL. If you need to temporarily specify a model for a single session, you can run:

gemini --model MODEL_ID

/model is an additional way to select a model, but its list may not include every model available to the current AGTCloud API Key. If a model is missing, copy its full ID from the Model Marketplace and specify it with GEMINI_MODEL or the interactive-session --model option.

Verify connection

gemini -p "Please only reply: AGTCloud connection successful." --output-format json

gemini -p "@README.md Please summarize the project purpose in three points without modifying any files." --output-format json

gemini

Frequently Asked Questions

If you encounter issues that cannot be located, record the request time, API Base URL, model ID, Gemini CLI version, HTTP status, and redacted error messages, then review Errors and Troubleshooting. Do not submit the full API Key or .env files containing credentials.

Safety advice

• Do not write real API keys into repositories, share scripts, screenshots, logs, or chat logs;
• It is recommended to first use temporary environment variables for verification, and only save user-level configurations after success;
• Set appropriate local access permissions for .env files and avoid syncing to public cloud drives;
• Maintain manual approval when first using tool capabilities and validate them in non-production projects;
• Before sharing troubleshooting information, delete the full Key, username, local path, and business source code.

Next

• API Key, Base URL, and Authentication
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• Protocol Selection
• Errors and Troubleshooting