CommandInstalls cleanly
Make images and transcripts with Gemini
Gemini API CLI
Google's gemini-api command lets Claude Code, Codex or any shell agent make images, voiceovers and transcripts, read PDFs and run Gemini research agents.
- Works with
- Claude Code, Codex CLI, Any agent
- Good for
- Graphic designers, Daily work and research
What it does
gemini-api is one small program from Google that gives any assistant with a terminal (Claude Code, Codex, Antigravity and others) access to Gemini models. Your assistant plans the work and calls gemini-api when it needs something Gemini is good at:
image: make or edit images and save them in your project.ttsandmusic: make voiceovers and background music.video: make or edit video clips.analyze: answer questions about PDFs, images, audio, video, CSV or text files, or public YouTube links.transcribe: turn a recording into Markdown, plain text, JSON or SRT captions.agent run: start a Gemini managed agent, such as Deep Research, in the background and fetch the result later.
It is not a chat app and not a coding assistant. Each command runs once and prints a file path or an answer, which the assistant then uses. Google calls it beta.
If you do not want to pipe a script into bash, download the archive for your computer from the GitHub Releases page, compare it with the release's checksums.txt, unpack it and put gemini-api in a folder on your PATH. Google's docs also show how to install one exact version: add GEMINI_VERSION=<release-tag> before bash in the install line.
Example prompts
- "Use gemini-api to make a friendly robot mascot for this landing page and save it in ./assets/."
- "Transcribe interview.mp4 with gemini-api into SRT captions."
- "Use gemini-api analyze on product-brief.pdf and tell me what we should build first."
- "Start a Gemini deep research run on battery recycling with gemini-api and check on it in ten minutes."
How to install
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bashHow to use it
Set GEMINI_API_KEY, add the README's short instruction block to CLAUDE.md or AGENTS.md, then ask: Use gemini-api to make a mascot image for this site and save it in ./assets/.
Check it works
In a terminal, run gemini-api generate "Hello from my agent" --dry-run. It checks your setup and shows the request without a network call. Then run it again without --dry-run to call the API. gemini-api whoami shows your active settings and where your key comes from.
Common problems
- Authentication error (exit code 3) — create a key in Google AI Studio and
export GEMINI_API_KEY="...", or save it withgemini-api configure --api-key— https://ai.google.dev/gemini-api/docs/api-key gemini-api: command not found— the binary is not on your PATH; the install script puts it in ~/.local/bin when /usr/local/bin is not writable, so add that folder to PATH or move the binary — https://github.com/google-gemini/gemini-api-cli- Big video or audio files fail — files over about 14 MB should be uploaded once with
gemini-api files upload --wait, then passed by theirfiles/<id>URI — https://github.com/google-gemini/gemini-api-cli - The assistant waits forever on a research run — start it with
--background --stream=falseso it returns an ID at once, and check it withgemini-api agent status— https://github.com/google-gemini/gemini-api-cli
Other assistants
- Codex and other agents: the same program works for any agent with shell access; add the README's instruction block to AGENTS.md (README).
- Windows (PowerShell):
iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex(README). This script also does not check checksums. - With Go:
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest(README). - Gemini CLI: no primary source gives a Gemini CLI setup line. The Gemini CLI README's "Which Google CLI do you need?" table lists
gemini-apifor agents such asagy, Claude Code and Codex, scripts and CI, and lists Gemini CLI itself for organizations with Gemini Code Assist Standard or Enterprise.
What to watch out for
- Beta: the README says breaking changes may occur between releases and recommends pinning to a specific release version in CI and automated workflows (README, Status section)
- Every real call uses your Gemini API key. New keys start on the Free Tier, which gives access to certain models up to their free rate limits; some models are not available on the Free Tier and paid use is billed per token (ai.google.dev billing and pricing pages)
- On the Free Tier, Google's pricing page marks content as used to improve Google's products; on the Paid Tier it is not (ai.google.dev/gemini-api/docs/pricing)
- Files and prompts you send go to Google's API. Uploaded files are deleted after 48 hours. Interactions are stored by default, for 55 days on the Paid Tier and 1 day on the Free Tier, unless you send "store": false in a --body request (README, Files API and Interactions API docs)
- The install line downloads a script from GitHub and runs it with bash. The script (from the main branch) installs the latest release and does not check the checksums.txt file that each release ships; read scripts/install.sh first, or download a release archive and check it yourself (scripts/install.sh, GitHub Releases)
- The README gives you a text block to paste into CLAUDE.md or AGENTS.md. It tells the agent to inspect --help or --usage first and to 'Preview API calls with --dry-run'; read it before you add it (README, Quick start step 2)
Licence and author
- Licence
- Apache-2.0
- Author
- Source code
- github.com/google-gemini/gemini-api-cli
How we tested it
We installed it on an empty test computer on 28 Oct 2026. Installed and started in a clean test system. Not yet used in a real AI session.
No API key, so no calls to Google were made. Not yet used on real work.
Technical details of the test
- Date
- 28 Oct 2026
- Method
- Manual sandbox run on 2026-10-28 in the intake's clean container with no account: read scripts/install.sh, ran it as a normal user (it installed v0.4.4 to ~/.local/bin because /usr/local/bin was not writable), then ran "gemini-api --version" and "gemini-api --help".
Checked again on 28 Oct 2026
Alternatives
- Nano Banana — image commands inside Gemini CLI instead of a separate program
- HyperFrames — make videos from HTML instead of generating them with a model
- imagegen-skills — skills that guide image generation for mockups and brand boards
FAQ
- Q: Does it cost money? A: The CLI is free (Apache-2.0). Calls use your Gemini API key. New accounts start on Google's Free Tier, which covers certain models up to their rate limits; other use is billed under Google's Gemini API pricing.
- Q: Is this the same as Gemini CLI? A: No. Google's docs say
gemini-api"is a stateless API client, not an interactive coding agent like @google/gemini-cli". It is a tool your existing assistant calls. - Q: Can I try it without spending anything? A: Yes.
--dry-runchecks the request without calling the API or reading your keychain (README). After that, a Free Tier key lets you make real calls to some models at no charge, but on the Free Tier Google may use your content to improve its products.
Sources
- github.com/google-gemini/gemini-api-cli
- github.com/google-gemini/gemini-api-cli/releases
- ai.google.dev/gemini-api/docs/cli
- ai.google.dev/gemini-api/docs/api-key
- ai.google.dev/gemini-api/docs/pricing
- ai.google.dev/gemini-api/docs/billing
- ai.google.dev/gemini-api/docs/files
- ai.google.dev/gemini-api/docs/interactions-overview
- github.com/google-gemini/gemini-cli