AG
Gemini & Antigravity v2.6 Agentic Engineering Guide
Gemini 4 Models Quickstart Verified: 2026-10

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.

Author: Google GenAI Evangelist Team • Google GenAI & Antigravity 2.6 Engineering Spec

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:

  1. Pipeline Data Streams: cat build.log | gemini -m gemini-4-argon "Diagnose memory fault" yields instant root-cause analysis without context switching.
  2. Terminal Code Generation: Direct complex script creation and vulnerability patching via Gemini 4 Carbon into destination files.
  3. Multimodal Terminal Inputs: Pass local screenshots, diagrams, and logs directly for UI and stack trace debugging.
  4. 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 FlagDescription & Allowed ValuesTypical Command Pattern
--model, -mModel identifier: gemini-4-carbon, gemini-4-argon, gemini-3-flashgemini -m gemini-4-carbon "Audit repo CVEs"
--streamToggle streaming typing mode (defaults to enabled)gemini --no-stream "Output raw text payload"
--formatOutput format: markdown (default), json, plaingemini --format json "Extract metadata" > out.json
--systemInject custom system directive promptgemini --system "You are a Linux kernel SRE" "Analyze dmesg"
--image, -iPath to local image file (PNG, JPG, WebP)gemini -i screenshot.png "Explain UI overflow bug"
--temperatureSampling temperature (0.0 ~ 2.0), default 0.7gemini --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_KEY outputs 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