Use Gemini CLI with Models Hub: One-Click and Manual Setup

Configure Gemini CLI for Models Hub with one Models Hub CLI command, or edit settings.json and .env manually to reach Google Gemini models, with verification and error troubleshooting.

Gemini CLI is Google's official terminal AI coding assistant. Switch its auth method to an API key and point it at Models Hub, and every chat and code edit inside gemini uses your Models Hub balance for the model you choose. This page covers the connection only, not how to use Gemini CLI itself.

Three things you need

A Models Hub API key, the base URL https://modelsok.com, and a model name. The one-command setup below takes about 30 seconds.

Prerequisites

Gemini CLI installed. If not, follow the official install instructions and run npm install -g @google/gemini-cli; gemini --version should print a version afterward.
A Models Hub API key, created on the Tokens page. The token's group must have access to the models you plan to use.

Recommended models

Gemini CLI speaks Gemini's native protocol, so use a Gemini-family model from Models Hub:

Use case	Model	Pricing	Live status
First choice for everyday coding	`gemini-3.1-pro-preview`	Price	Availability and latency
Faster and cheaper, good for small edits and batch tasks	`gemini-3.5-flash`	Price	Availability and latency
Stable release, when you want predictable behaviour	`gemini-3.1-pro`	Price	Availability and latency

Model names are authoritative on the pricing page. If you want to try a Claude or GPT model from inside Gemini CLI, swap GEMINI_MODEL for the name on the pricing page — whether the gateway translates the protocol for you is something to verify yourself.

Option 1: one-command setup (recommended)

The Models Hub CLI writes your API key, base URL and default model into ~/.gemini/settings.json and ~/.gemini/.env.

macOS / Linux:

curl -fsSL https://modelsok.com/cli/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://modelsok.com/cli/install.ps1 | iex"

After installing, run models, choose Gemini CLI from the interactive menu, and paste your API key and pick a model when prompted. Or run it non-interactively: models configure --target gemini --api-key <your-api-key> --yes. The default model is gemini-3.1-pro-preview; pick a different one during setup, or pass --gemini-model. Full reference: CLI one-command setup.

Option 2: manual setup

Create or edit ~/.gemini/settings.json to enable API key auth:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "model": {
    "name": "gemini-3.1-pro-preview"
  }
}

Then create or edit ~/.gemini/.env:

GEMINI_API_KEY=your-models-hub-api-key
GEMINI_MODEL=gemini-3.1-pro-preview
GOOGLE_GEMINI_BASE_URL=https://modelsok.com

Variable / field	Purpose
`security.auth.selectedType`	Auth method; `gemini-api-key` means using an API key instead of signing in with a Google account
`GEMINI_API_KEY`	Your Models Hub API key
`GEMINI_MODEL`	The default model name
`GOOGLE_GEMINI_BASE_URL`	The base URL — do not append `/v1`

Verify against your current version

GOOGLE_GEMINI_BASE_URL started as a community workaround for pointing Gemini CLI at a custom endpoint; the official docs don't cover "API key + custom base URL" as a combination, and behavior can differ between versions. Confirm it actually works with the verification steps below.

Verify

Reopen your terminal, run gemini in any project, and ask something like "describe this directory in one sentence". A normal reply means you're connected. Then open Usage logs in the Models Hub console; a request under your configured model name appears within seconds.

Common errors

Symptom	Cause	Fix
`401` / authentication failure	Wrong key, stray whitespace, or a disabled token	Re-copy from the Tokens page; if you used one-click setup, rerun `models`
Changes don't take effect	Gemini CLI isn't reading the file you edited, or the terminal wasn't reopened	Confirm the paths `~/.gemini/settings.json` and `~/.gemini/.env`, then reopen the terminal
`model not found` / no available channel	Misspelled model name, or the token's group can't access it	Check the name on the pricing page
Requests still hit Google's official endpoint	`selectedType` isn't `gemini-api-key`, or you're signed in via OAuth	Check `security.auth.selectedType` in `settings.json`
`429`	Rate limited, usually too much concurrency	Retry shortly; contact support for a higher limit if it persists

FAQ

How is it billed? Per input and output token actually consumed, at the price on each model's pricing page; every request is itemized in usage logs.

How is this different from using my Google account directly? Once configured, every Gemini CLI request goes through Models Hub instead of your Google account's free quota or subscription, and you don't need a Google AI Studio account.

How do I switch models? Rerun models configure --target gemini --api-key <your-api-key> --gemini-model <model-id> --yes, or edit GEMINI_MODEL in .env and model.name in settings.json by hand.

CLI one-command setup: the same tool also configures Claude Code, Codex and OpenClaw
Model pricing and model status
Claude Code setup, Codex CLI setup

Use Gemini CLI with Models Hub: One-Click and Manual Setup

On this page