Gemini API CLI Guide: gemini-api Setup, Commands, Agents

Last updated: October 31, 2026

The Gemini API CLI (gemini-api) is an open-source beta command-line client that Google released on October 27, 2026. It lets coding agents, scripts and CI pipelines call Gemini from the shell to generate text, images, speech, music and video, analyze files, and launch managed agents such as Deep Research.

This guide is based on Google’s Gemini API CLI documentation, the Gemini API changelog and the project’s GitHub releases. If you are new to Gemini pricing, start with our answer on whether Gemini is free.

Contents

What is new
Where gemini-api fits
How to install and set up the Gemini API CLI
Gemini API CLI commands
Running managed agents
Power-user features
Limitations
Frequently asked questions

What is new

The changelog lists the Gemini API CLI as a beta release on October 27, 2026, running on the Interactions API. According to the documentation, raw REST calls cause trouble for agents because base64 media fills the context window, interactive prompts block subprocesses and stale training data leads to invented flags. The CLI addresses this with four design choices:

Offline schema lookup. --usage prints the command tree and --schema prints the JSON Schema for --body requests.
Files on disk, paths on stdout. Media and transcription commands save files and print only the path, keeping binary data out of the agent’s context.
Dry runs and structured output. --dry-run previews the HTTP request offline with credentials redacted. -o json, -o toon and --jq give machine-readable output, and --agent-mode returns structured JSON errors.
Stateless by default. No hidden local state. You chain steps with --previous-interaction-id, a files/<id> URI or a background interaction ID.

The tool is moving fast. Version 0.4.5, published on GitHub on October 30, 2026, made gemini-3.5-transcribe the default model for the transcribe command, per the release notes.

Where gemini-api fits

Tool	What it does	When to use it
Gemini API CLI (`gemini-api`)	Calls Gemini models and managed agents from any shell	An agent, script or CI job needs media, file analysis or a background research run with no project dependencies
Google GenAI SDKs	Client libraries for Python, TypeScript, JavaScript, Go, Java and C#	You are building Gemini features into an application or a real-time Live API session
Gemini Docs MCP and skills	Live documentation search and current SDK rules for coding agents	Your coding agent is writing app code that imports a GenAI SDK
`@google/gemini-cli`	An interactive coding agent	You want a terminal coding assistant rather than a stateless API client

Google says gemini-api works with Antigravity, Claude Code, Codex, Cursor and any shell environment. That makes it a useful add-on to the tools in our Claude Code guide and Codex CLI guide.

How to install and set up the Gemini API CLI

Install the binary. On macOS or Linux, run curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash. On Windows, use the install.ps1 PowerShell script. With Go, run go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest.
Pin a version for automation. Set GEMINI_VERSION to a release tag in the install command, or use the prebuilt archives on GitHub. Google warns that breaking changes can occur between minor versions.
Add your API key. Create a key in Google AI Studio and run export GEMINI_API_KEY="YOUR_API_KEY". On a workstation, gemini-api configure --api-key saves it to the OS keychain, or to ~/.config/gemini-api/config.yaml with --no-keyring.
Verify. Run gemini-api whoami, then gemini-api generate "Confirm CLI setup in one sentence." --dry-run.
Tell your agent about it. Add a short note to AGENTS.md, CLAUDE.md or .cursorrules telling it to check --usage and --schema first and preview calls with --dry-run -o json.

Gemini API CLI commands

Command	What it does
`image`	Generates or edits images and writes a JPEG; sizes 512, 1K, 2K or 4K
`tts`	Writes 24 kHz mono WAV speech with one or two speakers; default voice Kore
`music`	Generates music tracks or loops with Lyria
`video`	Generates or edits MP4 clips; `--async` returns an ID right away
`generate`	Streams text to stdout; `--stdin` pipes input in
`analyze`	Answers questions about PDFs, images, audio, video, CSV, text or public YouTube URLs
`transcribe`	Writes speaker-labeled, timestamped transcripts as md, text, json or srt
`agent`	Runs, checks, cancels and defines managed agents
`files`	Uploads, lists, inspects and deletes Files API uploads
`models`	Lists available models

