Setup & First Run

By the end of this module you will have Gemini CLI installed, authenticated, and producing useful analysis on a real codebase. We are not going to use a "hello world" example — we're going to use TaskFlow, the project you'll work with throughout this entire course.

What We're Building

The reference project for this course is TaskFlow — a task management REST API built with FastAPIA modern Python web framework for building REST APIs. Automatically generates interactive API documentation at /docs. Fast because it uses async I/O and Pydantic for validation. and SQLiteA lightweight file-based SQL database. No separate server needed — the database is stored in a single .db file. Perfect for development and small applications.. Here's what you'll be working with:

TaskFlow has 11 API endpoints, JWT authentication, SQLAlchemy ORM, Pydantic v2 validation, and a test suite. It is complex enough to be a realistic teaching tool but small enough to understand completely. You'll use Gemini CLI to explore it, extend it, test it, and eventually deploy it.

Install Gemini CLI

# Check Node.js version (need 18+)
node --version

# If not installed, use WinGet (Windows 11 / Windows 10 with App Installer)
winget install OpenJS.NodeJS.LTS

# Alternative: download from https://nodejs.org/en/download/

# Fix execution policy (one-time setup, run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install Gemini CLI globally
npm install -g @google/gemini-cli

# Verify installation
gemini --version

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js LTS
brew install node

# Install Gemini CLI globally
npm install -g @google/gemini-cli

# Verify
gemini --version

# Install Node.js via NodeSource (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fix npm global permissions (avoid sudo npm install)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install Gemini CLI
npm install -g @google/gemini-cli

# Verify
gemini --version

Authenticate

Gemini CLI offers two authentication paths. For this course we use the Google account (OAuth) path — it gives you the free tier without a credit card.

gemini auth login
# Opens browser → Sign in with Google → Authorize → Done
# Token stored in ~/.gemini/credentials (Linux/macOS) or %APPDATA%\gemini\credentials (Windows)

# Get API key from https://aistudio.google.com/app/apikey
# Set as environment variable (add to your PowerShell profile for persistence)
$env:GEMINI_API_KEY = "AIza..."

# Or set permanently in Windows environment variables:
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY","AIza...","User")

Free Tier Limits

For this course, the free tier is more than sufficient. At 10 req/min and 1,500/day, you can run about 50 full lab sessions without hitting limits.

First Look at TaskFlow

Navigate to the TaskFlow directory and ask Gemini CLI to explain the project. When you run gemini inside a directory that has a GEMINI.md file, it automatically loads that file as context before answering.

cd sample-project\taskflow
gemini "What does this project do?"

cd sample-project/taskflow
gemini "What does this project do?"

Context Loading with @-mentions

Single File: @models.py

# Ask about the Task model using the actual file
gemini "@models.py Explain the Task model and all its fields"

# Ask about authentication by loading the real auth.py
gemini "@auth.py How does get_current_user verify a JWT token?"

gemini "@models.py Explain the Task model and all its fields"
gemini "@auth.py How does get_current_user verify a JWT token?"

Multi-file: Cross-file Analysis

# Compare models and schemas for sync issues
gemini "@models.py @schemas.py Are the Task model fields and Task schema fields in sync? List any mismatches."

# Understand what routes are protected
gemini "@main.py @routers/tasks.py Which routes require authentication and how is it enforced?"

gemini "@models.py @schemas.py Are the Task model fields and Task schema fields in sync? List any mismatches."
gemini "@main.py @routers/tasks.py Which routes require authentication and how is it enforced?"

Headless Mode

# List all API endpoints (no interactive session)
gemini -p "List all API endpoints in @main.py @routers/tasks.py @routers/users.py @routers/tags.py" --no-interactive

# Use output in a PowerShell script
$endpoints = gemini -p "List only the HTTP method and path for each endpoint in @routers/tasks.py" --no-interactive
Write-Output "Found endpoints:`n$endpoints"

# Pipe to a file for documentation
gemini -p "Generate a markdown table of all TaskFlow API endpoints from @main.py" --no-interactive | Out-File -FilePath api-docs.md

# List all API endpoints
gemini -p "List all API endpoints in @main.py @routers/tasks.py @routers/users.py @routers/tags.py" --no-interactive

# Capture in a variable
ENDPOINTS=$(gemini -p "List only the HTTP method and path for each TaskFlow endpoint" --no-interactive)
echo "Found endpoints: $ENDPOINTS"

# Pipe to file
gemini -p "Generate markdown docs for the TaskFlow API from @main.py" --no-interactive > api-docs.md

Rate Limits & Quotas

Handling 429 Errors

When you hit the per-minute limit, Gemini CLI returns a 429 Too Many RequestsAn HTTP status code meaning "you've sent too many requests in a given time period." The server includes a Retry-After header telling you how many seconds to wait. error. Here's how to handle it gracefully:

# PowerShell: retry Gemini CLI with exponential backoff
function Invoke-GeminiWithRetry {
    param([string]$Prompt, [int]$MaxRetries = 3)
    $delay = 10  # seconds
    for ($i = 0; $i -lt $MaxRetries; $i++) {
        $result = gemini -p $Prompt --no-interactive 2>&1
        if ($LASTEXITCODE -eq 0) { return $result }
        if ($result -match "429") {
            Write-Warning "Rate limited. Waiting ${delay}s before retry $($i+1)..."
            Start-Sleep -Seconds $delay
            $delay *= 2  # exponential backoff: 10s -> 20s -> 40s
        } else {
            throw $result
        }
    }
    throw "Max retries exceeded"
}

# Usage
$analysis = Invoke-GeminiWithRetry -Prompt "@routers/tasks.py Explain the create_task endpoint"

Lab: Your First 5 Commands on TaskFlow

Complete all five commands in order. Each one teaches a different Gemini CLI capability using the real TaskFlow codebase. Run these from inside the sample-project/taskflow/ directory.

gemini "What does this project do? Summarize each file in one sentence."

gemini "@models.py What fields does the Task model have? What are the valid priority values?"

gemini "@auth.py @routers/users.py Trace the complete flow from a user calling POST /users/login to receiving a JWT token. Include every function called."

gemini -p "List all 11 TaskFlow API endpoints as: METHOD /path — description" --no-interactive

gemini -p "List all 11 TaskFlow API endpoints as: METHOD /path — description" --no-interactive

gemini "@models.py @schemas.py @routers/tasks.py What would break if I added a required 'status' field to the Task model? List every file that would need changes."

Knowledge Check

Test your understanding of Gemini CLI setup and first commands.