Gemini CLI

Google's terminal agent, on plugboard's Gemini API.

Connect

export GEMINI_API_KEY="$PLUGBOARD_KEY"
export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:4010"   # the origin, without /v1

and in ~/.gemini/settings.json:

{ "security": { "auth": { "selectedType": "gemini-api-key" } } }

Then gemini -m fast. For headless runs add --skip-trust (or set GEMINI_CLI_TRUST_WORKSPACE=true); otherwise the CLI exits with code 55 before calling the API.

Headless output

gemini -p "<prompt>" -m <model> --output-format json:

// gemini -p "<prompt>" -m <model> --output-format json, with GEMINI_API_KEY and GOOGLE_GEMINI_BASE_URL set (cli.ts).
const stdout = await gemini(home, model, "Reply with exactly: pong", "json")

--output-format stream-json prints one event per line; text arrives as assistant deltas and the result event has the stats:

// gemini -p "<prompt>" -m <model> --output-format stream-json. One JSON event per line.
const stdout = await gemini(home, model, "Reply with exactly: pong", "stream-json")

Token counts

A prompt that refers to an image or a PDF with @name makes the CLI call :countTokens before it sends the prompt, to check that the request fits the model's context window. Plugboard answers with an estimate. A prompt with text only calls nothing: the CLI estimates it itself.

// An @file reference to an image sends the file with the prompt. The CLI then calls POST /v1beta/models/<model>:countTokens
// before :streamGenerateContent, with the same GEMINI_API_KEY and GOOGLE_GEMINI_BASE_URL.
await gemini(home, model, "Reply with exactly: pong @red32.png", "json")

What works

Chat, streaming, token counts and the CLI's own tools, which it runs itself.

Limits

• A # in a model name must be sent as %23 (-m openai/gpt-5.6-luna%23low). Aliases avoid it.