gemini-api-cli

The gemini-api CLI exposes every Gemini API resource as a shell subcommand. Compared to curl: media and transcription commands decode output to disk and print only the file path, -i attaches local files or files/<id> URIs, --jq extracts fields in-process (raw strings by default, no external jq), --dry-run previews redacted HTTP requests offline, and list endpoints auto-paginate with --all (cap pages with --max-pages N; --page-size sets server page size).

CLI vs SDK

CLI for shell work, SDK for application code. Use gemini-api from terminals, scripts, and CI jobs to generate media files, analyze local PDFs or recordings, run Deep Research, and manage agent sandboxes (gemini-api is a stateless Gemini API client, distinct from the interactive @google/gemini-cli coding agent). Use the Google GenAI SDKs (gemini-api-dev, gemini-live-api-dev) when calls live inside application source or need bidirectional Live API WebSockets.

Install and auth

# macOS / Linux (set GEMINI_VERSION=<tag> to pin a release)
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Credentials resolve in order (first match wins): --api-key / --access-token flags, GEMINI_API_KEY / GEMINI_ACCESS_TOKEN env vars, the OS keychain, then ~/.config/gemini-api/config.yaml.

• Env var (agents and CI): export GEMINI_API_KEY="..."
• Workstation key: gemini-api configure --api-key "..." saves to the OS keychain. Pass --no-keyring or GEMINI_NO_KEYRING=1 on headless Linux to use config.yaml; gemini-api auth logout clears stored keys.
• Active auth check: gemini-api whoami (add -o json for JSON) prints masked credentials and the winning source.

The #1 auth trap: an exported GEMINI_API_KEY overrides credentials stored in the keychain or config.yaml, billing whichever project that env var belongs to. Check gemini-api whoami to see which source won, or run env -u GEMINI_API_KEY gemini-api ... to ignore the env var.

Command structure

gemini-api <intent> [prompt] [flags]          # task commands with model and modality presets
gemini-api <resource> <action> [flags]        # REST resource groups

Run gemini-api --help to list commands, or <subcommand> --help for flags and examples (--usage dumps a 45 KB KDL spec, so stick to --help to save context).

Command	Key flags / actions	Default model & behavior
generate [prompt]	-m, -i, --stdin, --system, --previous-interaction-id, --stream=false, --body	gemini-3.8-flash; streams text deltas to stdout
image [prompt]	-m, -i, --aspect-ratio, --image-size (512..4K), --previous-interaction-id, --out	gemini-nano-banana-2.1; writes image, prints path
tts [text]	-f, --stdin, --voice (default Kore), --multi-speaker, --language, --out	gemini-3.8-flash-tts; writes 24 kHz WAV, prints path (unstored)
music [prompt]	-m, -f, --stdin, --out, --body	lyria-3.5; writes audio track, prints path
video [prompt]	-m, -i, --aspect-ratio, --resolution (360p..4k), --async, --resume, --out	gemini-omni-1.1-flash; polls until done, writes MP4, prints path
analyze [question]	-i (required, repeatable), --stdin, --system, -m	gemini-3.8-flash; answers over PDFs, media, CSV/text, YouTube URLs (unstored)
transcribe	-i (required, repeatable), --format (md, text, json, srt), --no-speakers, --no-timestamps, --out	gemini-3.8-flash; writes --out (or ./transcript-*), prints path (unstored)
agent	run, status, cancel, delete-interaction; create, list, get, delete	Runs models or managed agents; manages custom agent definitions
files	upload [--wait], list, get, generated-files-list, register, delete	Uploads reusable files/<id> URIs (48h TTL; up to 2 GB, 50 MB PDFs)
models	(bare), list [--all], get <id>	Bare models prints an offline catalog; list and get query the live API
environments	create, list, get, delete, files, connect, poll, serve	Remote sandboxes and workspace snapshots (credentials, webhooks, triggers for agent infra)

Model selection: use gemini-3.8-flash (default), gemini-4-argon (hard reasoning and coding), or gemini-3.5-flash-lite (high throughput); for images, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, or gemini-3-pro-image. Avoid deprecated gemini-2.5-*, gemini-2.0-*, and gemini-1.5-* models.

Global flags

Flag	Purpose
-o, --output-format	pretty (default), json, toon, yaml, table
-q, --jq	Filter JSON output with a built-in jq expression (--raw-output is true by default)
--agent-mode	Compact TOON on stdout and structured JSON errors on stderr
--no-interactive	Disable prompts, TUI forms, and explore
--dry-run	Validate inputs and preview redacted HTTP requests offline (-o json outputs JSON)
-d, --debug	Log HTTP request and response details to stderr

Exit codes: 0 ok, 1 runtime or API error (including failed or incomplete runs), 2 usage or validation error, 3 auth error. See gemini-api --help-global for --server-url, pagination, and auth flags.

Output

Media (image, tts, music, video) and transcribe write files locally and print only the file path on stdout. Adding -o json still writes the file and prints {path, mime_type, size_bytes, response_id, status}.

Streaming and JSON shape: generate and agent run stream plain reply text by default, so -o json alone emits NDJSON events. Pass --stream=false -o json for one JSON object {id, status, steps, usage} (bare --stream=false prints metadata YAML, and --jq or --background disables streaming automatically). Reply text lives under .steps[] model_output (see agent status below) rather than .candidates[]. On paginated list commands, --jq runs per page envelope (.models[]?.name, .agents[]?.id).

Input

• -i / --input attaches media and documents on generate, image, video, analyze, transcribe, and agent run (repeatable). Accepts local paths up to ~14 MB (20 MB base64 cap), files/<id> URIs, or YouTube URLs. Upload larger or reused files once with gemini-api files upload <path> --wait.
• -f / --file reads prompt text from a file on tts and music. Piped text needs --stdin: when piping plain text into generate, image, video, or analyze, pass --stdin or piped input gets parsed as a JSON --body.
• --body passes raw Gemini API JSON inline, from @file.json, or via @- (merges with flags; exits 2 on duplicate keys). Use it for response_format schemas, tools (google_search, code_execution, url_context, function declarations), generation_config, environment, or store.
• Don't dump --schema raw: it prints ~91 KB of minified JSON and exits before --jq runs. Pipe it to jq:

  gemini-api generate --schema | jq '."$defs".ModelInteraction.properties | keys'
  

Media, analysis, and transcription

HERO=$(gemini-api image "Isometric cloud database icon" --aspect-ratio 16:9 --image-size 2K --out ./hero.jpg)
gemini-api image "Add warm sunset lighting" -i "$HERO" --out ./hero-sunset.jpg

gemini-api tts "Alice: Ready to ship? Bob: Checks are green." \
  --multi-speaker "Alice=Kore,Bob=Puck" --out ./dialogue.wav

VID_ID=$(gemini-api video "Aerial coastal cliffs at sunrise" --aspect-ratio 16:9 --resolution 1080p --async)
gemini-api video --resume "$VID_ID" --out ./cliffs.mp4

FILE_URI=$(gemini-api files upload ./call.mp4 --wait)   # prints files/<id>
gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format srt --out ./call.srt

Managed agents and sandboxes

• deep-research-preview-04-2026 and deep-research-max-preview-04-2026: run with --background and poll agent status.
• antigravity-preview-09-2026 (Linux sandbox with Bash, Python, Node, file ops, and web search): pass environment ("remote") or environment_id in --body.

ID boundary: agent status, agent cancel, and agent delete-interaction take a run ID (v1_...). agent create, agent get, agent list, and agent delete manage custom agents only (built-in agents appear in gemini-api models; cap agent list and environments list with --page-size 10).

RUN_ID=$(gemini-api agent run "Compare WebRTC SFU architectures with primary sources." \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$RUN_ID" --jq '.status'   # queued | in_progress | completed | failed
gemini-api agent status "$RUN_ID" \
  --jq '[.steps[]? | select(.type=="model_output") | .content[]? | select(.type=="text") | .text] | join("")'

ENV_ID=$(gemini-api agent run "Benchmark radix sort vs timsort in Python and write results.csv." \
  --agent antigravity-preview-09-2026 --body '{"environment": "remote"}' --jq '.environment_id')
gemini-api environments files list -e "$ENV_ID" -r
gemini-api environments files download "$ENV_ID" results.csv --out ./results.csv

gemini-api agent create --id code-reviewer --base-agent antigravity-preview-09-2026 \
  --system-instruction "Review diffs for race conditions and auth bugs."

Multi-turn and structured output

Calls store state server-side by default (store is true), so multi-turn chains only need --previous-interaction-id (system_instruction, tools, and generation_config apply per turn; setting store to false disables previous_interaction_id and background):

TURN1=$(gemini-api generate "Propose 2 indexing strategies for time-series logs." --jq '.id')
gemini-api generate "Compare them for write-heavy workloads." --previous-interaction-id "$TURN1"

Combine --stdin with --body for schema-constrained JSON output:

cat build.log | gemini-api generate "Extract unique compiler errors." --stdin --stream=false --body '{
  "response_format": {
    "type": "text", "mime_type": "application/json",
    "schema": {"type": "object", "properties": {"errors": {"type": "array", "items": {"type": "string"}}}, "required": ["errors"]}
  },
  "store": false
}'

Full CLI reference: aistudio.google.com/docs/cli.md; docs index: llms.txt.