GeminiCLI.net

How to Install Gemini CLI with npm: Complete 2025 Guide

By Gemini Guides on 8/26/2025

npm is the most popular and recommended way to install Gemini CLI. In this comprehensive guide, we'll walk you through the installation process, troubleshoot common issues, and show you how to get started with Google's powerful AI command-line tool.

🚀 Quick Start: Install Gemini CLI with npm

Prerequisites

  • Node.js (version 18 or higher)
  • npm (comes with Node.js)
  • Google account (for API key)

One-Command Installation

npm install -g @google/gemini-cli

That's it! Gemini CLI is now installed globally on your system.

📋 Detailed Installation Steps

Step 1: Verify Node.js and npm

First, ensure you have the required versions:

node --version  # Should be 18.0.0 or higher
npm --version   # Should be 8.0.0 or higher

Step 2: Install Gemini CLI

npm install -g @google/gemini-cli

What this command does:

  • Downloads the latest version of Gemini CLI
  • Installs it globally (-g flag)
  • Makes the gemini command available system-wide

Step 3: Verify Installation

gemini --version

You should see output like:

@google/gemini-cli/1.0.0 darwin-x64 node-v18.17.0

Step 4: Get Your API Key

  1. Visit Google AI Studio
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Copy the generated key

Step 5: Configure Your API Key

macOS/Linux:

# Add to your shell profile
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
 
# Or for bash users
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows:

# Set environment variable
setx GOOGLE_API_KEY "your-api-key-here"
 
# Restart your terminal or run
refreshenv

Step 6: Test Your Installation

gemini "Hello, Gemini CLI is working!"

🔧 Alternative Installation Methods

Using npx (No Global Installation)

If you prefer not to install globally:

npx @google/gemini-cli "Your prompt here"

Using Yarn

If you prefer Yarn over npm:

yarn global add @google/gemini-cli

Using pnpm

If you use pnpm:

pnpm add -g @google/gemini-cli

🛠️ Troubleshooting Common Issues

Issue 1: Permission Denied Error

Error: EACCES: permission denied

Solution:

# Option 1: Use sudo (macOS/Linux)
sudo npm install -g @google/gemini-cli
 
# Option 2: Change npm default directory (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @google/gemini-cli

Issue 2: Command Not Found

Error: gemini: command not found

Solutions:

# Check if it's installed
npm list -g @google/gemini-cli
 
# Reinstall if needed
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli
 
# Check your PATH
echo $PATH
which gemini

Issue 3: API Key Not Recognized

Error: API key not found

Solutions:

# Check if environment variable is set
echo $GOOGLE_API_KEY
 
# Set it again
export GOOGLE_API_KEY="your-actual-api-key"
 
# Test immediately
gemini "Test"

Issue 4: Network Issues

Error: fetch failed or network error

Solutions:

# Check your internet connection
ping google.com
 
# Try with different DNS
nslookup aistudio.google.com
 
# Use a VPN if needed
# Check firewall settings

📦 Package Information

Current Version

npm view @google/gemini-cli version

Package Details

  • Package name: @google/gemini-cli
  • Publisher: Google
  • License: Apache-2.0
  • Repository: GitHub

Dependencies

npm view @google/gemini-cli dependencies

🔄 Updating Gemini CLI

Check for Updates

npm outdated -g @google/gemini-cli

Update to Latest Version

npm update -g @google/gemini-cli

Install Specific Version

npm install -g @google/gemini-cli@1.0.0

🎯 Best Practices

1. Use Global Installation

Global installation is recommended for CLI tools:

npm install -g @google/gemini-cli

2. Keep It Updated

Regular updates ensure you have the latest features and bug fixes:

npm update -g @google/gemini-cli

3. Secure Your API Key

Never commit your API key to version control:

# Good: Use environment variables
export GOOGLE_API_KEY="your-key"
 
# Bad: Hardcode in scripts
gemini --key="your-key" "prompt"

4. Use Version Control

For projects, consider using a .nvmrc file:

# .nvmrc
18.17.0

🚀 Getting Started After Installation

First Commands to Try

# Basic interaction
gemini "What is Gemini CLI?"
 
# File analysis
gemini -f package.json "Explain this package.json file"
 
# Code review
gemini -f src/ "Review this code for potential issues"
 
# Generate documentation
gemini -f src/ "Generate README documentation for this project"

Integration with Your Workflow

# VS Code integration
# Add to your VS Code tasks.json
{
  "label": "Code Review",
  "type": "shell",
  "command": "gemini",
  "args": ["-f", "${file}", "Review this code for bugs and improvements"],
  "group": "build"
}
 
# Git hooks
# Add to .git/hooks/pre-commit
#!/bin/sh
git diff --cached | gemini "Generate a conventional commit message"

📊 Performance Tips

Optimize for Speed

# Use specific files instead of directories when possible
gemini -f src/main.js "Review this file"
 
# Batch related requests
gemini -f src/ "Review all files for security issues, performance problems, and code quality"

Reduce API Usage

# Use our simulator for testing
# Visit: https://geminicli.net/simulator
 
# Use our prompt generator for optimized commands
# Visit: https://geminicli.net/prompt-generator

🔍 Advanced Configuration

Custom Configuration File

Create ~/.gemini/config.json:

{
  "model": "gemini-2.5-pro",
  "temperature": 0.7,
  "maxTokens": 4096
}

Environment Variables

# Set default model
export GEMINI_MODEL="gemini-2.5-pro"
 
# Set temperature
export GEMINI_TEMPERATURE="0.7"
 
# Set max tokens
export GEMINI_MAX_TOKENS="4096"

🎉 Conclusion

Installing Gemini CLI with npm is straightforward and reliable. The global installation makes it available system-wide, and the official Google package ensures you're getting the latest features and security updates.

Key takeaways:

  • Use npm install -g @google/gemini-cli for installation
  • Set your API key as an environment variable
  • Keep the package updated regularly
  • Use our free tools to optimize your workflow

Ready to start? Try our online simulator to experience Gemini CLI without installation, or follow our interactive installation guide for step-by-step instructions.

Need help? Check out our FAQ for common questions, or join our community for support.

Share this article: