Installing Gemini CLI on a Mac and fixing the errors people hit first

Installing Gemini CLI on a Mac takes one command. Getting it to answer a prompt is where people stall: the command is not found, npm refuses to write to a system folder, the sign-in page says the account is not eligible, or the tool installs fine and then stops serving requests. Most install guides were written in 2025 and describe a free sign-in path that no longer works the same way for many accounts. This guide covers the install itself, the account question that now decides whether the tool is usable at all, and the errors that show up first.

Check two things before you install

The official installation page lists the requirements plainly. On a Mac they come down to two things.

macOS 15 or later. The recommended specification names macOS 15+. Older versions may run the Node package, but they are outside what the project tests against.

Node.js 20 or later. Gemini CLI is a Node program. The npm package declares node >=20 as its engine requirement, so an older Node will either refuse to install it or fail at launch. Run node -v first. If the command is missing or reports an older version, install a current Node before anything else.

The page also lists memory guidance: 4GB of RAM for short sessions and common edits, 16GB or more for long sessions on large codebases. The shell can be Bash or Zsh, which covers the default Terminal setup on every recent Mac.

The second check matters more than either of these, and it is about your account rather than your machine. It gets its own section below, because it decides whether installing makes sense at all.

Install with npm, Homebrew, or npx

There are three practical ways to get the gemini command on a Mac, plus MacPorts for those who already use it.

Method	Command	Updates	Notes
npm (global)	npm install -g @google/gemini-cli	npm install -g @google/gemini-cli@latest	Tracks the weekly stable release
Homebrew	brew install gemini-cli	brew upgrade	Formula marked deprecated on 2026-06-18
npx	npx @google/gemini-cli	Fetched on each run	No permanent install
MacPorts	sudo port install gemini-cli	sudo port upgrade	Only if MacPorts is already set up

npm is the method to prefer today. At the time of writing, the npm registry lists version 0.60.0 as the latest release. The Homebrew formula, by contrast, is marked deprecated with the date 2026-06-18, points to an antigravity-cli cask as its replacement, and still sits at version 0.46.0. A Homebrew install therefore gives you a release that is many versions behind. If you installed through Homebrew earlier, brew info gemini-cli will show the deprecation notice.

npx is useful for a quick trial. It downloads and runs the package without leaving a global command behind. It is slower to start and does not help if you plan to use the tool daily.

Release channels exist for npm installs. Stable releases come out weekly and use the latest tag, which is also what you get without a tag. A preview tag carries the next week's release before full validation, and a nightly tag carries everything merged to the main branch that day. Unless a specific fix is only in preview, stay on stable.

Having both installs at once causes confusing behavior. If you installed through Homebrew months ago and later ran the npm install, two copies of gemini exist, and the one that runs is whichever folder comes first in your PATH. Run which -a gemini to list every copy. If two paths appear, remove one with brew uninstall gemini-cli or npm uninstall -g @google/gemini-cli, open a new terminal window, and check gemini --version again. The same check explains the common report that an update "did nothing": the update went to one copy while the shell kept running the other.

After installing, run gemini --version to confirm the command resolves, then run gemini inside a project folder. The first launch asks you to choose an authentication method.

The account question that decides whether it works

This is the part older guides miss. On May 19, 2026, Google announced that it was moving individual users from Gemini CLI to a new tool called Antigravity CLI. The announcement set a date:

On June 18, 2026, Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests for Google AI Pro and Ultra, as well as those using it free of charge using Gemini Code Assist for individuals. Source: developers.googleblog.com

The same announcement states that access stays unchanged for organizations using a Gemini Code Assist Standard or Enterprise license, and that Gemini CLI remains accessible through paid Gemini API keys and Gemini Enterprise Agent Platform API keys. The Gemini CLI documentation site now carries a banner saying that unpaid tier and Google One users were moved to Antigravity CLI on June 18th, 2026.

In practice, this splits readers into two groups.

You can keep using Gemini CLI if your company or school provides a Gemini Code Assist Standard or Enterprise license, if you use Vertex AI through a Google Cloud project, or if you authenticate with a paid Gemini API key from Google AI Studio.

