Gemini API CLI: Google's Open-Source gemini-api Command Gives Any Coding Agent Images, Video, Music and Deep Research

Google has released a beta command line tool, gemini-api, that lets any coding agent with shell access call the Gemini API. The Gemini API CLI is a single Go binary under the Apache-2.0 license. One command can generate an image, a voiceover, music or a video, analyze a PDF, transcribe a recording, or start a background Deep Research run. It is published in the google-gemini/gemini-api-cli repository and introduced on Google AI Studio.

The pitch is in the README's first line: "Gemini models and managed agents for the agent you already use." Google names Codex, Claude Code, Antigravity, OpenClaw and Hermes as hosts. Your agent plans the work, and Gemini supplies models and media. That makes this less a competitor to other coding agents and more a plug-in for them.

TL;DR: what you need to know

What does the Gemini API CLI actually do?

A coding agent building an app often needs something it cannot make by itself: a hero image, a narrated demo, a second opinion on a design, or an answer buried in a PDF. The usual route is to write SDK code, handle base64, and manage uploads. The README says the CLI replaces that with commands an agent can discover and run.

The command groups, as listed in the repository, with their default models:

There are also advanced groups for sandbox environments, stored server-side credentials, webhooks and cron triggers for managed agents. Media commands write the file to disk and print only the path, which is exactly what an agent needs to keep building.

How do you install and try it?

On macOS or Linux, the README gives an install script, and go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest works if you have Go. Windows has a PowerShell installer, and prebuilt archives are on the Releases page. The main branch needs a recent Go toolchain, which Go can download automatically.

export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api generate "Hello from my agent" --dry-run
gemini-api generate "Hello from my agent"
gemini-api image "A friendly robot mascot for a developer tool" --out ./assets/

The first call with --dry-run validates your flags and prints the resolved HTTP request with credentials redacted, without any network call. Remove the flag to run it for real. To keep your key off the shell environment, gemini-api configure --api-key stores it in the OS keychain or a config file, and gemini-api whoami shows which credential is active.

Then tell your agent about it. The README suggests pasting a short block into AGENTS.md, CLAUDE.md or .cursorrules: tell the agent it has gemini-api in the shell, to inspect --help or --usage, preview with --dry-run, and capture file paths and interaction IDs. If you are new to those files, our guides to AGENTS.md support in Claude Code and agent skills explain the pattern.

A sample prompt from the README, which you give to your host agent rather than to the CLI: build a landing page, use Gemini to make a mascot and a welcome voiceover, and launch a managed research agent on competing products.

Why is it built for agents rather than humans?

Stateless calls resuming a multi-turn Gemini API CLI session by interaction ID

Most CLIs are designed to be read by a person. This one is designed to be parsed by a model. Five details from the repository show it:

• Self-describing. --usage prints the full command tree, flags, defaults and config keys as machine-readable KDL. --schema prints the bundled JSON Schema for any command that takes a request body.
• Safe previews. --dry-run shows the exact request before anything is sent or billed.
• Structured output. --output-format json, a compact format called TOON, and an inline --jq filter let an agent extract one field instead of parsing prose.
• Agent mode. --agent-mode (or GEMINI_CLI_AGENT_MODE=1) switches errors to structured JSON envelopes on stderr.
• Stable exit codes. 0 for success, 1 for runtime or API failures, 2 for invalid usage, 3 for authentication failures.

The CLI also holds no local conversation state. Each call is independent, and multi-turn work uses a previous_interaction_id returned by the API. The README says this is by design: your agent supplies the context and decides the next step. That fits the way Gemini's managed agents and Interactions API are built, and the CLI is explicitly "evolving alongside" that API.

Managed agents and Deep Research from the shell

Long-running background research task started from the Gemini API CLI and polled later

The most interesting command for builders is agent run. The README shows starting a Deep Research agent in the background and getting back an interaction ID right away:

INTERACTION_ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')
gemini-api agent status "$INTERACTION_ID" --stream=false --output-format json

