Install Gemini CLI — Free Version
Your complete, step-by-step guide to getting Google's powerful Gemini CLI up and running on your machine — for free. From prerequisites to your first AI-powered command, we've got every step covered.
Get Started on GitHub
What Is Gemini CLI?
AI in Your Terminal
Gemini CLI brings Google's Gemini AI model directly into your command-line environment. Interact with powerful AI — ask questions, generate code, analyse files — without ever leaving your terminal.
It's open-source, free to use with a Google account, and runs on macOS, Windows, and Linux.
What You Can Do
  • Chat with Gemini directly from the terminal
  • Generate and debug code on the fly
  • Analyse local files and directories
  • Run agentic tasks and multi-step workflows
  • Integrate with shell scripts and pipelines
Prerequisites Overview
Before installing Gemini CLI, make sure your system meets these requirements. The setup is lightweight — you likely already have most of these in place.
Node.js
Version 18 or higher required. Node.js powers the CLI runtime.
npm or npx
Comes bundled with Node.js. Used to run and install the CLI package.
Google Account
A free Google account is all you need to authenticate and access Gemini.
Internet Connection
Required for authentication and sending prompts to the Gemini API.
Step 1 — Check Your Node.js Version
Open your terminal and verify that Node.js version 18 or higher is installed. This is the single most important prerequisite before proceeding.
node --version
# Expected output: v18.0.0 or higher
# e.g. v20.11.0

If Node.js is not installed or your version is below 18, head to nodejs.org and download the latest LTS release before continuing.
Installing Node.js (If Needed)
1
Visit nodejs.org
Go to https://nodejs.org and download the LTS (Long Term Support) version — this is the recommended stable release for most users.
2
Run the Installer
Launch the downloaded installer and follow the on-screen prompts. Accept the default settings — they're suitable for most use cases.
3
Verify Installation
Close and reopen your terminal, then run node --version and npm --version to confirm both are installed correctly.
Quick Install
Step 2 — Run Gemini CLI with npx
The fastest way to launch Gemini CLI is using npx — no global install required. This runs the latest version of the CLI directly without permanently installing it on your machine.
npx https://github.com/google-gemini/gemini-cli
On first run, npx will download the necessary packages automatically. You'll see a brief download progress bar, after which the CLI will launch.

This is the recommended approach for trying Gemini CLI for the first time. It keeps your system clean and always uses the latest version.
Step 3 — Install Globally (Optional)
If you plan to use Gemini CLI regularly, installing it globally means you can launch it from anywhere with a single command. This is ideal for developers who want seamless day-to-day access.
npm install -g @google/gemini-cli
After installation completes, verify the global install was successful:
gemini --version

Global installs require write access to your npm global directory. On macOS/Linux, you may need to prefix the command with sudo depending on your setup.
npx vs. Global Install — Which Should You Choose?
Use npx (No Install)
  • No permanent files added to your system
  • Always fetches the latest version
  • Ideal for first-time users and quick trials
  • Slightly slower to start (downloads each time)
Use Global Install
  • Launches instantly from any directory
  • No internet needed to start (already cached)
  • Best for daily use and scripting
  • Requires manual updates with npm update -g
Authentication
Step 4 — Sign In with Your Google Account
When you launch Gemini CLI for the first time, it will prompt you to authenticate. This links the CLI to your free Google account and grants access to the Gemini API via the free tier.
The CLI will open a browser window automatically. Simply sign in with your existing Google account — no billing information or credit card is required for the free tier.
Authentication — Step by Step
The entire authentication process takes under 60 seconds. Once authorised, your credentials are cached locally so you won't need to sign in again on future sessions.
Step 5 — Choose Your Login Method
When Gemini CLI first launches, it will ask you to choose how you'd like to authenticate. There are two supported options:
Login with Google (Recommended)
The simplest option. Uses your Google account via OAuth. No API key needed. Perfect for individual users on the free tier. Select this option and follow the browser prompts.
Use an API Key
For advanced users or CI/CD pipelines. Generate a free Gemini API key from Google AI Studio at aistudio.google.com, then paste it when prompted in the terminal.

For most users getting started, Login with Google is the easiest and fastest path. You can always switch to an API key later.
Generating a Free API Key (If Needed)
01
Go to Google AI Studio
Visit aistudio.google.com and sign in with your Google account.
02
Click "Get API Key"
In the left sidebar, click Get API Key, then Create API Key.
03
Copy Your Key
Copy the generated key and store it safely — you won't be able to view it again.
04
Paste into CLI
When the CLI prompts for an API key, paste your key and press Enter.
Free Tier — What's Included?
Gemini CLI's free tier is surprisingly generous. Here's what you get with a standard Google account — no payment required.
1M
Tokens per Minute
Up to 1 million tokens per minute on the free tier with Gemini 1.5 Pro.
1,500
Requests per Day
1,500 free API requests per day — more than enough for most developers.
$0
Cost to Start
Zero cost. No credit card. No billing setup required to use the free tier.
First Launch
Step 6 — Launch the CLI
Once authenticated, you're ready to start using Gemini CLI. Launch it with one of the following commands depending on how you installed it:
# If using npx:
npx https://github.com/google-gemini/gemini-cli

