Use Gemini CLI with a Custom Vana API Endpoint

Agents at the terminalEN2026-10-24

Gemini CLI can connect to a compatible endpoint instead of sending requests directly to Google's default service. The important details are the authentication method, the base URL, and the model identifier. This walkthrough connects Gemini CLI to Vana API using the Gemini native protocol.

Vana API provides one endpoint that supports OpenAI-compatible requests, Anthropic Messages, and Gemini native requests. For this setup, use the Gemini interface rather than trying to configure Gemini CLI as an OpenAI client.

§ 1. Prepare your API key and model identifier

Create a Vana API account, then obtain an API key and check the available model identifiers in your account. Keep the key private, and make sure the account has sufficient balance before testing.

Choose a Gemini model available through the service, such as Gemini 2.5 Flash. Copy its exact API identifier rather than assuming the display name is accepted as a request parameter. In the commands below, replace MODEL_ID_FROM_VANA with that identifier.

Vana API bills by actual token usage, with no monthly fee. A short verification prompt keeps the initial test small.

§ 2. Install or update Gemini CLI

Install a current Node.js release supported by Gemini CLI, then install the CLI with npm. Run this command in your terminal:

 1  npm install -g @google/gemini-cli

Confirm that the executable is available:

gemini --version

If you already have Gemini CLI installed, updating it before configuring a custom endpoint can avoid problems caused by older authentication or endpoint-handling behavior.

§ 3. Set the endpoint and API key

In a Bash terminal, set the Gemini base URL to Vana API:

 1  export GOOGLE_GEMINI_BASE_URL="https://api.vanaapi.com"

Use the service root here, not an OpenAI chat-completions URL. Gemini's client constructs native API request paths from the base URL; adding an unrelated protocol path can produce invalid routes.

Next, read the API key without displaying it or putting its literal value into shell history:

read -r -s -p "Vana API key: " GEMINI_API_KEY; printf '\n'; export GEMINI_API_KEY

Paste your key at the prompt and press Enter. These variables apply to the current shell and programs launched from it. Another terminal will need its own configuration.

If you previously enabled Vertex AI mode, remove that setting from this shell before continuing:

unset GOOGLE_GENAI_USE_VERTEXAI

§ 4. Select API-key authentication

Start Gemini CLI with your chosen model identifier:

gemini --model "MODEL_ID_FROM_VANA"

If the CLI asks how to authenticate, choose the Gemini API key option rather than Google account sign-in or Vertex AI. If it opens with an existing sign-in configuration, enter /auth and switch to API-key authentication.

This distinction matters: a custom Gemini API endpoint and its key belong to the API-key flow. Google account authentication is a separate route and should not be used to validate this configuration.

§ 5. Send a minimal verification prompt

Ask the CLI: Reply with one short sentence confirming you received this message. Do not use tools.

A successful reply confirms that a request completed, but the answer's wording does not prove which endpoint handled it. Check the corresponding usage record in Vana API to confirm routing and billing. Avoid asking the model to identify its provider as a verification method.

§ 6. Troubleshoot before starting real work

Authentication error: Check that GEMINI_API_KEY contains your Vana API key and that the CLI is using API-key authentication.
Model not found: Copy the exact supported identifier from Vana API. A display name and an API identifier may differ.
Route not found: Confirm that GOOGLE_GEMINI_BASE_URL is the service root and does not include an OpenAI-specific path.
Unexpected Google sign-in: Revisit /auth and check inherited environment variables and saved CLI settings.
Chat works but tools fail: Test tool use separately. Native protocol support does not guarantee that every model supports every CLI capability identically.

Once the minimal request succeeds, try a small task in a non-sensitive project directory. Review file changes and permission prompts before expanding the workflow, and keep API keys out of repositories and shared logs.