Before You Install gemini-api: It Is Not Gemini CLI, and Where I Decided It Belongs

I was reading the release notes from the top when the 10/27 entry stopped me: "Gemini API CLI (gemini-api) arrives in beta." With both "Gemini" and "CLI" in the name, I briefly took it for a new face of the existing Gemini CLI.

I opened the README just to be sure, and found I had it wrong. It is a different tool. I'm glad I noticed before installing it rather than after, and this post is my record of the lines I drew once I'd read the README and the top of the install script.

A caveat first: at the time of writing I have not run gemini-api and made a billed call. What follows is what I could confirm by reading, and what I decided before installing. There are no measured results here.

First, what matters: it is not a coding agent

As the README describes it, gemini-api is a set of single-purpose commands for calling the Gemini Interactions API from a shell. It is a single Go binary, and it keeps no conversation state locally.

Gemini CLI, by contrast, was an agent that talked with you while reading, writing files and running commands. Its personal-account service ended on 6/18, which I covered in the migration plan for the personal-tier shutdown. So installing gemini-api as a "replacement for Gemini CLI" won't give you what you expect.

The README lists generation commands (generate, image, tts, music, video), understanding commands (analyze, transcribe), management commands (agent, files, models, configure, whoami), and environments, credentials, webhooks, triggers. Looking at them, it reads less like a tool for a person and more like a toolbox for agents and CI jobs that can use a shell.

What you can check before installing anything real: dry-run and whoami

As an indie developer who scripts store-listing text and image prep around apps, I can picture where this would help. But I don't want to hand a production key to a beta tool that bills.

So the first thing I plan to try is --dry-run, which stays off the network. According to the README it validates input and prints the resolved HTTP request with credentials redacted, without any network call or keychain read.

# Goal: see what would be sent, before any billing
# No key needs to be configured yet; --dry-run makes no network call
gemini-api generate "Hello from my agent" --dry-run
 
# To learn the shape of a request, write out its JSON Schema
gemini-api image --schema > image-schema.json
 
# A machine-readable map of every flag, default and environment variable
gemini-api --usage > gemini-api-usage.kdl

Why this order? --schema and --usage tell you what can be passed, and --dry-run shows what actually gets built, so most argument mix-ups die before a billed call exists. I haven't seen the exact output on my side yet, so please check it on yours.

When you do set a key, use an environment variable or configure, and confirm which one is active with whoami.

# Key only on a personal workstation
export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api whoami   # shows the active configuration and where the credential came from

The README says the key can also be stored in the OS keychain or in ~/.config/gemini-api/config.yaml. On a shared CI machine I'd rather not persist anything with configure, and pass the key through the environment only.

If it goes into CI, pin the version

The README warns that a beta can break between releases and recommends pinning a specific release in CI and automation.

The top of the install script says GEMINI_VERSION selects the version and GEMINI_INSTALL_DIR the destination. The default is /usr/local/bin, falling back to ~/.local/bin when that isn't writable.

# Goal: install a version you have checked, not "latest", in CI
# 1) Save the script to a file and read it before running it
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh -o install.sh
less install.sh
 
# 2) State the version and destination (replace vX.Y.Z with a value from GitHub Releases)
GEMINI_VERSION="vX.Y.Z" GEMINI_INSTALL_DIR="$HOME/.local/bin" bash install.sh

The one-line curl ... | bash in the README is convenient, but I'd rather save the script and read it first. I don't give a script I haven't read the right to run on my machine, and that holds doubly for a beta tool.

Where I almost misread it: "the CLI keeps no state" is not "nothing is kept"

At first I nearly read "stateless" as "no history is stored anywhere." That was a misreading.

What the README says is only that the CLI keeps no conversation state locally. Server-side interactions and uploaded files have their own retention. And the 10/26 release notes say store is now on by default for the Generate Content API in new paid projects. If you pipe personal data through a script, the setting that matters is on the side you call, not the nature of the CLI.

This connects to my comparison of keeping state on the server versus pruning on the client, in the Interactions API state-management post.

After catching that, I redrew my line: what the CLI forgets and what the server remembers get checked separately. I keep the two apart even for small scripts on my own machine.

Where I'm starting

My current decisions:

• Development with a person present stays with an interactive agent; I don't swap it for gemini-api
• Only one-shot jobs from a shell or CI become candidates for gemini-api
• For a candidate, check the shape with --dry-run and --schema first, and make billed calls only after that
• Before it goes into CI, pin the version and read the install script

I drew a similar role-based split in Gemini CLI versus Claude Code.

Start with a single command on your own machine: gemini-api generate "Hello from my agent" --dry-run, and look at what gets built. That is about the right distance to begin with a beta tool, or so it feels to me right now.