Google announced the beta release of Gemini API CLI on 27 October, introducing a command-line client for coding agents, scripts and automated development processes. Available as gemini-api, the tool calls Gemini models and Google-managed agents from a terminal through the Interactions API. It brings together content generation, file analysis and the execution of research tasks in the background.
The project is open source, and Google distributes executables for macOS, Linux and Windows. Written in Go, the client can run as a single executable without adding a software library to the application project. Beta status applies to this new client; the cloud capabilities it accesses follow the separate availability and conditions of the selected models or agents.
An interface for existing agents and working environments
Gemini API CLI operates inside an environment that can execute shell commands. The documentation names coding agents such as Antigravity, Claude Code and Codex, but the same interface is available to scripts and CI systems that automatically run checks or operations during development. The host agent retains coordination of the task and uses the client to make calls to Gemini services.
Despite the similar name, Gemini CLI has a different role. Gemini API CLI is an API client without hidden local conversation history, while Gemini CLI is an interactive coding agent. In the new client, commands are separate calls, and continuing a process requires explicit use of the files and identifiers returned by the service.
The commands cover text, image, speech, music and video generation, as well as document analysis and transcription of recordings. Media results are written to disk, and the calling program receives the file path. Structured output can also include the content type, size or operation status, allowing the result to be passed to the next stage of a workflow.
The path of a Gemini API CLI request
- 1. Agent or scriptPrepares the task and input data.
- 2. Terminal clientValidates and sends the API request.
- 3. Gemini serviceThe model or agent processes the request.
- 4. ResultText, a file path or an ID for continuation.
Separating the file from the command response keeps binary data outside the agent's text context. An audio file or image can be passed onwards through its path without inserting encoded content into the conversation. For text and metadata, the client offers JSON output and field filtering, which programs can use to process results automatically.
Inspectable schemas and responses for automated processes
The client includes command descriptions and request schemas that can be inspected without network access. According to Google, an agent can therefore check parameter structures directly in the installed executable. A dry-run function validates the inputs and displays the prepared HTTP request with credentials redacted, without sending the call to the API.
Normal execution is designed to work without interactive prompts. Those are enabled explicitly, and errors can be returned in a structured format. Exit codes distinguish success, runtime or API problems, invalid parameters and authentication errors. An automated process can use these categories to decide whether to stop a task or request intervention from its operator.
Common parameters are available through command options, while additional configurations can be supplied as a JSON request body. The documentation covers schemas for generated output and configuration of the tools called by a model. If the same value is defined through conflicting mechanisms, the client rejects the request during validation.
Document analysis and file retention
Analysis functions accept PDF documents, images, audio and video recordings, CSV and text files, and public YouTube URLs. Multiple files can be included in the same request, including for comparisons. Transcription produces files containing text, timestamps and speaker labels in formats such as Markdown, JSON or SRT, according to the command used.
For local inputs sent inline, Gemini API CLI sets a limit of 14 MB of raw data within a 20 MB request threshold for base64-encoded data. Larger files are uploaded through the Files API, and subsequent requests use the resulting identifier. This client limit is separate from the capacity of the file-storage service.
The Files API allows up to 2 GB per file and a total of 20 GB per project. Uploaded files are retained for 48 hours and then deleted automatically; the service also supports manual deletion. Their metadata can be retrieved during the retention period. Google distinguishes downloading model-generated files from access to files uploaded by the user.
Background tasks with explicit identifiers
For longer operations, the client can launch cloud-managed agents, including Deep Research, and immediately return the interaction identifier. The program that initiated the request keeps this identifier, checks execution status and retrieves the result once the task has completed. Operations for cancelling an active task are also available.
The client's lack of implicit local conversation history is separate from data storage in the Interactions API. The API stores interactions by default and can use a previous interaction's identifier to continue a conversation. According to the documentation, this mechanism reuses input and output history, while tools, system instructions and generation configuration apply to the current interaction.
Interaction storage can be disabled through an explicit parameter. That configuration, however, excludes background execution and subsequent continuation through the interaction identifier. A workflow that launches a research agent in the background and one that requests a response without storing the interaction therefore have different API configurations.
API access and application integration
Authentication uses a Gemini API key associated with a Google Cloud project, through which permissions, quotas and billing are managed. The client can receive the key from its execution environment or keep it in the operating system's secret-storage facility. For CI processes, Google specifies using a secret manager separately from the project's source code.
The model can be selected for each task, and the client includes commands for inspecting available models. The choice of model determines the capabilities used for text, images and other content types. The access key remains a project credential; publishing it in a web page's code would allow other people to use the associated resources.
Google distinguishes terminal-based work from integrating GenAI libraries into an application's code. For application development with AI integration, the SDKs provide direct access from languages such as Python, JavaScript, Go and Java. Gemini API CLI instead serves the agent, script or development process that needs to make a call from the shell.
The client uses HTTP requests, progressively delivered SSE responses and polling for asynchronous operations. Bidirectional WebSocket connections required for certain real-time audio and video sessions are served through the Live API and GenAI SDKs. For automated environments, Google recommends pinning a version of the beta client because updates can change compatibility between versions.
