Gemini API CLI beta: pin the version, scope the key

Google shipped a new way for your coding agent to call Gemini. The Gemini API CLI, installed as gemini-api, is a stateless command-line client built for AI agents with shell access, plus scripts and CI pipelines. Claude Code, Codex, or a GitHub Actions job can now generate text, images, and video, analyze files, and start Gemini managed agents with one shell command. It's a beta, and Google says breaking changes can land between minor versions. So treat it like any beta dependency: pin it, and give it its own key.

What actually happened

The Gemini API changelog lists the release on October 27, 2026: a stateless, zero-dependency command-line client for AI coding agents, scripts, and CI pipelines, running on the Interactions API. The CLI guide and the GitHub repo fill in the details:

• Commands: generate for text, image, tts, music, video, analyze and transcribe for PDFs, images, audio, and video, and agent run|status|cancel for managed agents. The repo lists gemini-3.8-flash as the default text model.
• Stateless: no hidden local state. You chain multi-step work by passing an interaction ID or a files/<id> URI. Media commands write a file and print only its path.
• Auth: the GEMINI_API_KEY environment variable, or gemini-api configure --api-key to store it in the OS keychain. gemini-api whoami shows which credential is in use.
• Exit codes: 0 for success, 1 for API errors, 2 for usage errors, 3 for auth failures. That makes it easy to use in CI.
• License and support: Apache-2.0. Google is not taking pull requests right now. Report bugs through GitHub Issues.
• Limits: inline files cap at 14 MB, and uploaded files are deleted after 48 hours.

It is not the interactive @google/gemini-cli coding agent. It is a tool that other agents call. The docs even include a snippet to paste into AGENTS.md or CLAUDE.md so your agent knows how to use it.

Why it matters for your business

This is the cheapest way yet to add a second model to a workflow you already run. Your Claude-based agent can hand off product-photo generation, a voice clip, or a long-video transcription to Gemini with no SDK code in your repo.

The beta label is the part to plan around. Here's how we would set it up:

• Pin a release. The install script takes GEMINI_VERSION=<release-tag>. Never run @latest in CI.
• Use a separate key. Make a Gemini key just for agents and CI, with its own budget alert. If the agent loops, you'll see it on that key, not on production.
• Save outputs right away. Files uploaded through the API are gone after 48 hours. Copy anything you need to keep into your own storage.

Sources: Gemini API changelog, Gemini API CLI guide, google-gemini/gemini-api-cli on GitHub.