Gemini API CLI: Google's Free Command-Line Tool That Lets Any AI Agent Use Gemini — Complete Install and Command Guide

Gemini API CLI at a glance

What it is, and who it is for

A coding agent building an app often needs something that is not code: a hero image, a voiceover, a second opinion on a design, or an answer buried inside a PDF. Until now, giving an agent those abilities meant wiring up API calls by hand. The Gemini API CLI is Google's answer: one binary that puts the whole Gemini API behind ordinary shell commands, so an agent (or a script, or a CI job) can do all of it without custom integration code.

The design is deliberately agent-first. Every command is self-describing: --help and --usage print the command tree as machine-readable data, --schema prints the JSON Schema for any request body, and output can be streamed text, structured JSON, compact TOON, or a single field filtered with --jq. Media commands write files to disk and print only the file path, so the agent gets a path it can use in the next step. Long work is delegated: start a managed agent in the background, keep the interaction ID, and poll for the result later.

If you are a developer, it is also useful without any agent at all — a faster way to call Gemini from a terminal than opening a browser, with the same commands in scripts and CI.

Installation

Pick one method. The installer script is the fastest; the Go install is best if you already use Go; prebuilt binaries suit locked-down machines.

macOS and Linux (installer script):

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

Go install (any platform with Go):

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

