Gemini API CLI beta: what to lock down before agents use it

Google's Gemini API CLI, gemini-api, is a beta command-line client that lets coding agents, scripts and CI jobs call Gemini from a shell. It generates text and media, analyses files and runs managed agents. Before an agent gets it, decide whose API key it uses, pin the version, and cap what it can spend.

What Google released

The Gemini API CLI was announced as a beta by Google on 27 October 2026 in the Gemini API changelog. Google describes it as a stateless, zero-dependency client for AI coding agents, scripts and CI pipelines. Every command runs on the Interactions API, and the CLI guide calls it an open-source beta that can introduce breaking changes between minor versions.

It is not the same product as Gemini CLI. The guide is explicit: @google/gemini-cli is an interactive coding agent, while gemini-api is an API client that runs inside any coding agent. The guide names Antigravity, Claude Code, Codex and Cursor among the environments it works with. So a team that already uses Claude Code or Codex can give that agent Gemini image, speech or video generation without adding an SDK to the project.

What the CLI can do

The CLI guide groups the commands into four sets:

• Create: generate for text, image for generation and editing, tts for one or two speakers, music through Lyria and video for MP4 clips.
• Understand: analyze for PDFs, images, audio, video, CSV and public YouTube links, and transcribe with Markdown, text, JSON or SRT output.
• Manage agents: agent run, status and cancel, plus commands for custom agents, environments, credentials, webhooks and triggers.
• Setup and files: configure, auth, whoami, files and models.

Three design choices matter for agents. Media commands write the file to disk and print only its path, so binary data stays out of the agent's context window. Errors can come back as structured JSON with --agent-mode. And --dry-run previews a request offline with credentials redacted, which is a cheap way to check what an agent is about to send.

The CLI keeps no hidden local state. Multi-step work is chained through --previous-interaction-id, an uploaded files/<id> reference or a background interaction ID. That makes runs easier to replay from logs, because everything the next step depends on is in the command line.

How teams get access

Install it with the script from the google-gemini/gemini-api-cli repository, with go install, or from prebuilt binaries on GitHub Releases, which the guide recommends for pinning exact versions in Docker and CI. It authenticates with a GEMINI_API_KEY environment variable, or on a workstation with gemini-api configure --api-key, which saves the key to the operating system keychain.

There is no separate CLI price. The guide says usage is billed as normal Gemini API usage and points to the pricing page.

What to lock down before an agent uses it

The CLI is a small tool, but it hands a coding agent a paid API key and the ability to start long-running jobs. These are the controls we would put in place first. They are CodeDTX advice, not Google requirements.

Give agents their own key

Don't let a coding agent inherit a developer's personal key from the shell. Create a key in a separate Google Cloud project for agent and CI use, inject it from your secret store as the guide recommends, and run gemini-api whoami at the start of a job so the logs show which credential was used. If the key leaks through an agent transcript, you rotate one key, not every developer's. Our post on GitHub's AI secret detection model covers catching keys that end up in commits.

Pin the version

Because breaking changes can land between minor versions during the beta, install a fixed release tag in CI images rather than the latest script. Upgrade on purpose, run your scripted calls with --dry-run against the new version, and only then roll it out to agents.

Cap what an agent can start

Image, video, music and managed agent runs are billed at the prices of the models behind them, so check those on the pricing page before allowing them. agent run --background returns immediately while the work carries on, so an agent that loops can queue many jobs before anyone notices. Set budget alerts on the agent's project, have your wrapper pass an explicit --model so an agent can't pick a pricier one, and make your wrapper call agent cancel on any background interaction it started when a run ends. Our guide to controlling AI agent running costs sets out how to budget per task.

Treat uploads as data leaving your network

analyze and files upload send local files to the Gemini API. Local files are sent inline up to a size limit, and larger ones go through the Files API, which deletes them after a fixed period stated in the guide. Decide which folders an agent may point the CLI at, and keep customer data out of them unless your data agreement allows it. If your project's request storage setting is on, review that too, since Google changed the default for new paid projects in the same week.

When not to use it

Skip the CLI where you are building Gemini into an application: the guide points to the Google GenAI SDKs for that. It also has no bidirectional WebSocket support, so real-time voice or video belongs on the Live API through the SDKs. And if your team needs a stable interface for a production pipeline that runs unattended for months, wait for a non-beta release or wrap the CLI behind your own script so a breaking change touches one file.

For teams that already use the Gemini 4 Argon API from code, the CLI is most useful as a shell tool for coding agents and for one-off CI jobs such as transcribing a recording or generating test images, not as a replacement for the SDK.

Frequently asked questions

Is the Gemini API CLI the same as Gemini CLI?

No. Gemini CLI is an interactive coding agent that you work with in a terminal. The Gemini API CLI, gemini-api, is a stateless client that calls the Gemini API from a shell, so other coding agents such as Claude Code, Codex or Cursor can run it as a tool. Google's guide states this difference directly, and the two install and update separately.

Does the Gemini API CLI cost extra?

No separate price is listed. Google's guide says CLI usage is billed as normal Gemini API usage for the models you call, under the standard Gemini API pricing page. The cost depends on which models the agent calls, so media generation and managed agent runs are priced by their own models. Check those prices before allowing them, and watch spend per project, not per command.

Is the Gemini API CLI ready for production CI pipelines?

It can run in CI today, and the guide gives CI advice: pin a release, use JSON output, and rely on typed exit codes. But it is a beta that can break between minor versions. Pin the exact version in your build image, test upgrades before rolling them out, and keep calls behind a small wrapper script so a breaking change is a one-file fix.

How should a coding agent authenticate to the Gemini API CLI?

The CLI reads a GEMINI_API_KEY environment variable, or a key saved to the keychain with the configure command. For agents and CI, we recommend a dedicated key in a separate project, injected from a secret store, never a developer's personal key. Run the whoami command at the start of each job so the logs record which credential the agent actually used.