How do I install Gemini CLI on macOS

***

Introduction to Gemini CLI

Gemini CLI is a command-line tool developed by Google that allows users to interact with the Gemini AI models directly from the terminal. It supports AI-driven automation, code assistance, querying, and various multimodal capabilities like working with images and PDFs. The CLI serves as an interface for Google's Gemini Pro and Flash models and is designed for developers, prompt engineers, and AI enthusiasts to enhance productivity by integrating AI into everyday command-line workflows.

***

Prerequisites

Before installing Gemini CLI, you need to ensure your macOS system meets certain requirements:

- macOS version: 10.15 Catalina or later is recommended for compatibility and stability.
- Node.js: Version 18 or higher is required since Gemini CLI is a Node.js-based package. The Node.js runtime must be installed and available on your system.
- You can check your Node.js version by running `node -v` in the terminal.
- If Node.js is not installed or outdated, download from nodejs.org or install/manage it using Homebrew or a version manager like nvm.
- npm: Comes bundled with Node.js. It is essential for installing Gemini CLI packages.
- Stable internet connection: Required to download the tool and for authenticating during the setup.
- Some knowledge of working in the terminal is helpful but not mandatory.

***

Installation Methods

There are three standard ways to install and run Gemini CLI on macOS:

1. Run Directly with npx (No Permanent Installation)

This method is the quickest way to try out Gemini CLI without installing it globally on your system. It uses `npx` to fetch the latest version from GitHub and execute it instantly.

Open the terminal and run:

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

This command downloads Gemini CLI temporarily and launches it. It's handy for testing or occasional use but not recommended for regular workflows as each invocation downloads the tool anew.

2. Global Installation Using npm (Recommended)

For regular use, it is best to install Gemini CLI globally so that the `gemini` command is available system-wide.

The command to install globally is:

sudo npm install -g @google/gemini-cli

- The `sudo` prefix is often needed to grant permission to install globally.
- For Apple Silicon Macs (M1, M2 chips), this same command works, but ensure your Node.js installation supports your architecture (arm64).
- After installation, verify by running:

  gemini --version
  

You should see the installed Gemini CLI version printed.

3. Installation Using Homebrew (Alternative)

If you prefer using Homebrew, the popular macOS package manager, Gemini CLI is also available as a package. This is a straightforward method if you already use Homebrew.

Run:

brew install gemini-cli

Homebrew handles dependencies and adds the CLI tool to your path automatically. After installation, typing `gemini` should start the CLI.

***

First-Time Configuration

After installing and running `gemini` for the first time, the CLI will guide you through initial setup:

- Theme Selection: You will be prompted to select a light or dark color theme for the CLI interface.
- Authentication:
- The CLI requires authentication via Google Login to access Gemini AI models.
- When prompted, choose to log in with your Google account.
- A browser window will open for you to authorize the CLI.
- If the callback fails due to network restrictions or VPN, switch VPN to global or open authorization links manually.
- Free Usage Limits:
- Logging in with Google grants you a quota of about 60 requests per minute and 1000 requests per day on Gemini 2.5 Pro.
- This is suitable for most personal and development uses.

***

Using an API Key for Higher Limits

For users who need higher request limits or want to automate usage without interactive login, using an API key is recommended.

Steps:

- Generate an API key via Google AI Studio (console for Google AI).
- Export this key as an environment variable by adding the following line to your shell config file (`~/.zshrc`, `~/.bash_profile`, etc.):

export GEMINI_API_KEY="YOUR_API_KEY"

- Reload your shell or source the file:

source ~/.zshrc

- Now Gemini CLI will use this key automatically when making requests.

This approach unlocks higher usage quotas depending on your API key permissions and is favored in production or automated scripting environments.

***

How to Use Gemini CLI

After installation and authentication, start the CLI by typing:

gemini

Some useful commands and features:

- Interactive prompt that accepts natural language commands and code queries.
- Use `/` inside the CLI to view available shortcuts and commands.
- Use `@` to attach files (like images or documents) to get context-aware AI responses.
- The CLI can switch between models (e.g., Gemini Pro or lightweight Gemini Flash) automatically based on network conditions.

***

Troubleshooting Common Issues

Permission Errors during Installation

If `npm install -g` fails due to permission errors:

- Try again using `sudo`:

sudo npm install -g @google/gemini-cli

- Alternatively, fix npm permissions or set up a local npm global directory.

Node.js Version Issues

If your Node.js version is too old:

- Use Homebrew to upgrade Node.js:

brew install node@18

- Or install Node.js from the official website or use nvm to manage Node.js versions.

PATH Not Found for gemini Command

If after installation the terminal doesn't recognize `gemini`:

- Add npm global bin to your PATH:

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

- Or open a new terminal window to reload environment variables.

***

Advanced Features & Tips

- Gemini CLI runs a ReAct agent loop internally, allowing it to decide when to run shell commands, web search, or directly answer from AI.
- It integrates well with developer workflows such as reading/writing files, running Git commands, or fetching pull requests.
- The CLI supports multimodal inputs like images and PDFs for app prototyping or content generation.
- It can interact with external servers for generating images or summarizing documents.
- Shortcuts like `/` and `@` speed up usage during interactive sessions.

***

Security and Privacy

- Authentication tokens and API keys are stored locally for convenience but ensure your `.zshrc` or environment files are secured.
- The Gemini CLI accesses your Google account for authentication only with your consent.
- For enterprise or Google Workspace users, additional authentication methods like OAuth2 or service accounts may be available. Check official documentation for corporate use cases.

***

Next Steps After Installation

Once installed and configured, explore Gemini CLI capabilities with these steps:

- Run simple queries and coding questions from the CLI.
- Use Gemini to generate or debug code snippets in various programming languages.
- Attach local project files and ask for code reviews or documentation summaries.
- Automate routine shell tasks with AI guidance.
- Try connecting Gemini CLI to model context protocol (MCP) servers for custom AI model execution.
- Explore integration with image generation tools provided via MCP for multimodal AI projects.

***

Summary

To summarize the installation of Gemini CLI on macOS:

- Ensure macOS 10.15 or newer and Node.js 18+ are installed.
- Choose your preferred installation method: direct run with npx, global npm install with permissions, or Homebrew.
- Authenticate with your Google account or set up an API key for advanced usage.
- Handle common issues like permissions or PATH fixes proactively.
- Leverage the CLI's powerful features to enhance development productivity and automate AI workflows.

This comprehensive approach will ensure a smooth installation and immediate productive use of Gemini CLI on your macOS machine.

***