Gemini CLI

Revision 1 · Updated 2026-11-12 · 3 min read

Connect Gemini CLI to Runtoken.

Prerequisites#

Before you start, prepare:

A working Gemini CLI installation; run gemini --version. See the official instructions if needed.
A Runtoken platform API key.
The exact model ID for the native Gemini v1beta route.

Connection settings#

Set the following values in a separate terminal.

Variable or option	Value	Purpose
`GOOGLE_GEMINI_BASE_URL`	`https://api.runtoken.net`	Base host for Gemini API requests; do not append `/v1` or a model path.
`GEMINI_API_KEY`	`YOUR_PLATFORM_KEY`	Platform key used for the selected API-key authentication mode.
`GOOGLE_GENAI_API_VERSION`	`v1beta`	Selects the gateway's native API version.
`--model`	`YOUR_MODEL_ID`	Selects the exact model from the platform catalogue.

The SDK adds the version and model method to the base host. This differs from the OpenAI-style /v1 address used by other clients.

Set credentials and launch#

Run the commands in a small test project. They set the current terminal environment rather than writing a key into project files.

bash

export GOOGLE_GEMINI_BASE_URL="https://api.runtoken.net"
export GOOGLE_GENAI_API_VERSION="v1beta"
export GEMINI_API_KEY="YOUR_PLATFORM_KEY"
gemini --model "YOUR_MODEL_ID"

$env:GOOGLE_GEMINI_BASE_URL = "https://api.runtoken.net"
$env:GOOGLE_GENAI_API_VERSION = "v1beta"
$env:GEMINI_API_KEY = "YOUR_PLATFORM_KEY"
gemini --model "YOUR_MODEL_ID"

Replace YOUR_PLATFORM_KEY with your platform key and YOUR_MODEL_ID with the exact Gemini-protocol model ID. Keep real keys out of shared files and screenshots; terminal history can retain commands containing them.

Select Use Gemini API key when prompted. If a different authentication mode is already active, use /auth to select the API-key route. Check existing .env files and managed settings when unexpected credentials or endpoints take effect; do not delete an existing Google-account login to diagnose a gateway request.

Check the connection and file task#

Send a short message and locate its matching Runtoken request record. Compare the selected model and request time; a reply alone does not establish that the API-key gateway route is active.

Then try this task in the test project.

Check file creation and a follow-uptext

Create greeting.py with greet(name), returning "Hello, " plus name.
Read the file back. Do not install dependencies or access the network.

Inspect and approve the necessary file action. In the same session, ask for an empty name to return "Hello, friend". Read the actual file and check that the follow-up completed after the tool result was returned.

Capabilities and limits#

Choose a specific platform model ID rather than assuming the CLI's automatic model selection maps to your catalogue. Auxiliary requests may use different models or API methods from the main conversation.

Capability	Integration requirement
Streaming conversation	Compatible native generation request and SSE response.
File and shell tools	Model support for tool calls plus client permissions.
Token counting, compression and auxiliary models	Support for the particular method and model requested.
File resources, explicit cache and hosted search	Separate platform support; changing the base host does not provide it.

Runtoken does not convert an OpenAI model into a native Gemini model. Do not change API versions or tool options at random to work around a rejected request.

Troubleshooting#

Use the request method and error body to identify which part failed.

Symptom	What to check
Requests still use Google-account authentication	Use `/auth` and check the selected mode.
`401` or rejected key	Check the platform key, active auth mode and inherited environment without printing the key.
`404`	Check the base host, `v1beta`, requested method and exact model ID.
Main chat works but another request fails	Identify whether an auxiliary model, token-counting method or tool was requested.
`429`	Follow the limit and reset details returned by the platform.

Restore settings and further reading#

Close the test terminal to discard its environment changes. If you changed the saved authentication selection, use /auth to restore the previous mode. Restore only the settings you changed.

See Gemini v1beta, the official authentication guide and CLI configuration.

Was this page helpful?