# If installed globally:
gemini
The CLI will load and display a welcome prompt. You're now inside an interactive session with Gemini — type any question or command to begin.
Your First Commands — Try These!
Not sure where to start? Here are some great first prompts to explore the power of Gemini CLI right away.
Ask a Question
What are the benefits of using TypeScript over JavaScript?
Generate Code
Write a Python function that reverses a linked list
Analyse a File
Summarise the contents of README.md
Explain an Error
Explain this error: TypeError: Cannot read properties of undefined
Step 7 — Explore the CLI Interface
Gemini CLI features an intuitive interactive interface. Once inside a session, you can type prompts naturally — just as you would in a chat. The CLI supports multi-line input, file references, and special slash commands.
Slash Commands
  • /help — View all available commands
  • /clear — Clear the current conversation
  • /quit or /exit — Exit the CLI
  • /model — Switch between Gemini models
Keyboard Shortcuts
  • Enter — Submit your prompt
  • Shift + Enter — New line (multi-line input)
  • Ctrl + C — Cancel current response
  • Up Arrow — Recall previous prompt
Step 8 — Pass Prompts Directly from the Shell
Gemini CLI isn't limited to interactive mode. You can pass prompts directly as command-line arguments — perfect for scripting, automation, and one-off queries without entering an interactive session.
# One-shot prompt:
gemini "Explain the difference between REST and GraphQL"

# Pipe file contents into Gemini:
cat server.js | gemini "Review this code for bugs"

# Summarise a file:
gemini -p "Summarise this document" < report.txt

This non-interactive mode makes Gemini CLI incredibly powerful for shell scripts, CI pipelines, and automated workflows.
Step 9 — Set Your API Key as an Environment Variable
If you're using an API key instead of Google login, it's best practice to store it as an environment variable rather than pasting it each session. This keeps your key secure and makes it available automatically.
# macOS / Linux — add to ~/.bashrc or ~/.zshrc:
export GEMINI_API_KEY="your-api-key-here"

# Windows (Command Prompt):
setx GEMINI_API_KEY "your-api-key-here"

# Windows (PowerShell):
$env:GEMINI_API_KEY = "your-api-key-here"

Never commit your API key to a public repository. Add .env to your .gitignore file if storing keys in a project directory.
Step 10 — Update Gemini CLI
Keeping Gemini CLI up to date ensures you have the latest features, bug fixes, and model improvements. Here's how to update depending on your installation method.
Using npx
No action needed! npx always fetches the latest version automatically each time you run it.
npx https://github.com/google-gemini/gemini-cli
Global Install
Run the update command to pull the latest version to your global npm registry.
npm update -g @google/gemini-cli
Check Current Version
Verify which version you're currently running at any time.
gemini --version
Troubleshooting — Common Issues
Running into issues? Here are the most common problems users encounter during setup, and how to resolve them quickly.
❌ "node: command not found"
Node.js is not installed or not on your PATH. Download it from nodejs.org and reinstall, or add Node to your system PATH manually.
❌ "permission denied" on npm install -g
On macOS/Linux, prefix with sudo: sudo npm install -g @google/gemini-cli. Alternatively, configure npm to use a local directory.
❌ Authentication loop or browser doesn't open
Try running gemini auth logout then gemini auth login again. Ensure pop-ups are not blocked in your browser.
❌ "API key invalid" error
Double-check that your key was copied correctly with no extra spaces. Regenerate a new key from Google AI Studio if needed.
Troubleshooting — Network & Rate Limit Issues
Rate Limit Exceeded (429 Error)
You've hit the free tier limit. Wait a few minutes before retrying, or space out your requests. The limit resets every minute (requests per minute) and daily (requests per day).
Timeout or No Response
Check your internet connection. Long or complex prompts may take more time — try breaking them into smaller, more focused requests if the timeout persists.
Proxy or Firewall Blocking Requests
If you're on a corporate network, the Gemini API endpoint may be blocked. Configure your npm proxy settings or contact your network administrator.
Platform-Specific Notes
macOS
Use Terminal or iTerm2. Node.js is best installed via Homebrew: brew install node. Works seamlessly on both Intel and Apple Silicon (M1/M2/M3).
Windows
Use PowerShell or Windows Terminal. Download Node.js from nodejs.org. For the best experience, consider using WSL2 (Windows Subsystem for Linux).
Linux
Install Node.js via your package manager: sudo apt install nodejs npm on Ubuntu/Debian, or sudo dnf install nodejs on Fedora. Use nvm for version management.
Advanced Usage — Agentic Mode
Gemini CLI supports agentic mode — where Gemini can autonomously execute multi-step tasks on your behalf, including reading files, running shell commands, and iterating on code.
Agentic tasks are triggered naturally through your prompts. For example:
gemini "Audit my project directory for security vulnerabilities and suggest fixes"

gemini "Refactor all .js files in /src to use async/await instead of callbacks"

Agentic mode can execute shell commands on your system. Always review what actions Gemini intends to take before confirming in sensitive environments.
Gemini CLI vs. Other AI CLI Tools
Wondering how Gemini CLI stacks up against the competition? Here's a quick comparison of the most popular AI command-line tools available today.
You're All Set!
Installation Complete 🎉
Congratulations — you've successfully installed and configured Gemini CLI! You now have access to one of the most capable AI models available, right from your terminal.
📚 Documentation
Explore the full docs at github.com/google-gemini/gemini-cli for advanced configuration and features.
🤖 AI Studio
Visit aistudio.google.com to manage your API keys, view usage, and explore Gemini models.
💬 Community
Join the discussion on GitHub Issues and the Google AI Developer Forum to get help and share tips.