Gemini API CLI Official Guide (Part 1): Giving Your AI Agent a Stateless Multimodal CLI Toolbox

Verified environment: 2026-11-14 21:53 (Asia/Taipei, UTC+8) on macOS Apple Silicon (ts-m1), gemini-api 0.4.6 (supplemented by our 2026-11-15 live Paid Tier run documented in Section 7). Built for both international developers (Dev.to) and the Taiwan / APAC developer community & GDE workshops. 🎬 Video & Bilingual Navigation ▶️ 70-second Walkthrough Video (YouTube 16:9): https://youtu.be/Rb5ij419w2Y ⚡ 13-second Highlight (YouTube Shorts 9:16): https://youtube.com/shorts/82-Z_Jq-ezQ 📱 Facebook Reel (9:16): https://www.facebook.com/reel/1484807533581243/ 🇹🇼 Original Traditional Chinese Edition (Substack): https://memo.jimmyliao.net/p/gemini-api-cli-part-1-agent-api 1. Introduction & the 2026 CLI Landscape Shift June 18, 2026 marks a watershed moment for Google's individual developer CLI entry points: gemini-cli consumer access for free personal accounts and Google AI Pro/Ultra (Google One) plans transitioned to Antigravity CLI (agy). That transition applies to specific personal/consumer account scopes and should not be oversimplified as every gemini-cli mode or enterprise/paid API path disappearing overnight. See the official Google blog announcement for the exact scope. Developers can now adopt a clean two-track architecture: agy (or Codex / Claude Code) as the Agent Brain & Host: handles reasoning, planning, file edits, and long-horizon coding tasks. gemini-api as the Stateless Multimodal CLI Toolbox: exposes image generation, video generation, multi-speaker TTS, music composition, transcription, and server-side Managed Agents over shell primitives. Look at the official repository (google-gemini/gemini-api-cli) to see how it is specifically positioned to equip any shell-capable agent with Gemini models. Here, stateless means the CLI binary itself does not maintain hidden local chat history between runs; the underlying Interactions API can still persist server-side interactions, resume via --previous-interaction-id, or run background jobs. Mistaking "stateless CLI" for "no server-side state exists" leads to misdesigning multi-turn media pipelines. 2. Installation & Standard Authentication gemini-api ships as a standalone Go binary. On macOS or Linux, install it using the official installer script: curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash command -v gemini-api gemini-api --version On ts-m1 (Darwin / arm64), the installer skipped /usr/local/bin (non-writable) and installed /Users/jimmyliao/.local/bin/gemini-api (v0.4.6; build timestamp 2026-11-11 02:46:39 Asia/Taipei). Ensure $HOME/.local/bin is on your PATH: export PATH="$HOME/.local/bin:$PATH" Because latest tracks newer releases over time, pin GEMINI_VERSION in CI per the official CLI installation docs. For standard authentication, use either an environment variable or interactive configuration (choose one; no need to mix both): export GEMINI_API_KEY="YOUR_API_KEY" # OR interactive OS Keychain storage: gemini-api configure gemini-api whoami Note that configure stores secrets in your OS Keychain, whereas --no-keyring / GEMINI_NO_KEYRING=true alters secret resolution and should not be casually enabled without understanding the boundary. In our clean isolation harness, every subshell explicitly unset GEMINI_API_KEY / GEMINI_ACCESS_TOKEN and exported GEMINI_NO_KEYRING=true; gemini-api whoami reported both credentials [unset] and API version v1beta. Crucially, whoami inspects local configuration sources—it does not prove remote API entitlement or quota. See experiments/01-cli-introspection/results.md for the full capture. 3. Why Is This CLI Built for AI Agents? AI agents routinely trip over stale CLI flags, dump raw base64 media into context windows, or hang forever on interactive prompts. gemini-api avoids those traps with machine-discoverable schemas and direct file I/O. First, probing the documentation page itself via curl -sS -I https://aistudio.google.com/docs/cli returns: content-type: text/markdown; charset=utf-8 x-llms-txt: /llms.txt link: ; rel="llms-txt", ; rel="llms-full-txt" On the binary side, four introspection flags govern agent self-discovery: gemini-api --usage # Complete KDL command tree gemini-api generate --schema # Request body JSON Schema gemini-api agent run --schema gemini-api generate "Test prompt" --dry-run -o json Caveat from our v0.4.6 introspection: --schema is not uniform across every subcommand. generate, image, video, and agent run succeeded, while analyze, tts, and transcribe returned exit code 2 (unknown flag: --schema). Inspect each subcommand's --help first, and check agent run --schema whenever you need full request body fidelity. Dry-run redaction was also verified: passing a synthetic dummy --api-key outputs "X-Goog-Api-Key": ["[REDACTED]"]. Note carefully that --dry-run validates local request construction—it does not verify server model access, billing, or IAM permissions. While the CLI supports both JSON and TOON structured output, gemini-api v0.4.6 always emits a JSON request envelope under --dry-run: {"dry_run":true,"request":{"method":"POST","url":"https://generativelanguage.googleapis.com/v1beta/interactions","headers":{"Accept":["text/event-stream"],"Content-Type":["application/json"],"User-Agent":["google-genai-cli/0.4.6 gl-go/go1.26.10"]},"body":{"input":"Test prompt","model":"gemini-3.8-flash","stream":true}}} Built-in --jq also has a quirk under --dry-run: running generate "Test prompt" --dry-run --jq '.body.model' still prints the full envelope (and flips stream to false). Pipe -o json into external jq instead when filtering dry-run payloads: gemini-api generate "Test prompt" --dry-run -o json | jq -r '.request.body.model' Full dummy-key dry-run traces and HTTP header checks are archived in experiments/02-part1-standard-workflows/sample-dry-runs.md. 4. Core Commands & Multimodal Primitives Using synthetic local fixtures (input.txt 64 bytes, silence.wav 0.1s 16 kHz mono PCM), all six core commands succeeded cleanly under --dry-run (exit code 0): cd experiments/02-part1-standard-workflows gemini-api generate "Test prompt" --dry-run --output-format json gemini-api analyze -i input.txt "Summarize" --dry-run gemini-api image "Minimalist cloud database icon" --out /tmp/gapi-test.jpg --dry-run gemini-api tts "Welcome to the Taiwan developer community" --out voice.wav --dry-run gemini-api transcribe -i silence.wav --out transcript.md --dry-run gemini-api video "A cloud above Taipei" --out cloud.mp4 --dry-run Every subcommand targets POST https://generativelanguage.googleapis.com/v1beta/interactions. Understanding how their JSON bodies differ explains how to wire multimodal pipelines: Command Default Model (v0.4.6) Key Request Payload Observation generate gemini-3.8-flash input string, stream:true analyze gemini-3.8-flash user_input.content array containing text/media + prompt, store:false, stream:false image gemini-nano-banana-2.1 response_format:{"type":"image"}, stream:false tts gemini-3.8-flash-tts response_format.type:audio, speech_config:[{"voice":"Kore"}], store:false transcribe gemini-3.5-transcribe audio/wav input, transcription_config.mode.type:verbatim, diarization & word timestamps video gemini-omni-1.2-flash response_format.type:video, background:true, stream:false File bytes never bloat agent context on --dry-run: analyze summarizes files as "text":"" and audio as "data":"". Abbreviated TTS request body observed on v0.4.6: { "generation_config": {"speech_config": [{"voice": "Kore"}]}, "input": [{"content": [{"text": "Welcome to the Taiwan developer community", "type": "text"}], "type": "user_input"}], "model": "gemini-3.8-flash-tts", "response_format": {"type": "audio"}, "store": false, "stream": false } Output handling flags such as --out remain client-side and stay out of the HTTP body. Per --help, tts outputs 24 kHz mono PCM WAV (adjusting .mp3 targets back to .wav), transcribe supports md, text, json, and srt, and video waits on background completion unless --async is passed. 4.1 End-to-End Scenario (Part 1 Perspective): 6-Step 9:16 AI Reels Pipeline Our running scenario—"Understand in 15 Seconds Why AI Agents Need a Multimodal CLI Toolbox"—chains these primitives into a version-controlled pipeline: Storyboard: generate --stdin creates the 3-scene 9:16 breakdown. Visual Keyframes: image --aspect-ratio 9:16 --image-size 1K generates Scene 1, followed by image -i scene1-keyframe.jpg to preserve character and visual style into Scene 2 (--previous-interaction-id can also continue live server interactions). Video Motion: video --aspect-ratio 9:16 --resolution 720p -i turns the approved Scene 1 keyframe into motion (background:true). Dual-Speaker Voiceover: tts --multi-speaker "Host=Kore,CoHost=Puck". BGM & Subtitles: music + transcribe --format srt. Safe-Zone & Alignment QA: analyze inspects the 9:16 composition against storyboard.json. See examples/reels-storyboard-pipeline/run-reels-pipeline.sh and the verbatim trace examples/reels-storyboard-pipeline/dry-run-trace.md. Runnable Part 1 Example (sample-part1-reels-primitives.sh) Run directly from the workspace root (examples/part1-multimodal-cli/sample-part1-reels-primitives.sh); synthetic fixtures/* validate MIME handling without incurring API charges: bash