Getting Started Tutorial
A comprehensive beginner's guide to mastering Gemini CLI from installation to advanced usage.
What You'll Learn
This tutorial takes you from zero to a fully working Gemini CLI setup in about 20 minutes. By the end you will be able to run natural-language prompts against any file or directory on your machine, configure multiple Gemini models, and integrate the tool into your existing development workflow.
Each step builds on the previous one, so work through them in order the first time. Later you can jump to any section as a reference. All commands are shown for macOS/Linux; Windows equivalents are noted where they differ.
- • How to install Gemini CLI on macOS, Linux, and Windows
- • How to generate and configure a Google AI API key
- • How to run your first prompt and understand the output
- • The most useful everyday commands and flags
- • How to unlock advanced features like MCP integration
Prerequisites
Before you start, make sure the following are available on your system. If anything is missing, follow the linked setup guides.
Gemini CLI is distributed as an npm package and requires Node.js 18 or later. Run node --version to verify. If you do not have Node.js, download it from nodejs.org or use a version manager like nvm.
You need a Google account to create a free API key at Google AI Studio (aistudio.google.com). No credit card is required for the free tier.
Any Unix-compatible terminal works: Terminal.app on macOS, bash or zsh on Linux, Git Bash or WSL on Windows. PowerShell is also supported.
Tutorial Steps
Installation
Install Gemini CLI globally so it is available from any directory. The command is the same on macOS, Linux, and Windows (with npm in your PATH):
npm install -g @google/gemini-cli
gemini --version
If npm install -g fails with a permissions error on macOS or Linux, you have two good options: fix npm global directory permissions by changing the prefix to a user-writable folder, or prefix the command with sudo. The preferred approach is the former — it avoids running npm as root.
API Configuration
Gemini CLI needs a Google AI API key to send requests. Visit aistudio.google.com, sign in with your Google account, and click "Get API key" in the left sidebar. Copy the generated key — you will not be able to see it again after you close the dialog.
The safest way to supply the key is via an environment variable. Add the following export to your shell profile so it is set automatically for every session:
# Add to ~/.bashrc, ~/.zshrc, or equivalent
export GEMINI_API_KEY="AIza...your_key..."
# Reload the profile
source ~/.zshrc
Alternatively, run gemini auth and follow the interactive prompt. Gemini CLI will store the key in its config directory at ~/.gemini/.
First Command
With installation and authentication complete, try the simplest possible invocation — a plain text prompt with no file input:
gemini "What is the Gemini CLI and what can it do?"
Gemini will stream a response directly to your terminal. The first response may take two to three seconds while a cold connection is established; subsequent requests in the same session are much faster.
Now try reading a local file by piping it as stdin. Navigate to any project directory and run:
gemini "Summarize what this file does" < README.md
You can also pass a directory path and Gemini CLI will recursively include all relevant files up to the configured context limit.
More first-command examples →Basic Usage
The three patterns you will use most often are: (1) prompting with a file as input, (2) writing output to a new file, and (3) using the interactive REPL mode for multi-turn conversations.
# 1. Review a file and save feedback
gemini "Review this code for bugs and suggest improvements" < app.js > review.md
# 2. Interactive multi-turn chat
gemini chat
# 3. Use a specific model
gemini --model gemini-2.0-pro "Explain this algorithm" < sort.py
Use the --model flag to pick a different Gemini model. Free-tier users typically use gemini-2.0-flash, which is fast and cost-efficient. Switch togemini-2.0-pro for tasks that need deeper reasoning.
Advanced Features
Once you are comfortable with the basics, two features unlock a significant productivity leap: Model Context Protocol (MCP) integration and shell scripting.
MCP servers extend Gemini CLI with new tools — filesystem access, database queries, web search, and more — that Gemini can invoke autonomously while answering your prompts. Setting up your first MCP server takes about five minutes:
npm install -g @modelcontextprotocol/server-filesystem
gemini mcp add filesystem npx @modelcontextprotocol/server-filesystem ./
gemini "List all TypeScript files and summarize each one"
Shell scripting lets you automate repetitive prompts — batch processing files, generating reports on a schedule, or running AI-assisted code reviews in CI/CD pipelines.
Advanced features guide →Frequently Asked Questions
Do I need a paid Google account to use Gemini CLI?
No. A free Google AI Studio account provides an API key with generous free-tier limits suitable for personal projects and learning. Paid plans unlock higher rate limits and access to the most powerful Gemini models.
What is the minimum Node.js version required?
Gemini CLI requires Node.js 18 or later. Run node --version to check. If you need to manage multiple Node versions on the same machine, use nvm or fnm.
Can I use Gemini CLI without a terminal?
Gemini CLI is a terminal-first tool, but most modern IDEs expose an integrated terminal. VS Code, JetBrains IDEs, and Neovim all support running Gemini CLI without leaving your coding environment.
How do I update Gemini CLI to the latest version?
Run npm update -g @google/gemini-cli to get the latest stable release. Check the GitHub release notes before upgrading in production environments to review any breaking changes.
What's Next?
Continue your learning journey with more advanced topics: