Skip to main content

Gemini CLI

Gemini CLI is Google's terminal client for the Gemini model family. It reads its endpoint and credential from environment variables, so pointing it at the Cequence AI Gateway is a matter of setting them to the right values. It also reads custom headers, which is how the Agent Access Key travels when a route needs one alongside a provider key.

Which setup do you need?​

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP tools, under one set of policiesYou want the CLI to use tools as well as a model

Which credentials you send depends on the entry's credential mode. If you haven't read which credentials your entry needs, start there.

Connect to an LLM Registry entry​

Gemini CLI only supports the Gemini provider. Pick the credential mode on the entry's Provider Credential panel.

The gateway stores your Google API key, so Gemini CLI sends only its Agent Access Key.

export GOOGLE_GEMINI_BASE_URL="https://<gateway-host>/llm/<url-prefix>"
export GEMINI_API_KEY="<your-agent-access-key>"

gemini -m "<model-id>" -p "Hello"

Gemini CLI sends GEMINI_API_KEY as x-goog-api-key. The gateway authenticates the caller from that header, attaches the stored Google credential on the outbound side, and forwards to Google.

The Connect flow additionally sets GEMINI_CLI_CUSTOM_HEADERS="X-API-Key: <your-agent-access-key>", a fallback header the gateway also honours. It's harmless to include and unnecessary on its own.

Connect through an Agent Persona​

An Agent Persona bundles a set of MCP tools and, optionally, LLM access under one endpoint. Wiring Gemini CLI to it covers two sockets:

  • The tools socket, at https://<gateway-host>/p/<persona-id>, registered with gemini mcp add.
  • The model route, at https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>, set through the same environment variables as above.

One Agent Access Key covers both. The same key authenticates the model route and the tools socket, whichever Inbound Authentication method the persona uses.

note

Two separate settings are in play here, and only one of them changes the code below.

  • The entry's credential mode — API Key or Passthrough — decides which credentials you send. This is what the tabs below switch between, exactly as on the route above.
  • The persona's own Inbound Authentication method — Interactive or Passthrough — decides how the persona identifies you. Either way an Agent Access Key is issued, and neither changes the configuration below.

Because a persona always identifies you by an Agent Access Key, the entry's third mode — Passthrough (No Agent Access Key) — has no tab here. It applies to the LLM Registry entry route only.

export GOOGLE_GEMINI_BASE_URL="https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>"
export GEMINI_API_KEY="<your-agent-access-key>"
export GEMINI_CLI_CUSTOM_HEADERS="X-API-Key: <your-agent-access-key>"
export GEMINI_CLI_AIGW_AGENT_KEY="$GEMINI_API_KEY"

gemini mcp add -t http <persona-name> \
  --url "https://<gateway-host>/p/<persona-id>" \
  -H "x-api-key: ${GEMINI_API_KEY}"

What each line does:

  • GOOGLE_GEMINI_BASE_URL points Gemini CLI at the persona-scoped LLM route. That path is what makes the call flow through the persona's guardrails.
  • GEMINI_API_KEY is the Agent Access Key. Gemini CLI sends it on x-goog-api-key, which the gateway accepts on this mode.
  • GEMINI_CLI_CUSTOM_HEADERS adds the same key on X-API-Key, a fallback header the gateway also honours.
  • GEMINI_CLI_AIGW_AGENT_KEY mirrors the key for the wrapper's internal use.
  • gemini mcp add registers the persona's tool socket with the same key. From here the CLI can call the model and invoke the persona's tools with one credential.

Run gemini mcp list afterwards to confirm the persona endpoint is registered.

Registering the tools socket with a config file​

Instead of gemini mcp add, the same socket can be declared in Gemini CLI's MCP settings:

{
  "mcpServers": {
    "<persona-name>": {
      "httpUrl": "https://<gateway-host>/p/<persona-id>",
      "headers": { "X-Agent-Key": "<your-agent-access-key>" }
    }
  }
}

The headers block is always needed on this route: an Agent Access Key is required whatever the entry's credential mode.

Where to find each value​

PlaceholderWhere to find it
<gateway-host>Host from the entry's Overview tab
<url-prefix>The URL prefix field on the entry's Overview tab
<model-id>A model identifier from the entry's Allowed Models list, for example gemini-3.6-flash
<persona-id>The persona's ID on the Agent Persona page
<registry-entry-id>The LLM Registry entry's ID in the entry's URL
<persona-name>Any short name you want Gemini CLI to use for this MCP server locally
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-gemini-api-key>Your own Google Gemini API key, needed only in the passthrough modes

Tips​

  • One key covers both surfaces. In the persona setup the same Agent Access Key authenticates the LLM call and the MCP tool socket. Generate one key and use it in both places.
  • Watch the header name. X-API-Key on an API Key entry, X-Agent-Key on a passthrough one. Sending the wrong one on a passthrough route fails as though the key were invalid.
  • Restart the CLI after any env change. Gemini CLI reads its environment at startup, so export in a fresh shell before invoking gemini.
  • Verify MCP registration. Run gemini mcp list after gemini mcp add to confirm the persona endpoint is registered.
  • Unset when finished. If these variables are set only for testing, run unset GOOGLE_GEMINI_BASE_URL GEMINI_API_KEY GEMINI_CLI_CUSTOM_HEADERS GEMINI_CLI_AIGW_AGENT_KEY before returning to your normal Gemini CLI usage.
Last updated on