Your host agent can keep coding while the research runs, then poll agent status or stream events, or cancel with agent cancel. For large media, files upload --wait returns a files/<id> URI you can reuse across analyze, transcribe, video or agent run. The README puts the inline limit at roughly 14 MB raw, or 20 MB once base64-encoded.

This is a practical way to use a second vendor's strengths inside the tool you already prefer. It pairs naturally with what we covered in Claude Fable 5.1 and Gemini 3.8 Flash coding-agent routing, where different models handle different parts of a job.

How does it compare with Gemini CLI and other vendor CLIs?

The names are confusing, so here is the split:

The README makes the same distinction: this is a utility an agent calls, not an agent harness. It is also not the first vendor CLI of its kind. OpenAI shipped an official command line for its API, which we covered in the official OpenAI CLI guide. The shared idea is that the shell is now the universal tool interface for agents, so every lab wants a first-class command there.

For Google's own docs direction, see also our note on the Gemini API docs preview inside AI Studio.

The models behind the defaults

The README's defaults map to models we have covered. The text default, Gemini 3.8 Flash, is covered in the launch and coding benchmarks post. The speech default is explained in Gemini 3.8 Flash TTS and voice design. Music uses Lyria 3.5, and video uses the model family from Gemini Omni Flash. The image default, gemini-nano-banana-2.1, follows the line in our Nano Banana 2.5 post. Model names and availability can change quickly in a beta, so run gemini-api models for the offline catalog and gemini-api models list --all to see what your key can actually call.

What are the limits and risks?

It is beta. The README warns: "Breaking changes may occur between releases," and recommends pinning a release version in CI. The repository itself is described as experimental. Do not hard-wire it into production pipelines yet.

It costs money. The CLI is free software, but every call goes through your Gemini API key. Video and music generation are typically the pricey ones. Check current pricing in the Gemini API docs and set a budget alert.

Your agent holds the key. Any process your agent can launch can read GEMINI_API_KEY from the environment. Prefer the keychain option, use a key restricted to the project, and keep shell permissions tight. Agents that shell out freely are the same surface that attackers target; for runtime checks on what an agent is about to execute, see AgentBeam, the agent security platform from the explainx.ai team.

Generated assets need review. Image and video models can get facts and details wrong, so check what your agent generates before shipping it.

No pull requests. Google says it is not accepting contributions now, so fixes depend on Google's own release pace. Feedback goes in GitHub Issues.

What people are asking

Should I switch my agent to use it? Only if you need Gemini-specific media or Deep Research. If you already call the Gemini SDK from code you control, the CLI mostly saves boilerplate.

Can I use it in CI? Yes, the README says it targets headless use by agents, scripts and CI jobs. Pin the version and use --no-interactive.

Does it work without an agent? Yes. It is a normal CLI, and gemini-api explore opens an interactive command explorer.

How does it handle secrets in logs? --dry-run redacts credentials in the request preview. Other logging behavior is not detailed in the README, so test it before sharing logs.

What this means for what you build

If you build with coding agents, this is a low-effort way to add generated media and long-running research to a workflow without writing integration code. The cost model is the usual API one: you pay per call. The risk model is the usual agent one: you are handing over a key and a shell. Start with --dry-run, give the agent a narrow task such as "generate the three images this page needs," and review the output.

For the broader picture of where Google's developer stack is heading, see our coverage of Gemini managed agents and agent harness token costs.

Related reading

• Gemini managed agents get files and credentials APIs
• Gemini API docs preview inside Google AI Studio
• Gemini 3.8 Flash launch and coding benchmarks
• Claude Fable 5.1 and Gemini 3.8 Flash agent routing
• The official OpenAI CLI guide
• Gemini Omni Flash video generation
• What are agent skills? Complete guide
• Official: gemini-api-cli on GitHub, Gemini API docs

Details such as default models, flags and version numbers are accurate as of October 22, 2026 and may change as the CLI is in beta.