Gemini CLI on a Mac: A Week in the Terminal

What Gemini CLI actually is

It is an open-source AI agent from Google that runs in your shell. Not a chat box that happens to live in a terminal, but an agent with real tools: it can read, write, and edit files, run shell commands, fetch web pages, and ground answers with Google Search. You point it at a project and it works inside that project.

The mental model that helped me: it is closer to a junior pair-programmer sitting at your machine than to a search engine you query. That framing matters for how you use it, which I will get to.

Installing on macOS

You need Node.js 18 or newer. If you already build anything in JavaScript you have it; check with node --version. If not, brew install node handles it.

Then install the CLI globally:

npm install -g @google/gemini-cli

If you would rather not install anything permanently, npx @google/gemini-cli runs it on demand.

Authentication: skip the API key at first

The original advice everyone copies is "go get an API key." You do not need one to start, and for most people you never will.

Run gemini in any project directory and it prompts you to authenticate. Choose Login with Google. That free tier gives you 60 model requests per minute and 1,000 per day, which is more than enough for a normal day of development and costs nothing.

You only want an API key if you are scripting it heavily or hitting those limits. If so, create one in Google AI Studio, then add it to your shell profile (~/.zshrc on a modern Mac):

export GEMINI_API_KEY="your_key_here"

Open a new terminal tab and you are set. You can switch auth methods any time from inside the tool with /auth.

The commands worth knowing

Start it by going to a project and typing gemini. That drops you into an interactive session where the agent can see the folder you are in.

The thing that makes it click is referencing files directly. Inside the session, mention a file with @ and ask about it:

@package.json what are the heaviest dependencies here and which could I drop?

It reads the file itself. No piping, no pasting. You can point it at a whole directory the same way.

For one-off questions without entering the session, use the -p flag:

gemini -p "explain what a debounce function does"

And piping is where it earns its place in a real workflow. My most-used command, hands down:

git diff | gemini -p "write a concise commit message for this diff"

That single line replaced the ten seconds of staring I used to do before every commit. Stack traces work the same way: pipe your failing build output straight in and ask what broke.

A few slash commands earn their keep inside a session: /help lists everything, /chat manages conversation branches, and /auth switches login methods.

Is it worth switching to?

If you live in an editor and a terminal all day, yes, with one caveat. It will not architect your app or replace thinking. What it does is eat the small chores: commit messages, "explain this regex," summarizing a dependency tree, drafting a README section from the actual code. Those chores are exactly the things that fragment your attention, and handing them off keeps me in flow longer than any browser-based assistant has.

The honest limit is the same one that applies to every AI coding tool worth using: it is fast and confident, including when it is wrong, so read what it writes before you ship it. Used that way, it has become the utility I reach for most, somewhere between grep and a colleague.