Gemini CLI Against a Native Relay: First-Run Checklist

§1 Start with the native protocol, not just an API key

Connecting Gemini CLI to a relay takes more than replacing a hostname. The CLI needs a compatible Gemini API surface, the correct authentication mode, and a model identifier the relay actually accepts. This checklist helps you separate those requirements before debugging your first prompt.

Fluxio is a streaming-first, pay-per-token AI API relay that works with Gemini CLI and other development tools. It is worth considering when you want one key across providers, but this setup must use its native Gemini route rather than assume an OpenAI-compatible endpoint is interchangeable.

§2 Confirm the relay endpoint and model identifier

Fluxio publishes https://api.fluxioapi.com as its API base. OpenAI-style clients add /v1, but that does not establish the correct base for Gemini CLI. Confirm the native Gemini base URL and any required path prefix in the current relay documentation or dashboard before continuing.

• – Confirm that the route supports Gemini-native generation requests.
• – Check whether streaming generation is supported on the same route.
• – Copy an exact supported model identifier instead of deriving one from a display name.
• – Check account access and pricing for your selected model.

$ Gemini 2.5 Flash is a reasonable example for an initial, lightweight test if your account exposes it. Use the relay’s exact identifier, including any documented alias.

§3 Install the CLI and check your shell

Install a Node.js release supported by the current Gemini CLI, then run npm install -g @google/gemini-cli. Verify the installation with gemini --version and inspect available options with gemini --help.

Use a fresh terminal session for the relay test. Existing Google login credentials, project settings, or environment variables can make a successful request appear to use your relay when it actually follows another authentication path.

§4 Set API-key authentication and the native base

For a POSIX-compatible shell, set export GEMINI_API_KEY='YOUR_RELAY_KEY' and export GOOGLE_GEMINI_BASE_URL='YOUR_CONFIRMED_NATIVE_BASE_URL'. Replace both placeholders locally. Never commit the real key to a repository.

Gemini CLI configuration changes across releases. Confirm that your installed version honors GOOGLE_GEMINI_BASE_URL for Gemini API-key requests. If prompted for authentication, choose the Gemini API-key flow rather than Google account login or Vertex AI.

• – Remove conflicting credentials from the test shell.
• – Check project and user settings for authentication overrides.
• – Preserve any path prefix required by the relay.
• – Do not append /v1 merely because another client uses it.

§5 Send one small, noninteractive prompt

Run gemini -m 'YOUR_MODEL_ID' -p 'Reply with exactly: Relay connection verified.'. This keeps the first request small and makes unexpected output easier to spot.

A successful answer proves basic generation, not every CLI capability. Confirm the request in the relay’s usage dashboard or available request logs. That extra check helps establish that your selected model and relay key handled the call.

§6 Verify streaming separately from terminal rendering

Fluxio delivers replies token by token, but a CLI may buffer, reformat, or delay visible output. A completed answer alone does not prove that streaming traversed every layer correctly.

Use the relay’s documented native streaming example to test the transport independently. Gemini-native streaming commonly uses streamGenerateContent with server-sent events. Follow the documented URL construction and authentication requirements rather than copying an OpenAI chat-completions request.

Look for incremental events before completion. If output arrives all at once, inspect reverse-proxy buffering, timeouts, and client behavior before concluding that the model is not streaming.

§7 Test tools, then diagnose failures by layer

After plain text works, open Gemini CLI in a disposable project and request a harmless file inspection. Review approval prompts before permitting changes. Tool-call compatibility is a separate requirement from successful text generation.

• – Authentication errors: Check the key, selected authentication mode, and account access.
• – Not-found errors: Check the native base, path prefix, and exact model identifier.
• – Invalid-request errors: Compare supported fields and tool schemas.
• – Interrupted responses: Inspect streaming compatibility, proxy behavior, and timeout limits.

Keep the working CLI version and configuration recorded, with secrets removed, so subsequent upgrades are easy to compare.

Sign up for Fluxio to try your first relay-backed session.