Gemini CLI Cross-Platform Installation & Configuration (macOS / Linux / Windows)
Zero-error setup guide for the official and community Gemini CLI: macOS Homebrew, Linux one-liners, Windows Winget, and API key environment variable persistence.
Cross-Platform Gemini CLI Installer
scripts/install-gemini-cli.sh
#!/usr/bin/env bash
set -e
echo "==> Detecting operating system and architecture..."
OS="$(uname -s)"
ARCH="$(uname -m)"
case "$OS" in
Darwin)
echo "==> macOS detected. Installing via Homebrew or npm..."
if command -v brew >/dev/null 2>&1; then
brew install gemini-cli
else
npm install -g @google/gemini-cli
fi
;;
Linux)
echo "==> Linux detected. Installing globally via npm..."
npm install -g @google/gemini-cli
;;
*)
echo "==> Please install via Node.js npm: npm install -g @google/gemini-cli"
exit 1
;;
esac
echo "==> Installation complete! Run 'gemini --version' to verify."
Why Use Gemini in Your Terminal?
Command-line interaction with the latest Gemini 4 generation offers huge developer velocity gains:
- Pipeline Data Streams:
cat build.log | gemini -m gemini-4-argon "Diagnose memory fault"yields instant root-cause analysis without context switching. - Terminal Code Generation: Direct complex script creation and vulnerability patching via Gemini 4 Carbon into destination files.
- Multimodal Terminal Inputs: Pass local screenshots, diagrams, and logs directly for UI and stack trace debugging.
- CI/CD Integration: Seamless injection of multi-modal validation or automated PR summaries into deployment pipelines.
Installation by Platform
1. macOS (Homebrew or npm)
macOS developers can install directly via Homebrew or npm:
# Recommended via Homebrew (automatically managed)
brew install gemini-cli
# Or install globally via npm
npm install -g @google/gemini-cli
2. Linux (Ubuntu / Debian / Arch / Fedora)
Ensure Node.js 18+ is available on your machine:
# Ubuntu / Debian prerequisites
sudo apt update && sudo apt install -y nodejs npm curl
# Install Gemini CLI globally
sudo npm install -g @google/gemini-cli
# Verify version
gemini --version
3. Windows 11 / 10 (Winget or PowerShell)
Windows developers can use the Windows Package Manager:
# Install via Winget
winget install Google.GeminiCLI
# Or install via PowerShell with npm
npm install -g @google/gemini-cli
API Key Configuration
Obtain an API key from Google AI Studio and persist it in your shell environment:
macOS / Linux (zsh or bash)
# Append API key to shell configuration
echo 'export GEMINI_API_KEY="AIzaSyYourGeneratedSecretKey"' >> ~/.zshrc
# Reload active shell
source ~/.zshrc
Windows (PowerShell)
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'AIzaSyYourGeneratedSecretKey', 'User')
CLI Flags & Options Matrix
Gemini CLI provides rich runtime flags for automated workflows:
| CLI Flag | Description & Allowed Values | Typical Command Pattern |
|---|---|---|
--model, -m | Model identifier: gemini-4-carbon, gemini-4-argon, gemini-3-flash | gemini -m gemini-4-carbon "Audit repo CVEs" |
--stream | Toggle streaming typing mode (defaults to enabled) | gemini --no-stream "Output raw text payload" |
--format | Output format: markdown (default), json, plain | gemini --format json "Extract metadata" > out.json |
--system | Inject custom system directive prompt | gemini --system "You are a Linux kernel SRE" "Analyze dmesg" |
--image, -i | Path to local image file (PNG, JPG, WebP) | gemini -i screenshot.png "Explain UI overflow bug" |
--temperature | Sampling temperature (0.0 ~ 2.0), default 0.7 | gemini --temperature 0.0 "Write deterministic SQL" |
Multimodal CLI Direct Ingestion
Gemini 4 CLI natively handles local media files without requiring pre-upload:
# 1. Inspect UI visual bug directly from screenshot
gemini --image ./assets/mobile-layout-bug.png "Diagnose why this hero section causes horizontal scroll"
# 2. Transcribe architecture whiteboard into Mermaid syntax
gemini --image ./diagrams/whiteboard.jpg "Convert this architecture sketch into GitHub Mermaid flowchart"
# 3. Audio transcript and action item synthesis
gemini --audio ./standup-recording.mp3 "Summarize top blockers and sprint action items"
Common Shell Pipelines & Interactive Mode
# 1. Quick reasoning query
gemini "Summarize the CAP theorem in 2 sentences"
# 2. Automated Git release notes generation
git log -n 10 --oneline | gemini "Draft concise release notes categorized by feat, fix, and chore"
# 3. Real-time crash diagnostics
dmesg | tail -n 50 | gemini -m gemini-3-flash "Identify any out-of-memory kernel kills or disk I/O errors"
# 4. Interactive REPL Chat session
gemini chat
Troubleshooting & Best Practices
1. Connection Timeouts via Corporate Proxies
If operating behind a VPN or enterprise proxy, configure standard proxy environment variables:
# HTTP / HTTPS Proxy
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
# Socks5 Proxy
export ALL_PROXY="socks5://127.0.0.1:7890"
2. 403 Forbidden: API key not valid
- Ensure
echo $GEMINI_API_KEYoutputs your active key; - Confirm the key was created in Google AI Studio and that Gemini 4 / 3 API access is active on your billing account or free quota.
3. Node.js Version Conflicts (SyntaxError: Unexpected token '?')
The CLI uses modern ECMAScript operators and requires Node.js 18.0.0 or higher. Update via nvm:
nvm install --lts && nvm use --lts