Gemini API CLI

Die Gemini API CLI (gemini-api) ist ein zustandsloser Befehlszeilenclient ohne Abhängigkeiten, der für KI-Agenten mit Shell-Zugriff entwickelt wurde und über Skripts und CI verwendet werden kann. Ihr Coding-Agent kann dann Text und Medien generieren, Dateien analysieren und Aufgaben an von Gemini verwaltete Agenten delegieren. Es funktioniert mit Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes oder jeder Shell-Umgebung.

Jedes Feature wird als Standard-Shell-Befehl in der Interactions API ausgeführt. Führen Sie die gleichen Befehle über einen Agenten-Unterprozess, Ihr Terminal oder eine CI-Pipeline aus:

# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"

# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false

Das richtige Gemini-Tool auswählen

Verwenden Sie gemini-api, wenn ein Agent oder Script Gemini direkt über die Shell aufrufen muss, ohne dass Sie Ihrem Projekt SDK-Code hinzufügen müssen. Verwenden Sie die SDKs und die Einrichtung des Coding-Agents, wenn Sie Gemini in eine Anwendung einbinden:

Funktionsweise

Unformatierte REST-Aufrufe und interaktive CLIs verursachen bei KI-Agenten für die Programmierung häufig Probleme. Base64-Medien füllen das Kontextfenster, interaktive Prompts blockieren Unterprozesse und veraltete Trainingsdaten führen zu halluzinierten Flags.

Vier Designentscheidungen sorgen dafür, dass gemini-api für Kundenservicemitarbeiter zuverlässig ist:

• Offlineschemasuche: Übergeben Sie --usage, um den Befehlsbaum (in KDL) auszugeben, oder --schema, um das JSON-Schema für --body-Anfragen auszugeben.
• Dateien auf dem Laufwerk, Pfade auf stdout: Medien- und Transkriptionsbefehle schreiben Dateien auf das Laufwerk und geben nur den Ausgabepfad aus, sodass Binärdaten nicht im Kontext enthalten sind.
• Probeläufe und strukturierte Ausgabe: --dry-run validiert Eingaben, entfernt Anmeldedaten und zeigt eine Vorschau der HTTP-Anfrage offline an. Übergeben Sie -o json, -o toon oder --jq für eine maschinenlesbare Ausgabe. Fügen Sie --agent-mode hinzu, um strukturierte JSON-Fehler für stderr zurückzugeben, und prüfen Sie die Exit-Codes, um Fehler zu beheben. Befehle werden nur dann abgefragt, wenn Sie --interactive übergeben.
• Standardmäßig zustandslos: Befehle behalten keinen verborgenen lokalen Zustand bei. Verketten Sie mehrstufige Aufgaben explizit mit --previous-interaction-id, einem hochgeladenen files/<id>-URI oder einer Hintergrundinteraktions-ID.

Mit -o json schreiben Medienbefehle die Datei weiterhin auf das Laufwerk und geben Metadaten in stdout aus:

{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/db-icon.jpg",
  "response_id": "v1_...",
  "size_bytes": 2914159,
  "status": "completed"
}

Jetzt starten

Installieren Sie die Befehlszeile, fügen Sie gemini-api zu Ihrem PATH hinzu, legen Sie GEMINI_API_KEY fest und fügen Sie Ihrem KI-Agenten für die Programmierung Nutzungsregeln hinzu.

1. Binärdatei installieren

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

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

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

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

2. Authentifizierung konfigurieren und bestätigen

Erstellen Sie einen API-Schlüssel in Google AI Studio (siehe API-Schlüssel). Legen Sie GEMINI_API_KEY in Ihrer Shell und in der Subprozessumgebung Ihres KI-Agenten fest:

export GEMINI_API_KEY="YOUR_API_KEY"

Auf einer lokalen Workstation können Sie den Schlüssel im Schlüsselbund Ihres Betriebssystems (macOS-Schlüsselbund, Linux Secret Service oder Windows Credential Manager) speichern. Übergeben Sie --no-keyring, um den Schlüssel stattdessen in ~/.config/gemini-api/config.yaml zu speichern:

# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"

# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run

3. Anweisungen für den Agenten

Fügen Sie dieses Snippet der AGENTS.md, CLAUDE.md, .cursorrules oder dem System-Prompt Ihres Projekts hinzu, damit Ihr Programmier-Agent weiß, wie er gemini-api verwenden soll:

## Gemini API CLI (`gemini-api`)

You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.

1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.

Prompten Sie Ihren Coding-KI-Agenten dann wie gewohnt:

Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.

Befehle

Führen Sie gemini-api --help aus, um alle Befehle aufzulisten, oder gemini-api explore, um sie interaktiv zu durchsuchen.

Workflows

Für jeden Befehl wird standardmäßig ein Modell verwendet, das für die jeweilige Aufgabe geeignet ist. Übergeben Sie --model (-m), um ein anderes Modell auszuwählen. Führen Sie gemini-api models aus, um die verfügbaren Optionen aufzulisten.

Bilderstellung und -bearbeitung

Agents, die Web- oder mobile Benutzeroberflächen erstellen, können mit Nano Banana Platzhalter, Symbole und Hero-Images generieren. Übergeben Sie einen generierten Pfad mit -i, um das Bild zu bearbeiten:

# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
  -i "$HERO_PATH" \
  --out ./public/images/hero-winter.jpg

