G

How to Install Gemini CLI on Mac

This guide walks you through installing and configuring Google\'s Gemini CLI on macOS, translated and curated from the original Chinese article provided by Apifox.

1. Prerequisites

  • macOS 10.15 Catalina or newer
  • Node.js 18+ (check with node -v)
  • npm (bundled with Node.js) or Homebrew
  • Stable internet connection

2. Installation Methods

Method A — Run Directly with npx

npx https://github.com/google-gemini/gemini-cli

This one-liner fetches Gemini CLI from GitHub and launches it instantly—no global installation required.

Method B — Global Install via npm (Recommended)

# Standard installation
npm install -g @google/gemini-cli

# Fix permissions if needed
sudo npm install -g @google/gemini-cli

# Apple Silicon
arch -arm64 npm install -g @google/gemini-cli

# Verify
gemini --version

3. First-Time Configuration

  1. Select a theme when prompted.
  2. Choose Login with Google for 60 req/min & 1000/day free quota.
  3. Complete browser authorisation (switch VPN to global mode if the callback fails).

4. Alternative — Use an API Key

Need higher limits? Generate a key in Google AI Studio and set it as an environment variable:

export GEMINI_API_KEY="YOUR_API_KEY"

5. Tips & Tricks

  • Type / in interactive mode to view shortcuts.
  • Use @ to attach local files for context-aware answers.
  • If network is slow, Gemini will auto-switch to the lightweight gemini-2.5-flash model.

6. Troubleshooting

Permission Errors

sudo npm install -g @google/gemini-cli

Node.js Version Issues

brew install node@18

Path Problems

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc

7. Next Steps

Jump into the Getting Started guide or explore the full list of Commands.