To build the current development version, use @main instead of @latest — current main requires Go 1.26.10 or later (Go's automatic toolchain selection downloads the required version if needed).

Prebuilt binaries: download the archive for your platform from GitHub Releases and place gemini-api on your PATH.

Configure your API key and run your first command

Create an API key in Google AI Studio, then make it available to the CLI. The simplest way is an environment variable:

export GEMINI_API_KEY="YOUR_API_KEY"

To persist the key instead, store it in your OS keychain (macOS Keychain, Linux Secret Service, or Windows Credential Manager) or in ~/.config/gemini-api/config.yaml:

gemini-api configure --api-key "YOUR_API_KEY"

Or open the interactive form with gemini-api configure --interactive. Check your active configuration and credential source any time with gemini-api whoami.

Verify the setup without spending anything or touching the network — --dry-run validates the call and prints the resolved request with credentials redacted:

gemini-api generate "Hello from my agent" --dry-run

gemini-api generate "Hello from my agent"

Every command, at a glance

gemini-api image "A friendly robot mascot for a developer tool" --out ./assets/

Workflows that show what it is for

1. Generate and edit creative assets. A coding agent building a landing page generates the mascot, the voiceover, the music and the video while it builds — then keeps the file paths and carries on:

# Generate an image and capture the written file path
MASCOT_PATH=$(gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg)

# Edit an existing image
gemini-api image "Add a winter scarf and snowy background" -i "$MASCOT_PATH" --out ./assets/mascot-winter.jpg

# Single-speaker or multi-speaker voiceovers
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api tts "Alice: Welcome to the demo! Bob: Let's dive right in." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./assets/dialogue.wav

# Background music and video
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/
gemini-api video "A slow camera move through a sunlit workshop" --out ./assets/

Media commands write files locally and print only the written file path to stdout. When --out points to a directory (or is omitted), the CLI names the file automatically using the extension that matches the returned MIME type (.jpg, .wav, .mp3, .mp4).

2. Analyse documents and transcribe recordings. Turn a PDF, a pair of screenshots or a recording into answers and deliverables:

# Analyse a PDF or compare multiple images
gemini-api analyze --input product-brief.pdf "What should we build first, and why?"
gemini-api analyze --input before.png --input after.png "Summarize the visual design changes"

# Transcribe audio or video (formats: md, text, json, srt)
gemini-api transcribe --input interview.mp4 --format srt --out interview.srt

For larger media files (over roughly 14 MB raw / 20 MB base64-encoded), upload once with files upload --wait and reuse the returned files/<id> URI across analyze, transcribe, generate, image, video or agent run:

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze --input "$FILE_URI" "List the key action items with timestamps"

3. Launch and poll a background managed agent. Delegate multi-step research to a Gemini managed agent such as Deep Research. Pass --background so the CLI returns the interaction ID immediately instead of holding a stream open:

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

echo "Started interaction: $INTERACTION_ID"

Then check progress or fetch the finished output with that ID — stream live progress, or cancel the run:

gemini-api agent status "$INTERACTION_ID" --stream=false --output-format json
gemini-api agent status "$INTERACTION_ID" --stream
gemini-api agent cancel "$INTERACTION_ID"

4. Choose the right model. Use --model (-m) on generation and analysis commands, and the models commands to see what your key can use:

# View the curated offline model catalog grouped by capability
gemini-api models

# Query all live models available to your API key
gemini-api models list --all
gemini-api models get gemini-3.8-flash

# Run a prompt with a specific model
gemini-api generate "Review this approach: cache immutable responses by content hash" --model gemini-3.8-flash

Go deeper: custom request bodies

Short flags cover common tasks; --body gives full access to the underlying Interactions API request schema while keeping the CLI's file output and error handling. First inspect the schema, then build the request:

gemini-api image --schema > image-schema.json

cat > hero-image.json <<'JSON'
{
  "model": "gemini-nano-banana-2.1",
  "input": "A friendly robot mascot in a sunlit workshop, composed on the right with uncluttered space on the left for a landing page headline. No text or watermark.",
  "response_format": {
    "type": "image",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  },
  "store": false,
  "stream": false
}
JSON

Preview the exact HTTP payload with --dry-run, then execute it. With --output-format json the CLI writes the image to disk and returns structured artifact metadata:

gemini-api image --body @hero-image.json --out ./assets/hero.jpg --dry-run --output-format json
gemini-api image --body @hero-image.json --out ./assets/hero.jpg --output-format json

{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/hero.jpg",
  "size_bytes": 2914159,
  "status": "completed"
}

The same --schema to --body workflow applies to agent run and other commands — for system_instruction, tools, structured JSON response_format.schema, or stateful multi-turn continuations via previous_interaction_id:

# Turn 1: Run a non-streaming interaction and capture its ID
TURN1_ID=$(gemini-api generate "Propose 3 database indexing strategies for a time-series log table." \
  --stream=false --jq '.id')

# Turn 2: Continue the conversation using previous_interaction_id
gemini-api agent run "Compare strategy #2 and #3 for write-heavy workloads." \
  --body "{\"previous_interaction_id\": \"$TURN1_ID\"}" \
  --stream=false

Give your agent the instructions

The README ships a ready-made block for your agent's instructions file (AGENTS.md, CLAUDE.md, .cursorrules, or tool configuration):

You have access to gemini-api through the shell.
Use it to call Gemini models, generate or edit media, analyze files, or launch managed agents.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run (or --dry-run --output-format json).
3. For discrete JSON output or --jq filtering on streaming commands (generate, agent run, agent status --stream), pass --stream=false --output-format json (--background on agent run returns a single interaction without streaming unless --stream is passed).
4. Capture returned file paths (from media commands) and interaction IDs (from agent/model runs) to continue multi-step tasks.

Honest limitations

• Beta, not stable. Commands, flags and default models can change. Pin a release version; do not track main in production scripts.
• Video uses the older model. The video command's default is gemini-omni-1.1-flash in the README — not the newer Omni 1.2 Flash. If you need 1.2's 15-second clips, check the current README or pass the model explicitly with -m.
• Files expire. Uploaded files are retained for 48 hours via the Files API — download or reuse them inside that window.
• It costs API usage, not just the download. The binary is free, but every call consumes your Gemini API quota/billing. Check AI Studio pricing and free-tier limits before heavy use, and use --dry-run to validate calls for free.
• No PRs accepted. Google is not accepting open-source contributions (pull requests) for this repo at this time — feedback goes through GitHub Issues.
• Needs an API key. This is not the free Gemini app: you need a Google AI Studio API key, and the key's limits apply. Without one, nothing runs.

Security and privacy

• Your API key is the credential. Keep it out of code, logs and screenshots. Prefer the OS keychain via gemini-api configure over a bare environment variable in shared shells, and never commit a key to a repo.
• Dry-run before real calls. --dry-run prints the resolved HTTP request with credentials redacted and makes no network call — use it when testing new commands or bodies.
• Your prompts and files go to Google. Text, images, audio and video references are processed by the Gemini API under Google's terms — do not send unreleased products, private people, or client assets you have no right to share.
• Stateless by design. The CLI keeps no local conversation state; server-side interactions and uploaded files manage their own retention on the API side, and your workflow keeps only the IDs it reuses.

Real use cases

• Agent-built landing pages: the agent generates the mascot, hero image, voiceover and background music itself while building the page, instead of waiting for a designer.
• Meeting notes in one command: transcribe a recorded call to SRT captions and a Markdown summary, then analyse the transcript for action items with timestamps.
• Research delegation: launch a Deep Research managed agent in the background, keep the interaction ID, and pick up the cited findings when the run finishes.
• Document Q&A in scripts: ask a question across a product brief PDF, compare before/after screenshots, or pull figures from a CSV — inside a shell script or CI job.
• Content pipelines: generate a batch of images, voiceovers and transcripts from a single script, with JSON output and --jq filtering feeding the next step.

Frequently asked questions

What is the Gemini API CLI?

A free, open-source command-line tool from Google (gemini-api) that puts the Gemini API behind shell commands — text, image, audio, music and video generation, document analysis, transcription, and background managed agents. One Go binary, macOS/Linux/Windows, Apache 2.0.

How do I install gemini-api?

On macOS/Linux: curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash. On Windows PowerShell: the matching install.ps1 script. Or go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest, or a prebuilt binary from GitHub Releases.

Do I need an API key?

Yes. Create one in Google AI Studio and set GEMINI_API_KEY, or run gemini-api configure --api-key "YOUR_API_KEY" to store it in your OS keychain. Check the setup with gemini-api whoami.

Is the Gemini API CLI free?

The binary is free under Apache 2.0. API calls are billed under Gemini API pricing — check AI Studio for current rates and free-tier limits. Use --dry-run to validate calls without spending anything.

Can my AI coding agent use it?

That is its main purpose. Add the README's instruction block to your agent's AGENTS.md or CLAUDE.md, put gemini-api on PATH with an API key, and the agent can inspect --help, preview with --dry-run, and call commands itself.

What is the difference between gemini-api and Gemini CLI?

This tool (gemini-api, repo google-gemini/gemini-api-cli) is a thin, scriptable bridge to the Gemini API, built for agents and automation. It is not the interactive Gemini CLI assistant — it runs one stateless command at a time and returns file paths, JSON or interaction IDs.

Is it stable enough for production scripts?

Not yet — it is in beta and Google warns breaking changes may occur between releases. Pin a specific release version in CI and automated workflows, and expect commands or defaults to evolve.

Sources

• GitHub — google-gemini/gemini-api-cli — README, install steps, command table, workflows, status (checked 6 November 2026; 451 stars, 10 releases, Apache 2.0)
• Google AI Studio — API keys, Gemini API docs and pricing

Related reading: Gemini Omni 1.2 Flash: Google's 15-Second AI Video Model · TurboFieldfare: run Gemma 4 26B on an 8GB Mac — complete install guide · Teardown: the free Claude Code skill that turns any machine into a 3D simulator · Kimi K3.1 Pro: open weights, 2.8 trillion parameters