Installation & Authentication

The first thing you do with any CLI tool is get it running. Gemini CLI runs on Node.js and installs through npm, Homebrew, or npx. Authentication is OAuth through your Google account -- no API keys to generate, no secrets to paste. This lesson covers every install path, the single command that verifies everything works, and the common failures you'll hit on each platform.

What you'll learn

• Install through npm (npm install -g @google/gemini-cli), Homebrew (brew install gemini-cli), or run without installing (npx @google/gemini-cli)
• System requirements: macOS 15+, Windows 11 24H2+, or Ubuntu 20.04+, with Node 20+ and 4GB RAM
• First run opens a browser for Google OAuth -- no API key needed
• gemini --version is the single command that confirms install + auth are both working
• Migration note (June 18, 2026): Free tier and Google One users transition to Antigravity CLI. Enterprise users stay on Gemini CLI.

The problem

Installing an AI coding tool usually means configuring providers, generating API keys, and setting environment variables before you even see a prompt. Gemini CLI skips all of that: you install it once, it opens your browser for Google OAuth, and you're coding. The catch is that the install path depends on your OS, and getting the wrong Node version is the most common failure. We'll cover all three install methods and the one command that tells you whether everything is wired up correctly.

Options & when to use each

Install method	Good for	Costs you	When to pick it
npm global (npm install -g @google/gemini-cli)	Any platform with Node.js	Adds a global package to your Node install	You already use Node and want gemini on your PATH permanently
Homebrew (brew install gemini-cli)	macOS users who manage everything through brew	Requires Homebrew; taps may lag behind npm releases	You're on macOS and prefer brew for all CLI tools
npx (no install)	Quick trials, CI/CD, machines you don't control	Slower cold start; no gemini command on PATH	You want to try Gemini CLI once without committing to an install

For this course, use npm global install. It gives you the gemini command everywhere and updates cleanly with npm update -g @google/gemini-cli.

Windows users: if you're on WSL (as this course assumes), install inside WSL, not on the Windows host. Gemini CLI runs on Windows 11 24H2+ natively, but the Linux environment gives you a more consistent terminal experience.

Build it

Step 1: Check your Node version

Gemini CLI requires Node 20 or later. Check what you have:

node --version

If you see v18.x or earlier, upgrade Node. The fastest path on any platform:

# Using nvm (recommended)
nvm install 20
nvm use 20

# Or using fnm
fnm install 20
fnm use 20

Step 2: Install Gemini CLI

Pick one of these three commands:

# Option A: npm global install (recommended)
npm install -g @google/gemini-cli

# Option B: Homebrew (macOS only)
brew install gemini-cli

# Option C: npx (no install, run directly)
npx @google/gemini-cli

The npm install downloads the package and puts the gemini binary on your PATH. On some systems you may need sudo for the global install -- if you hit a permissions error, fix your npm prefix instead:

# Better than sudo: configure npm to use a user-owned prefix
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Step 3: Verify the install

Check the installed version to ensure the binary is accessible on your system path.

gemini --version

You should see a version number like 0.51.0 or higher. If you get command not found, restart your shell:

source ~/.bashrc   # or ~/.zshrc on macOS

Step 4: Authenticate

Run Gemini CLI with no arguments:

gemini

The first run opens your default browser to a Google OAuth consent screen. Sign in with the Google account you want to use. After you approve, the browser redirects back, and Gemini CLI stores the token locally.

If you're on a headless server without a browser, Gemini CLI prints a URL you can open on another machine. Paste the auth code back into the terminal when prompted.

To confirm authentication worked:

# Start a one-shot prompt -- if it responds, you're authenticated
gemini -p "What is the current date? Use only the date command."

If you see a date in the response, Gemini CLI is installed, authenticated, and executing shell commands. You're ready.

Step 5: Release channels

Gemini CLI ships through three channels:

Channel	Update frequency	Install command	When to use
Stable	Weekly	npm install -g @google/gemini-cli@latest	Daily development -- most stable
Preview	Weekly	npm install -g @google/gemini-cli@preview	Testing upcoming features before they hit stable
Nightly	Daily	npm install -g @google/gemini-cli@nightly	Contributing or testing bleeding-edge changes

Stick with stable for this course. Switch to preview or nightly only when you're trying a feature that hasn't landed in stable yet.

What goes wrong

Mistake	How you notice it	The fix
Node version too old (v16 or v18)	npm install fails with engine compatibility errors or Gemini CLI crashes on startup	Upgrade to Node 20+ with nvm install 20 && nvm use 20
gemini: command not found after install	Shell can't find the binary	source ~/.bashrc (or ~/.zshrc). The npm global prefix may not be on PATH for the current session
OAuth browser doesn't open (headless server)	gemini hangs waiting for browser auth	Copy the URL printed in the terminal, open it on another machine, paste the code back
Windows 10 or older macOS	Gemini CLI prints a platform-not-supported error	Upgrade to Windows 11 24H2+ or macOS 15+. On older Windows, install inside WSL2 with Ubuntu 20.04+
Permission denied on npm install -g	EACCES error writing to /usr/local/lib/node_modules	Fix your npm prefix (see Step 2) instead of using sudo, which can cause future permission problems
Wrong Google account signed in	Gemini CLI uses a personal account when you meant to use your work account	Run gemini auth logout (if available) or delete the stored token in ~/.gemini/ and re-run gemini

Confirm it worked

Run this one-shot command. If you see a list of files, Gemini CLI is installed, authenticated, and executing shell commands:

gemini -p "List the 5 largest files in my home directory, sorted by size. Use du and sort, output as plain text." --yolo

The --yolo flag tells Gemini CLI to auto-approve all tool calls -- no confirmation prompts. Without it, Gemini CLI asks "Run this command?" before executing, which is fine for interactive use but annoying for verification.

If the response is a ranked list of actual file paths and sizes (not an error or a refusal), you're set. That's the baseline for every lesson that follows.

Next: The REPL & Your First Task