Gemini API CLI and Gemini CLI are different tools. The first, invoked as gemini-api, is a command-line client without hidden local session state. Google released it in beta on October 27, 2026, to call Gemini API models and managed agents from scripts, continuous integration (CI) pipelines, and other agents. The second, invoked as gemini, is a coding agent that converses with users and can work with project files and shell commands. Gemini CLI is generally the starting point for interactive development; gemini-api is worth considering when an existing workflow needs explicit API calls.
CLI stands for command-line interface, a program controlled through a terminal. An API is an interface through which one program requests capabilities from another. Similar names do not make the new tool an upgrade or drop-in replacement for the older one. This is a documentary comparison based on official material consulted on October 29, 2026, not a firsthand test of either tool.
What launched on October 27?
The Gemini API release notes explicitly identify the gemini-api beta on that date. The new client uses the Interactions API to generate text and media, analyze documents, transcribe files, and start managed agents. Google describes it as a standalone binary that does not require adding an SDK to a project. An SDK is a set of development libraries imported into application code.
The key technical term is stateless: one gemini-api invocation does not implicitly keep a local session for the next command. To chain tasks, the script owner must pass references such as a previous interaction ID, a file path, or a background job ID. That does not mean the remote API never stores data. The Interactions API supports server-side state and, according to its documentation, stores requests by default, with store=false available in the documented cases.
How the two tools compare
| Criterion | Gemini API CLI (gemini-api) | Gemini CLI (gemini) |
|---|---|---|
| Main role | A client for explicit model and managed-agent API calls. | A terminal agent that can explore, explain, and modify projects with user oversight. |
| Typical workflow | Independent commands, output files, and structured formats for automation. | Conversational sessions with tools, permissions, and project context. |
| Automation | Designed for scripts and CI, with JSON output, request previews without network calls, and exit codes. | Also has a headless mode using -p and JSON output; it is not limited to interactive use. |
| Authentication | The quickstart centers on a Gemini API key provided through GEMINI_API_KEY or credential configuration. | Supports Google Account sign-in, Gemini API keys, and Vertex AI options, depending on the scenario. |
| Documented installation | Binaries for macOS, Linux, and Windows; install scripts and a Go installation option. | The @google/gemini-cli package via npm, plus other documented methods. |
| Release status | Beta, with an official warning about breaking changes between minor versions. | A separate project with stable, preview, and nightly release channels. |
Thus, the difference is not simply that one can automate tasks and the other cannot. Gemini CLI has a noninteractive mode and can run in CI. What distinguishes gemini-api is its compact interface to specific Interactions API operations for other agents and programs to control.
When should you use each command?
To inspect a repository and work through proposed changes: Gemini CLI's documentation shows npm install -g @google/gemini-cli for installation and gemini to start it. The agent can inspect code, propose edits, and ask for permission to perform certain actions. For a one-off task without an interactive interface, its documentation also demonstrates gemini -p "Explain this error".
To call the API from another agent or script: after installing the binary and setting up an API key and appropriate permissions, the new tool's guide illustrates gemini-api generate "Summarize this text" and gemini-api analyze -i ./report.pdf "List the findings". These are documentation-based syntax examples, not outputs verified by DTech. The command gemini-api generate "Test" --dry-run previews and validates the request locally without sending it to the API.
Google documents structured output using -o json, exit codes for failures, and --stream=false when a generation flow must return one JSON object. These options matter when software needs to parse the output without reading an interactive terminal conversation.
Authentication, costs, and migration require care
- Credentials: gemini-api can read GEMINI_API_KEY from the environment or save credentials in the operating system's secure store. Never commit keys to source code, logs, or repositories. Google Account sign-in in Gemini CLI should not be assumed to be commercially equivalent to API-key access.
- Commands are not drop-in compatible: changing gemini to gemini-api in a script may affect arguments, response formats, error handling, sessions, permissions, and billing. Check compatibility in a controlled environment before changing production pipelines. Pin a beta release in CI rather than automatically using the newest version.
- State and privacy: having no hidden local state does not rule out service-side storage. Review Interactions API retention settings, applicable data policies, and uploaded files, especially for confidential documents.
- Availability and limits: Google documents installers or binaries for macOS, Linux, and Windows, but that does not constitute DTech testing every operating-system version. The new client does not provide bidirectional WebSocket sessions for live voice and video; Google points to SDKs and the Live API for that use case.
Does it work in Brazil, and is it free?
Brazil is on Google's official list of regions supported by the Gemini API and Google AI Studio. This establishes regional eligibility for the listed services, not successful beta operation on every account, machine, or configuration. Actual access also depends on the credential, project, requested capability, and account limits.
Installing a CLI and paying for API requests are separate matters. Google provides free and paid tiers for specific API models and features, subject to changing limits and pricing; this does not justify calling all gemini-api usage free. Gemini CLI also has quotas, pricing, and privacy terms tied to the authentication method. An app subscriber should not assume every API-key call is included in the subscription.
Practical choice: use Gemini CLI when you want an agent working directly in the terminal and your project, including in headless mode. Use Gemini API CLI when you need explicit calls for models, file analysis, media generation, or managed agents inside scripts and other agents. Because gemini-api is still beta, verify commands, output formats, and actual access before treating it as a replacement for an existing workflow.