You should look at Antigravity CLI instead if you planned to sign in with a personal Google account, either on the free tier or through a Google AI Pro or Ultra subscription. Installing Gemini CLI will still succeed, but requests from those accounts are no longer served. Google's announcement says Antigravity CLI keeps Agent Skills, Hooks, Subagents, and Extensions (as plugins), while noting that feature parity is not complete. It is distributed from the Antigravity download page, and Homebrew lists it as the antigravity-cli cask, which installs a command named agy.

If you are unsure which group you are in, decide this before spending time on install errors. A perfectly installed CLI that cannot authenticate looks exactly like a broken install.

Signing in and setting keys

Assuming your account is one that Gemini CLI still serves, the first launch offers three routes.

Sign in with Google. This opens a browser, completes the sign-in there, and caches credentials locally. Organization accounts, meaning a company, school, or Google Workspace account, also need a Google Cloud project set:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

Gemini API key. Create a key in Google AI Studio, then export it before launching:

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Choose "Use Gemini API key" at the prompt. To avoid exporting it every time, add the line to ~/.zshrc, keeping in mind that anything in that file is visible to every process you start from the shell. Treat the key like a password.

Vertex AI. Set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, then authenticate with gcloud auth application-default login, a service account JSON file through GOOGLE_APPLICATION_CREDENTIALS, or a Google Cloud API key in GOOGLE_API_KEY. The documentation notes one trap here: if GOOGLE_API_KEY or GEMINI_API_KEY is already set in your shell, you must unset them before the gcloud credential route will be used.

That last point generalizes. Environment variables left over from an earlier experiment are a frequent cause of sign-in failures, and several of the errors below come down to them.

Fixing the first errors

These are the errors the official troubleshooting guide lists for authentication and installation, in the order people tend to hit them on a Mac.

command not found: gemini. The package installed, but the folder npm puts global commands in is not on your PATH. Run npm prefix -g to see where npm installs, and check that its bin folder appears in echo $PATH. If you use a Node version manager, the command only exists under the Node version that was active when you installed it. Switching Node versions makes it disappear until you install it again.

EACCES during npm install -g. npm is trying to write to a folder owned by the system, which happens when Node was installed with the official macOS package. Running the install with sudo works once and causes permission problems later. npm's own documentation recommends reinstalling Node with a version manager, or pointing npm's global prefix at a folder in your home directory, as described on the npm EACCES page.

"You must be a named user on your organization's Gemini Code Assist Standard edition subscription". This appears when GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID is set, which forces an organization subscription check. If you are signing in with an individual account, remove those variables from ~/.zshrc, any .env file, and the current shell.

"Request contains an invalid argument" at sign-in. The troubleshooting guide says this affects some Google Workspace accounts and Google Cloud accounts tied to Gmail. Setting GOOGLE_CLOUD_PROJECT to a project ID, or switching to an API key, gets around it.

"Not currently available in your location". Sign-in with a Google account is limited to supported countries. An API key or Vertex AI route may still work.

unable to get local issuer certificate. A corporate network is inspecting TLS traffic. Set NODE_USE_SYSTEM_CA=1 so Node uses the macOS certificate store, and if that does not help, point NODE_EXTRA_CA_CERTS at the company's root certificate file.

No interactive prompt appears. If any environment variable starting with CI_ is set, the CLI assumes it is running in a CI system and skips interactive mode. Unset the variable for the session.

Where it runs matters as much as how it installs

Gemini CLI works on the folder you start it in. It reads files there, runs commands there, and loads GEMINI.md context files from that location. Starting it in your home folder instead of the project folder gives it the wrong files to reason about, and starting it in a parent folder can pull in context meant for another project. The --include-directories flag adds other folders explicitly when a task spans more than one.

This makes the daily routine less about the install and more about getting to the right folder quickly. On a Mac that usually means finding the project in Finder, opening a terminal, and changing into the same path before launching the agent. A file manager with a built-in terminal removes that step because the terminal opens where the folder already is. The features page shows that layout, and pricing covers what it costs if you want to try it alongside whichever CLI your account supports.

What to do first

Check your account type before installing: if you sign in with a personal Google account, look at Antigravity CLI; if you have an organization license or a paid API key, install Gemini CLI with npm rather than Homebrew and confirm gemini --version resolves. Then launch it from inside a project folder, not your home folder. If you want the folder and the terminal in one window while you do that, Atriens is built around that layout.