Gemini API CLI: What Google's README Says About Giving Your Coding Agent Gemini and Managed Agents

Google's gemini-api is an experimental command-line tool, published as Apache 2.0 open source, that lets any agent with shell access call Gemini models, generate media and start Gemini managed agents. Its README names Codex, Claude Code, Antigravity, OpenClaw and Hermes as example hosts. The README also says it is in beta, that breaking changes may occur between releases, and that you should pin a release version in CI. The idea is simple: your agent plans, and Gemini is one more tool it can run.

I read the repository page and README only. I did not install the CLI, call the API or read the release notes, the API docs or the source. Everything below is what the README says.

What it is

The README describes gemini-api as a stateless CLI for the Gemini API, built for headless use by coding agents and assistant tools, and equally usable from shell scripts and CI. It is a single Go binary for macOS, Linux and Windows.

On the repository page I saw: Apache 2.0, created April 29, 2026, about 318 stars, 19 open issues, and languages including Go, Python, TypeScript and shell. The README says Google is not accepting pull requests at this time and points feedback to GitHub Issues.

What the commands cover

The README groups commands like this:

• Create: generate (text and multimodal), image, tts, music, video. The README lists a default model for each, for example gemini-3.8-flash for generate and gemini-nano-banana-2.1 for image.
• Understand: analyze (PDFs, images, audio, video, CSV or text files, YouTube URLs) and transcribe (to Markdown, text, JSON or SRT).
• Manage: agent (run, status, cancel, and create or manage agent definitions), files (upload, list, get, delete, with 48-hour retention), models, configure, auth and whoami.
• Advanced: environments (sandbox environments and their files), credentials (stored server-side credentials for managed agents), webhooks and triggers (cron triggers for managed agents).

Model names and defaults are the README's. I did not check them against the live API.

Built for agents to read

Three design choices stand out because they are aimed at an agent, not a person.

• --usage prints the full command tree, flags, defaults, environment variables and config keys in a machine-readable format, so an agent can discover the tool from the binary itself.
• --schema prints the JSON Schema for any command that takes a request body, and --body lets the agent send a full request.
• --dry-run validates inputs and prints the resolved HTTP request with credentials redacted. The README says it makes no network call and does not read the OS keychain.

There is also --agent-mode, which per the README gives structured JSON error envelopes on stderr and compact TOON output on stdout. Exit codes separate success (0), runtime or API failures (1), usage errors (2) and authentication failures (3).

The --dry-run flag is the most useful one for anyone letting an agent run this unattended, because you can see what would be sent first.

The managed agent workflow

The README shows launching a Gemini managed agent in the background, using Deep Research as the example:

1. Run gemini-api agent run with an agent name, --background and --stream=false. The CLI returns an interaction ID right away.

2. Check progress or fetch the result with gemini-api agent status INTERACTION_ID. You can also stream progress or cancel the run.

The README also describes stateful multi-turn work: you pass a previous_interaction_id in the request body to continue a conversation. It says the CLI keeps no local conversation state. Server-side interactions and uploaded files handle their own retention on the API, and your workflow keeps the IDs it wants to reuse.

That means your agent has to store the interaction IDs itself. If it loses one, the README gives no way I could see to recover it from the CLI side. I did not check the API docs for a list endpoint.

Keys and secrets

The README says to set a GEMINI_API_KEY environment variable, or to store it with gemini-api configure in the OS keychain (macOS Keychain, Linux Secret Service or Windows Credential Manager) or in ~/.config/gemini-api/config.yaml. gemini-api whoami shows the active configuration and credential source.

Two points matter for agent use. The API key sits in the environment of whatever shell the agent controls, so anything that agent can run can read it. The README's credentials command manages server-side credentials for managed agents, but the README does not explain what those credentials can reach. I did not read further.

The README's install section also offers a curl ... | bash installer, a PowerShell iwr ... | iex installer, go install, and prebuilt release binaries. If you do not want to pipe a script into a shell, the go install and release-binary routes are in the same list.

What I would check

These are my untested suggestions, not results.

1. Pin a version. The README says breaking changes may occur. Pin a release, and read the release notes before you move.

2. Dry-run first. Have your agent run every new command with --dry-run and read the request before it makes a real call.

3. Key scope. Use a separate API key for agent use, so you can revoke it without touching your own.

4. Background cost. Before you let an agent start managed agents in the background, check Gemini API pricing for those agents. The README gives no prices.

5. Retention. Check how long server-side interactions are kept, and whether "store": false, which the README shows in a request body, does what you need.

6. Lost IDs. Test what happens when the agent drops an interaction ID in the middle of a task.

What I would not conclude

• That it is production-ready. The README calls it experimental and beta.
• That agent workflows are cheap. The README says nothing about cost, and I did not look.
• That the example models and agent names are current. They are from the README on the day I read it.
• That an agent using this CLI is sandboxed. The CLI is a client. Where it runs is up to you.
• That it works as described. I did not run it.

Frequently asked questions

What is the Gemini API CLI?

An experimental, Apache 2.0 command-line client for the Gemini API, built so shell-capable agents can call Gemini models, media generation and managed agents.

Which agents can use it?

The README names Codex, Claude Code, Antigravity, OpenClaw and Hermes, and says any agent with shell access can.

How do I install it?

The README lists a shell installer, a PowerShell installer, go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest, and prebuilt binaries from GitHub Releases.

How do I authenticate?

Set GEMINI_API_KEY, or run gemini-api configure to store the key in the OS keychain or a config file. gemini-api whoami shows what is active.

How do I run a long task without keeping a stream open?

Use gemini-api agent run with --background --stream=false. It returns an interaction ID. Fetch the result later with gemini-api agent status.

Can I see a request before it is sent?

Yes. --dry-run validates the input and prints the resolved HTTP request with credentials redacted, without a network call.

Will it change?

The README says it is in beta and breaking changes may occur between releases, and recommends pinning a specific release.

Sources

All pages read on October 27, 2026.

• google-gemini/gemini-api-cli repository and README: description, command overview, agent interface flags, workflows, status, license.

Not read: the GitHub Releases notes, the Gemini API and Interactions API documentation, the CLI source code, and any pricing pages.