Übergeben Sie -i mehrmals, um Referenzbilder zu kombinieren, z. B. eine Figur und einen Styleguide.

Sprachsynthese

gemini-api tts synthetisiert 24-kHz-WAV-Audio für UI-Hinweise, Vorschauen für Bedienungshilfen und gesprochene Anleitungen. Die Standardstimme ist Kore. Mit --voice können Sie eine andere Stimme auswählen. Labeln Sie bei einem Dialog mit zwei Sprechern jeden Redebeitrag im Prompt und ordnen Sie die Sprecher den Stimmen zu:

gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede \
  --out ./public/audio/build-ok.wav

gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./public/audio/release-intro.wav

Musik und Video

Mit Lyria eigene Musikstücke komponieren und mit Gemini Omni MP4-Clips generieren:

gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
  --out ./public/audio/bg-loop.mp3

gemini-api video "A drone shot of a mountain landscape at sunrise." \
  --aspect-ratio 16:9 \
  --resolution 1080p \
  --out ./public/video/mountain-sunrise.mp4

Standardmäßig wartet der Befehl video, bis die Generierung abgeschlossen ist, und schreibt die MP4-Datei auf das Laufwerk. Übergeben Sie --async, um sofort eine Interaktions-ID zurückzugeben, und führen Sie dann später gemini-api video --resume <id> --out <path> aus. Übergeben Sie -i, um ein vorhandenes Bild zu animieren.

Textgenerierung

gemini-api generate streamt Text an stdout:

gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."

Fügen Sie --stdin hinzu, um Text in den Prompt einzufügen. Übergeben Sie --previous-interaction-id, um eine frühere Interaktion fortzusetzen.

Dokumentanalyse und Transkription

analyze beantwortet Fragen zu PDFs, Tabellen, Screenshots, Audio- und Videodateien sowie öffentlichen YouTube-URLs. transcribe schreibt ein formatiertes Transkript (md, text, json oder srt) auf die Festplatte:

gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md

gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt

Übergeben Sie -i mehrmals an analyze, um Dateien zu vergleichen, z. B. Vorher-Nachher-Screenshots.

gemini-api sendet lokale Dateien inline bis zu 14 MB (20 MB nach Base64-Codierung). Größere Dateien sollten Sie einmal mit files upload --wait hochladen und den zurückgegebenen files/<id>-URI wiederverwenden:

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)

gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

KI-Agenten ausführen und verwalten

Ihr Coding-Agent kann mehrstufige Recherche- oder Sandbox-Aufgaben an von Gemini verwaltete Agenten wie den Deep Research-Agenten delegieren. Übergeben Sie --background --stream=false, um sofort eine Interaktions-ID zu erhalten, anstatt einen Stream offen zu halten:

# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json

Führen Sie gemini-api agent cancel <id> aus, um einen laufenden Job zu beenden. Sie können den Antigravity-Agenten auch in einer Remote-Sandbox mit agent run starten oder benutzerdefinierte Agenten mit agent create, list, get und delete verwalten. Informationen zum Konfigurieren von Agent-Sandboxes finden Sie unter Umgebungen.

Benutzerdefinierte Anfragetexte

Für Optionen ohne dedizierte Flags übergeben Sie eine unbearbeitete JSON-Nutzlast der Interactions API mit --body (inline oder als @file.json). Übergeben Sie --body, um response_format-Schemas, Tools für Funktionsaufrufe, generation_config oder "store": false festzulegen. Führen Sie zuerst gemini-api <command> --schema aus, um gültige Felder zu prüfen:

# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json

# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
  --stdin \
  --body '{
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {"errors": {"type": "array", "items": {"type": "string"}}},
        "required": ["errors"]
      }
    },
    "store": false
  }'

--body wird mit Befehls-Flags zusammengeführt. Wenn beide denselben Schlüssel festlegen, schlägt der Befehl mit dem Exit-Code 2 fehl, sodass widersprüchliche Eingaben schnell fehlschlagen.

Exit-Codes

Jeder Befehl gibt einen typisierten Exit-Code zurück, sodass Skripts und Agents Fehler ohne Parsen von Fehlertext verarbeiten können. 3 signalisiert beispielsweise ein Authentifizierungsproblem und 2 eine ungültige Befehlssyntax:

Führen Sie gemini-api --help-global aus, um globale Flags aufzulisten, die von jedem Befehl gemeinsam verwendet werden (Authentifizierung, Ausgabe, Netzwerk und Diagnose).

Beschränkungen

• Streamingbefehle (generate und agent run) erfordern --stream=false, wenn sie mit -o json oder --jq kombiniert werden, um ein einzelnes JSON-Antwortobjekt zurückzugeben.
• Inline--i-Dateieingaben sind auf 14 MB Rohdateidaten (20 MB Anfrage-Nutzlast einschließlich Base64-Codierung) begrenzt. Große Dateien mit gemini-api files upload hochladen. Die Files API löscht hochgeladene Dateien nach 48 Stunden.
• gemini-api unterstützt Standard-HTTP-Anfragen, SSE-Streaming und asynchrone Abfragen, aber keine bidirektionalen WebSockets. Verwenden Sie für Echtzeit-Sprach- und Videostreaming die Live API mit den Google GenAI SDKs.

Nächste Schritte

• Coding-Agent einrichten
• Interactions API
• Verwaltete Gemini-Agenten
• gemini-api-cli auf GitHub