Each command picks a default model for its task. Override it with --model or -m, and run gemini-api models to see the options. A practical pattern is to capture output paths in shell variables, for example HERO_PATH=$(gemini-api image "..." --out ./public/images/hero.jpg), then pass -i "$HERO_PATH" to edit the same image.

Running managed agents

The agent command delegates long jobs to Gemini managed agents. To start a Deep Research job without holding a stream open, run gemini-api agent run "Compare open-source vector index benchmarks" --agent deep-research-preview-04-2026 --background --stream=false --jq '.id'. Then poll with gemini-api agent status <id> -o json, or stop it with gemini-api agent cancel <id>.

The same command can launch the Antigravity agent in a remote sandbox and manage custom agents with create, list, get and delete. Separate commands configure environments, credentials, webhooks and scheduled triggers. For the model behind Antigravity, see our Gemini 4 Argon guide.

Power-user features

Raw request bodies. --body accepts an Interactions API JSON payload, inline or as @file.json, for response_format schemas, function-calling tools, generation_config or "store": false. If a flag and the body set the same key, the command fails with exit code 2.
Typed exit codes. 0 is success, 1 is a runtime or API error such as a rate limit, 2 is a usage or validation error, and 3 is an authentication failure.
Non-interactive by default. Commands never prompt unless you pass --interactive, so they will not hang an agent subprocess.
Large files. Run gemini-api files upload ./file.mp4 --wait once, then reuse the returned files/<id> URI across analyze and transcribe calls.

If you build your own agents in code rather than calling Gemini from the shell, compare this approach with the Cursor Agent SDK or, for open models on Hugging Face, the Hugging Face hf CLI.

Limitations

It is a beta release, and breaking changes can occur between minor versions.
Streaming commands (generate and agent run) need --stream=false when combined with -o json or --jq.
Inline file inputs are capped at 14 MB of raw data, or 20 MB including base64 encoding. Uploaded files are deleted after 48 hours.
It supports HTTP requests, SSE streaming and async polling, but not bidirectional WebSockets. For real-time voice and video, Google points to the Live API and the GenAI SDKs.

Frequently asked questions

What is the Gemini API CLI?

The Gemini API CLI, run as gemini-api, is a stateless, zero-dependency command-line client for the Gemini API. Google released it in beta on October 27, 2026. It lets coding agents, scripts and CI jobs generate text and media, analyze files and run Gemini managed agents from the shell.

Is gemini-api the same as Gemini CLI?

No. Google says gemini-api is a stateless API client, not an interactive coding agent like @google/gemini-cli. You can run gemini-api inside any coding agent, including Gemini CLI, Claude Code, Codex or Cursor.

How do I install the Gemini API CLI?

On macOS or Linux, run Google’s install script from the google-gemini/gemini-api-cli GitHub repository. Windows users can use the PowerShell script, and Go users can run go install. Then set GEMINI_API_KEY or save the key with gemini-api configure.

Is the Gemini API CLI free?

The CLI is open-source software under the Apache 2.0 license on GitHub. It calls the Gemini API with your own API key, so the requests it makes count toward that key’s Gemini API usage and pricing.

What does exit code 3 mean in gemini-api?

Exit code 3 means an authentication or authorization failure, such as a missing or invalid API key. Code 0 is success, 1 is a runtime or API error such as a rate limit, and 2 is a usage or validation error.

Can gemini-api handle large files?

Inline files are capped at 14 MB of raw data, or 20 MB including base64 encoding. For larger files, run gemini-api files upload –wait and pass the returned files/ID URI. The Files API deletes uploads after 48 hours.

Sources

Image: Google Gemini logo by Google LLC, public domain (trademarked), via Wikimedia Commons. Gemini is a trademark of Google LLC. FreeAnswers is not affiliated with or endorsed by Google.

Gemini API CLI: Power-User Guide to gemini-api Setup, Commands and Agents