Overview

gemini-api is a stateless command-line client for the Gemini API, built for coding agents and assistant tools that already have shell access. Rather than requiring a custom integration, it exposes Gemini's text and multimodal generation, media creation, file analysis, and managed-agent runs as ordinary commands. A host agent can plan the work, invoke the CLI, and then use the returned file paths or interaction IDs to continue.

The command set is organized around practical tasks: generate for text, image/tts/music/video for media, analyze for questions over PDFs, images, audio, video, CSV, and YouTube URLs, transcribe for captions and transcripts, and agent for running or managing Gemini managed agents. Auxiliary commands manage files, models, credentials, webhooks, triggers, and sandbox environments command overview. The binary is distributed as a single Go executable for macOS, Linux, and Windows, and is explicitly in beta beta note.

Quick start

You need a Gemini API key from Google AI Studio and a shell environment. Install with the platform script, go install, or a prebuilt archive from GitHub Releases; the README also documents the script-based installers installation.

1. Make the key available:

export GEMINI_API_KEY="YOUR_API_KEY"

For persistence, the README offers gemini-api configure --api-key "YOUR_API_KEY" (OS keychain or config file) and gemini-api configure --interactive configuration steps.

2. Validate locally without a network call, then run for real:

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

The README recommends this dry-run check before the first API call quick start.

3. Add instructions to the host agent's AGENTS.md, CLAUDE.md, .cursorrules, or tool configuration so the agent knows to inspect --help/--usage, preview with --dry-run, request JSON with --output-format json, and retain returned file paths and interaction IDs. A representative media command writes an asset and prints its path:

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

Agent interface

Commands, flags, request schemas, and environment/config keys are discoverable from the binary itself: --usage emits the command tree in KDL, --schema prints the bundled JSON Schema for commands accepting a request body, and --dry-run previews the resolved HTTP request with credentials redacted and no network access agent discovery. --agent-mode enables structured JSON errors on stderr and compact TOON output by default, while --output-format json selects JSON explicitly. Exit codes distinguish success (0), runtime failures (1), validation errors (2), and authentication failures (3).

For calls not covered by short flags, --body accepts a full Interactions API request payload, and the README walks through inspecting the image schema, authoring a JSON body, and running it with --out and --dry-run custom bodies.

Constraints

• The CLI is beta and may introduce breaking changes between releases; the README recommends pinning a release version in CI and automated workflows status.
• An API key is required and calls are billed according to your Gemini API account; the key must be present in the shell environment or stored via configure/auth.
• The CLI keeps no local conversation state. Multi-turn continuity relies on server-side interactions and previous_interaction_id; uploaded files have their own retention window (the Files API is described as 48-hour retention).
• Large media should be uploaded once (files upload --wait) and reused by URI rather than passed inline.
• The project is licensed under Apache-2.0, and pull requests are not being accepted at this time licensing.

HotRepo's take

The project first appears in HotRepo's records on 2026-11-07, ranking 3rd on the Go language daily list with 16 stars gained that day, bringing it to 462 stars and 73 forks. That is a single snapshot, so it supports interest on that date rather than a trend. The design choice most worth noting is the focus on machine-readable, self-describing behavior—--usage, --schema, --dry-run, --agent-mode, and explicit exit codes—which matches the stated goal of letting an existing shell agent use Gemini without bespoke glue code. Treat the beta status and the requirement for a valid API key as the practical limits on adopting it today.