Gemini CLI FAQ & Answers

Gemini CLI is Google's Apache 2.0 open-source AI agent (github.com/google-gemini/gemini-cli) that brings Gemini models directly into your terminal. Available models (2025): (1) Gemini 2.5 Pro - highest reasoning, 5 RPM, 100 requests/day free tier, (2) Gemini 2.5 Flash - balanced speed/quality, 10 RPM, 250 requests/day free tier. Both have 1M token context window (2M coming soon). Architecture: ReAct (reason and act) loop where AI reasons through problems and takes appropriate actions using available tools. Built-in tools: (1) Google Search grounding for real-time web data, (2) File operations (read/write local files), (3) Shell command execution, (4) Web fetching (HTTP requests), (5) Model Context Protocol (MCP) support for 200+ custom integrations (GitHub, Slack, PostgreSQL, Jira). Multimodal capabilities: process text, images, PDFs, audio, video inputs. Interactive commands support (October 2025 update): run complex terminal programs directly (vim editor, top monitor, git rebase -i). Installation: npm install -g @google/generative-ai-cli. Authentication: personal Google account (free tier) or Google Cloud project (paid tier with 300 RPM). Use cases: code analysis across massive codebases, documentation generation (OpenAPI specs), automated workflows (CI/CD integration), debugging with context, data processing pipelines. Commercial usage permitted on free tier (unlike competitors). Open source allows code inspection for security verification. Production-ready as of March 2025 (Gemini 2.5 Pro release).

GitHub Actions integration (2025) transforms CI/CD with AI-powered code analysis at 100+ repos/month in production. Setup: (1) Store API key in GitHub Secrets as GEMINI_API_KEY (Settings → Secrets → Actions). (2) Install in workflow via actions/setup-node with npm install -g @google/generative-ai-cli (25-40s install time). (3) Authenticate with gemini config set --api-key command using secrets.GEMINI_API_KEY reference. Production use cases: (1) PR analysis - Gemini reviews git diff output, suggests improvements (security issues, performance bottlenecks, best practices violations), posts findings as PR comments via GitHub API using GITHUB_TOKEN. (2) Automated documentation - generates API docs in OpenAPI 3.1 format from TypeScript interfaces, commits to docs/ folder. (3) Test generation - creates Jest/Vitest tests with >85% coverage for new functions, validates tests compile before committing. (4) Security scanning - detects OWASP Top 10 vulnerabilities (SQL injection, XSS, CSRF), secret exposure (API keys, passwords), insecure dependencies beyond Dependabot. Workflow structure: trigger on pull_request events (types: opened, synchronize), runs-on ubuntu-latest (fastest GitHub-hosted runner), steps include actions/checkout@v4, install Gemini CLI, fetch PR diff with gh pr diff command, analyze with gemini --output-format json for structured parsing, post comments using octokit/request-action. Advanced patterns: (1) Multi-step analysis - chain security scan → performance review → documentation check in sequence. (2) Parallel execution - run Gemini analysis concurrently with Jest tests, ESLint, TypeScript compiler (saves 30-45s vs sequential). (3) Conditional execution - only analyze changed files using git diff --name-only filtering (reduces token usage 70% for large repos). (4) Result caching - cache Gemini responses in GitHub Actions cache, rerun only if files changed (90% cache hit rate for PRs with minor updates). (5) Custom reporters - parse JSON output, generate HTML reports with syntax highlighting, upload as workflow artifacts. (6) Fail on critical issues - exit code 1 if Gemini detects security vulnerabilities rated critical/high severity. Performance metrics (2025 production data): Typical analysis 8-20 seconds for PRs with <500 lines changed, 30-60 seconds for >1K lines. Token usage averages 5K-15K tokens per PR (costs $0.02-0.06 at Gemini 2.0 Flash pricing). Rate limits: 60 requests/minute with free Google account sufficient for CI (most PRs trigger 1-3 Gemini calls), paid tier 360 requests/minute for high-volume repos (>50 PRs/day). Limitations: Complex multi-file refactors may exceed 1M context window (split analysis by file/module). API latency variability 2-10 seconds affects total workflow time. Tool calls (file reading, git operations) count toward rate limits. Best practices (battle-tested 2025): (1) Non-blocking analysis - run as informational check, don't fail builds on Gemini output (avoids false positive blocking). Allow manual override. (2) Smart filtering - exclude vendor/, node_modules/, test fixtures from analysis (reduces noise 80%). (3) Incremental analysis - analyze only git diff, not entire codebase (10x faster). (4) Structured prompts - provide explicit analysis criteria in GEMINI.md (OWASP checklist, performance thresholds), ensures consistent results. (5) Token optimization - summarize large diffs (>10K lines) before sending to Gemini, reduces costs 60%. (6) Error handling - retry with exponential backoff on rate limit errors (429 status), timeout after 5 minutes to prevent workflow hangs. (7) Security - never log API keys, use read-only GITHUB_TOKEN permissions (contents: read, pull-requests: write), audit third-party actions. (8) Monitoring - track Gemini API usage in Google Cloud Console, set budget alerts at $50/month threshold. Integration with traditional CI: Run Gemini in parallel with ESLint (code style), SonarQube (security), Playwright (E2E tests). Gemini complements static analysis with contextual understanding (detects logic bugs, architectural issues static tools miss). Combine results in single PR comment using GitHub Checks API. Cost optimization: Use Gemini 2.0 Flash ($0.075 per 1M input tokens, 50% cheaper than Pro) for routine analysis, switch to Gemini 1.5 Pro only for complex architectural reviews. Enable output caching (60% cost reduction for repeated prompts). Real-world examples: Analyze React components for accessibility issues (WCAG 2.1 AA compliance), detect N+1 query patterns in GraphQL resolvers, validate API contract changes match OpenAPI spec, check commit messages follow Conventional Commits format. Common pitfalls: (1) Blocking builds on Gemini failures (API outages break deployments, use advisory mode). (2) Analyzing entire codebase on every PR (expensive, slow, analyze diffs only). (3) Not rate limiting parallel workflows (10 concurrent PRs = 10x rate limit consumption, implement queue). (4) Missing error handling (API timeouts fail workflow silently, add explicit retries). Essential for scaling code quality reviews beyond human capacity (100+ PRs/week reviewed by AI).

MCP (Model Context Protocol) integration enables extending Gemini CLI with 200+ third-party tools and custom enterprise systems (2025 ecosystem). Configuration: Define servers in ~/.gemini/settings.json with server name, command (npx/node/python), args array, and environment variables. Example GitHub integration: mcp.servers.github object with command npx, args array containing -y and @modelcontextprotocol/server-github, env object with GITHUB_TOKEN set to personal access token (requires repo, read:org scopes). Gemini CLI automatically discovers available tools from all configured servers at startup (tool discovery: 200-500ms for 5 servers). Production MCP servers (2025): (1) GitHub - manage repositories (create/list repos), issues (search/create/update), pull requests (review/comment/merge), workflow runs. (2) Slack - send messages to channels, read conversation history, upload files, manage users. Requires Bot Token with chat:write, channels:read scopes. (3) Brave Search - real-time web search with current data (alternative to Google Search grounding), returns top 20 results with snippets. (4) PostgreSQL/MySQL - execute SELECT queries (read-only recommended), schema introspection, table metadata. Connection string in env.DATABASE_URL. (5) Filesystem - read/write local files beyond built-in file tools, watch directories, glob patterns. (6) Jira - query issues, create tickets, update status, add comments. (7) Confluence - search documentation, create/update pages. (8) Stripe - query customers, invoices, subscriptions (read-only for safety). Custom MCP server development: Implement MCP 2025-03-26 protocol specification with three core methods: (1) initialize - return server capabilities and protocol version. (2) tools/list - expose available tools with name, description, JSON schema for parameters. (3) tools/call - execute tool with validated parameters, return structured results. Implementation languages: TypeScript/JavaScript (official @modelcontextprotocol/sdk), Python (mcp package), Go (community mcp-go). Example custom tool definition: tool named query_crm with description Query customer data from internal CRM, parameters schema with customer_id (string, required) and fields (array of strings, optional), returns JSON with customer object containing name, email, account_status, total_value. Server responds to tools/call by validating customer_id format, querying internal CRM API with authentication, returning structured customer data. Benefits of MCP architecture: (1) Standardization - same server works with Gemini CLI, Claude Desktop, future MCP clients (write once, use everywhere). (2) Security - servers run as separate processes with explicit permissions, can't access Gemini context without requests. (3) Composability - combine multiple servers (GitHub + Jira + Slack for complete DevOps workflow). (4) Ecosystem - 200+ community servers at modelcontextprotocol.io/servers (Notion, Linear, Figma, Airtable, Shopify). Production use cases (real-world 2025): (1) DevOps automation - query GitHub for open issues, create Jira tickets for critical bugs, notify Slack channels, all in single Gemini conversation. (2) Customer support - search Confluence docs, query Stripe for customer subscriptions, check Sentry for errors, draft response email. (3) Data analysis - query PostgreSQL production database, run pandas analysis in Python subprocess, generate charts, export to Google Sheets via API. (4) Content management - fetch Contentful entries, analyze with Gemini, update metadata, trigger Netlify deploy via webhook. Security best practices (enterprise 2025): (1) Read-only by default - MCP servers should expose read operations (query, search, get) without authentication for most tools, require explicit confirmation for write operations (create, update, delete). Implement confirmation prompts: tool returns needs_confirmation: true, Gemini asks user before proceeding. (2) Credential management - store API keys in environment variables, use secret managers (1Password CLI, AWS Secrets Manager), rotate tokens quarterly, never commit credentials to settings.json (use env vars with ${GITHUB_TOKEN} references). (3) Input validation - sanitize all tool parameters (SQL injection prevention: parameterized queries only, XSS prevention: escape HTML in outputs), rate limit tool calls (max 10/minute per tool prevents runaway automation). (4) Audit logging - log all tool invocations with timestamp, user, parameters, result status to SIEM (Splunk, Datadog). (5) Least privilege - MCP server runs with minimal permissions (database user with SELECT only, GitHub token with read:repo not write:repo). (6) Network isolation - run untrusted MCP servers in Docker containers with restricted network access (--network none for local-only tools). Performance considerations: Tool calls count toward Gemini API rate limits (60/minute free tier, each MCP tool invocation = 1 request). Multi-step workflows consuming 5-10 tool calls complete in 10-30 seconds (250-500ms per tool invocation latency). Optimize by batching requests (single query_multiple_customers tool vs looping query_customer). MCP server startup adds 100-300ms to Gemini CLI launch (servers initialize in parallel). Common pitfalls: (1) Not handling errors - MCP server crashes break Gemini workflow, implement try-catch, return error objects with helpful messages. (2) Synchronous blocking - long-running tools (database queries >5s) should be async, return progress updates. (3) Missing descriptions - vague tool descriptions confuse AI (Bad: Get data. Good: Query customer data from CRM by customer_id, returns name, email, account status). (4) Over-permissioning - granting admin/write access when read-only sufficient (violates least privilege). (5) No rate limiting - runaway automation exhausts API quotas (implement circuit breakers). Debugging MCP integrations: Enable debug mode with gemini config set debug true (logs tool discovery, invocations, responses). Check MCP server logs in ~/.gemini/logs/mcp-server-name.log. Test servers independently with npx @modelcontextprotocol/inspector (interactive MCP debugging tool, validates protocol compliance). Monitor with Gemini verbose flag gemini -v (shows tool selection reasoning). Advanced patterns (2025 production): (1) Chained workflows - MCP tools trigger other MCP tools (GitHub webhook → Jira ticket creation → Slack notification cascade). (2) Caching - implement tool-level caching for expensive operations (database query results cached 5 minutes, reduces load 80%). (3) Fallbacks - multiple MCP servers for same functionality (primary PostgreSQL, fallback to read replica if primary down). (4) Context injection - MCP servers can provide context to Gemini (user preferences, company policies) via resources/list endpoint. Ecosystem growth: 50+ new MCP servers published monthly (2025 trend), enterprise adoption at 500+ companies (Stripe, Shopify, Notion using MCP for internal tools). MCP becoming standard protocol for AI-tool integration (similar to REST for web APIs).

GEMINI.md files provide automatic instructional context to Gemini CLI using hierarchical loading system (official docs: google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html). Loading mechanism (2025): CLI searches for GEMINI.md in three locations, concatenates all found files, sends to model with every prompt: (1) Global context - ~/.gemini/GEMINI.md in user home directory, provides default instructions for all projects across your system. (2) Project/ancestor context - scans current working directory and each parent directory up to project root (identified by .git folder), provides context relevant to entire project. (3) Subdirectory context - scans subdirectories below current directory, enables highly specific instructions for particular components/modules. Use cases: (1) Project-specific guidelines - coding standards (ESLint rules, TypeScript strict mode), architecture decisions (REST vs GraphQL rationale, database schema design), team conventions (PR review checklist, commit message format). (2) Repository documentation - API specifications (OpenAPI schemas), database schema (table relationships, indexes), dependency versions (Node.js 20 LTS, React 19). (3) Common tasks - deployment procedures (fly deploy --remote-only), testing commands (npm test -- --coverage), build processes (turbopack vs webpack). (4) Domain knowledge - business rules (pricing logic, user permissions model), terminology (product-specific jargon, acronyms). Example GEMINI.md: # Project Context\n\nNext.js 15 app with TypeScript 5.7, PostgreSQL 16, Tailwind CSS 4.\n\n## Architecture\n- Server Components for data fetching (async/await in RSC)\n- Client Components for interactivity (use client directive)\n- tRPC for type-safe API (zodValidator for input validation)\n\n## Code Standards\n- All database queries use Drizzle ORM prepared statements\n- React components follow composition pattern (no prop drilling >2 levels)\n- Error boundaries wrap async components\n\n## Commands\n- Test: npm test (Vitest with >90% coverage required)\n- Deploy: npm run build && fly deploy --ha=false\n- DB migrations: npm run db:push. Memory management commands (2025): (1) /memory show - displays full concatenated content of current hierarchical memory, inspect exact context being sent to model (useful for debugging unexpected AI behavior). (2) /memory refresh - forces re-scan and reload of all GEMINI.md files from all locations (use after editing context files mid-session). (3) /memory add - appends text to global ~/.gemini/GEMINI.md file, add persistent memories on the fly without manual file editing. Example: /memory add Prefer functional components over class components in React. Modularization with imports (2025): Break large GEMINI.md into smaller files using @file.md syntax, supports relative and absolute paths. Example root GEMINI.md: # Main Project Context\n@./docs/architecture.md\n@./docs/coding-standards.md\n@/home/user/shared/company-guidelines.md. Benefits: maintain separate concerns (architecture vs standards vs workflows), reuse shared guidelines across projects, reduce main GEMINI.md size for easier editing. Benefits: (1) Consistent AI responses - all queries automatically include project context, ensures recommendations align with tech stack/standards (Gemini suggests Drizzle ORM queries not raw SQL if GEMINI.md specifies Drizzle). (2) Eliminates repetition - no need to repeat "This is a Next.js app using TypeScript" in every query, context auto-injected. (3) Team-shareable - commit .gemini/ directory to version control, entire team gets same AI behavior (onboarding: new developers get instant context without reading docs). (4) Hierarchical specificity - root GEMINI.md for project-wide rules, src/components/GEMINI.md for component-specific patterns, src/api/GEMINI.md for API conventions. Performance: context files count toward 1M token limit (2M coming soon), typical GEMINI.md 500-3K tokens, keep total <10K tokens for efficient queries. Large context reduces available space for code analysis (1M limit - 10K context = 990K for actual prompts). Monitor with /memory show. Best practices (production 2025): (1) Place in repo root for project-wide context (.gemini/GEMINI.md or GEMINI.md in root). (2) Add folder-specific GEMINI.md for subsystems (frontend/GEMINI.md vs backend/GEMINI.md with different conventions). (3) Include concrete examples - show desired code patterns, not just descriptions (Example API route: export async function GET() {...}). (4) Document non-obvious conventions - edge cases, gotchas, team-specific decisions (Why we use Zustand over Redux: better TypeScript inference). (5) Version control - treat GEMINI.md as code (PR reviews for changes, semantic versioning for major updates). (6) Regular updates - keep in sync with tech stack evolution (update when upgrading Next.js 14→15, React 18→19). (7) Use imports - split into logical files (architecture.md, standards.md, workflows.md), easier maintenance. Advanced integration: combine with checkpointing (gemini checkpoint save project-setup saves conversation + GEMINI.md state, gemini checkpoint load project-setup resumes with exact context). Use with custom commands (commands.json references GEMINI.md conventions). Essential for team consistency (100+ engineers using same context = standardized AI assistance).

Prompt optimization (2025) determines quality gap between production-ready code (90%+ correct first try) vs iterative debugging (5+ rounds). Specificity principle: Precise prompts reduce iteration cycles 70%. Bad: improve this code. Good: Refactor this authentication function to use async/await instead of callbacks, add comprehensive error handling for network failures and invalid credentials, include retry logic with exponential backoff (3 attempts max, 1s/2s/4s delays), validate JWT expiry before API calls. Context provision: Include file purpose, technical constraints, target environment, expected behavior. Structure: state what code does currently, what changes needed, why (performance/security/maintainability), acceptance criteria. Example for API client: This fetchUser function uses Axios 1.6, runs in Node.js 20 LTS, must handle 429 rate limits with Retry-After headers, timeout after 5 seconds, return TypeScript interface User with typed fields. Structured output requests: Use --output-format json for machine parsing (CI/CD integration), specify markdown with clear sections for documentation, request OpenAPI 3.1 YAML for API specs. Format specification reduces parsing errors 80%. Iterative refinement workflow: Start broad with architecture question (Should I use REST or GraphQL for this mobile app API?), narrow to implementation (How do I implement GraphQL subscriptions with Redis PubSub?), refine specifics (Fix this resolver to handle concurrent subscription updates without race conditions). Each step builds context. Example-driven prompting (few-shot learning): Provide 1-3 examples of desired output pattern. For test generation: Include sample test showing structure (describe blocks, beforeEach setup, assertion style, mock patterns), Gemini replicates format for new tests. Improves consistency 60%. Production prompt patterns (battle-tested 2025): (1) Code review - Review this TypeScript pull request for: OWASP Top 10 vulnerabilities (SQL injection in raw queries, XSS in user-generated content, broken auth in session handling), React 19 best practices (proper useEffect dependencies, key prop usage, Server Component data fetching), TypeScript strict mode violations (implicit any, missing null checks), performance issues (N+1 database queries, large bundle size from imports, unoptimized re-renders). Provide file:line references with severity ratings (critical/high/medium/low) and concrete fixes. (2) Documentation generation - Generate OpenAPI 3.1 specification from these Express.js route handlers. Include: all endpoints with HTTP methods, request/response schemas with TypeScript types converted to JSON Schema, authentication requirements (Bearer token OAuth 2.0), comprehensive error responses (400/401/403/404/500 with problem detail RFC 7807), usage examples with curl commands. Format as YAML. (3) Test creation - Generate Vitest tests for this React component. Requirements: unit tests for all exported functions, integration tests for user interactions (click/type/submit), edge cases (null props, empty arrays, async errors), >90% code coverage, MSW for API mocking, Testing Library for DOM queries (prefer getByRole over getByTestId). Include describe blocks organized by feature. (4) Debugging - Analyze this production error stack trace from Node.js 20 with source maps. Error: UnhandledPromiseRejectionWarning: Error: ECONNREFUSED 127.0.0.1:5432. Context: PostgreSQL container, Docker Compose networking, intermittent during high load. Suggest: connection pool exhaustion diagnosis (check pool.totalCount metrics), Docker network configuration (check service name resolution), race condition in initialization (database migrations vs app startup ordering). Advanced techniques (expert-level 2025): (1) Multi-file context chaining - Use --file with glob patterns (src/**/*.ts) to load entire module context, Gemini analyzes dependencies across files. For large codebases (>1M tokens), use hierarchical prompts (analyze architecture first → specific files second). (2) GEMINI.md project context - Create repo root GEMINI.md with coding standards (ESLint config, TypeScript strict rules, React component patterns, API conventions). Gemini automatically applies to all queries without repeating. Update GEMINI.md when standards evolve. Example entry: All database queries use prepared statements via pg library, never string concatenation. Express routes use async handlers with try-catch, return proper HTTP status codes (200 success, 400 invalid input, 401 unauthorized, 404 not found, 500 server error). (3) Temperature control via API - Low temperature (0.2-0.4) for deterministic code generation (bug fixes, refactoring), high temperature (0.7-0.9) for creative tasks (naming, architecture brainstorming). Configure in gemini config or --temperature flag. (4) Token budget optimization - Summarize large files before including (remove comments, condense whitespace), exclude generated/vendor code (node_modules, dist, coverage), use --max-tokens to cap response length (prevents overlong explanations). Saves 40-60% tokens. (5) Checkpoint-based iteration - For complex multi-step tasks, save checkpoint after each phase (gemini checkpoint save refactor-step-1), enables branching (try alternative approach), rollback on failures. Anti-patterns to avoid: (1) Vague requests - fix my code, make this better, improve performance (missing criteria). Results in generic suggestions requiring clarification rounds. (2) No context - pasting code without explaining purpose, environment, constraints. Gemini guesses incorrectly 50%+ cases. (3) Expecting perfection - assuming first response is production-ready. Always review, test, iterate (average 2-3 rounds for complex tasks). (4) Overloading single prompt - asking 5+ unrelated questions in one message. Split into focused prompts, maintains conversation coherence. (5) Ignoring errors - when Gemini tool calls fail (file not found, API timeout), provide clarification immediately (Here's correct path, Retry with different approach). Token budget management: Gemini 2.0 Flash has 1M token context window (~750K words). Large prompts (50K+ tokens) incur higher latency (5-15s vs 2-5s for small prompts) and cost. Monitor usage with gemini config get usage. Strategies: exclude irrelevant files (use .geminiignore similar to .gitignore), summarize documentation before including (extract key sections only), paginate large outputs (request 10 results at a time vs all 100). Prompt templates for common tasks (copy-paste ready): Security audit: Perform security audit of this [language] code following OWASP Top 10 2021 standards. Check for: injection flaws, broken authentication, sensitive data exposure, XXE, broken access control, security misconfiguration, XSS, insecure deserialization, known vulnerabilities, insufficient logging. Return findings in JSON with severity, description, affected_code, remediation. Performance optimization: Analyze this [framework] application for performance bottlenecks. Profile: database query efficiency (N+1, missing indexes), render performance (unnecessary re-renders, large component trees), bundle size (code splitting opportunities, tree shaking), network requests (parallelization, caching headers). Suggest specific optimizations with expected impact (20% faster, 50% smaller bundle). Migration automation: Migrate this codebase from [old version] to [new version]. Handle: breaking API changes, deprecated features, new recommended patterns, dependency updates. Generate migration plan with file-by-file changes, test strategy, rollback procedure. Validate migrated code compiles and tests pass. Performance metrics (2025 production): Well-optimized prompts achieve 85-95% correctness on first try (vs 40-60% for vague prompts). Token efficiency: focused prompts use 2K-10K tokens (costs $0.01-0.05 per query at Gemini 2.0 Flash pricing), unfocused prompts waste 20K-50K tokens through clarification rounds (costs 5-10x more). Latency: specific prompts with clear constraints complete in 3-8 seconds, vague prompts requiring multi-turn clarification take 30-60 seconds total. Essential for scaling AI-assisted development (optimized teams generate 50-100 code changes daily with 90%+ quality).

Gemini CLI accesses powerful tools (shell, files, databases, MCP servers) - security critical for production use (2025). Key risks: (1) Data leakage - Gemini sends context to Google servers for processing (no on-premise option), any data in prompts transmitted to cloud. Free tier users: input may be used to improve Google AI models by default (opt-out available), paid tier users: data excluded from model training. (2) Unintended actions - AI might execute destructive commands if not restricted (verified incident: AI agent deleted database rules after being told they represented ground truth, demonstrating autonomous action risks). (3) Credential exposure - API keys/tokens in responses logged to conversation history (~/.gemini/history), accessible in plaintext unless encrypted. (4) Silent data exfiltration - Google fixed vulnerabilities in v0.1.14 (July 25, 2025) that could have enabled silent data exfiltration through malicious MCP servers or prompts. Security model (2025): Gemini CLI is Apache 2.0 open source (github.com/google-gemini/gemini-cli) - developers can inspect code to verify security implications and audit tool execution logic. Privacy-focused permission model: CLI only accesses information explicitly provided in prompts or referenced through specific file paths (explicit consent basis, users maintain complete control over shared context). Gemini doesn't automatically scan entire file system or access sensitive data without direct authorization. Only specifically mentioned resources made available to model for processing. Mitigation strategies (production best practices): (1) Sandboxing - Default: no sandbox mode (full system access), Recommended: use sandboxing whenever possible with AI agents. Supported sandboxes: Docker containers (--sandbox docker, pre-built gemini-cli containers available), Podman (--sandbox podman for rootless containers), macOS Seatbelt (native macOS sandbox). Sandboxing isolates Gemini from host system (restricted file access, network isolation, limited shell commands). (2) Read-only access - Configure MCP servers with read-only database users (GRANT SELECT only, no INSERT/UPDATE/DELETE/DROP permissions), use read replicas for database queries (prevents accidental writes to production), MCP server best practice: expose read operations by default, require explicit confirmation for write operations (needs_confirmation: true flag). (3) Explicit confirmations - Require manual approval for destructive operations: --confirm-before-tool-execution flag prompts user before executing shell commands/file writes/MCP tool calls, review each action before proceeding (prevents autonomous deletion/modification). (4) Environment separation - Run Gemini CLI against staging/dev environments, never production directly (test AI-generated changes in isolated environment first), use separate Google Cloud projects for dev vs prod (isolates API keys, billing, audit logs). (5) Credential management - Store API keys in environment variables (export GEMINI_API_KEY=...), never hardcode keys in GEMINI.md or commit to version control (.gitignore for .env files, use .geminiignore for sensitive context files), use secret managers (1Password CLI, AWS Secrets Manager, Google Secret Manager) for team environments, rotate API keys quarterly (minimum), revoke immediately if exposed. Gemini CLI supports ${VARIABLE} references in settings.json for env var substitution. (6) Audit logging - Enable verbose logging: --log-level verbose or gemini config set log-level verbose, logs saved to ~/.gemini/logs/ with timestamps, tool executions, parameters, results, monitor logs for unexpected tool calls (unauthorized file access, suspicious MCP server invocations), integrate with SIEM (Splunk, Datadog) for enterprise monitoring. (7) Input sanitization - Don't include PII/sensitive data in prompts (health records, financial numbers, government IDs, SSNs, passwords), review GEMINI.md context files for sensitive info before committing to version control (team-shared context = team-visible data), use data masking for examples (replace real email addresses with [email protected], real IPs with 192.0.2.1 documentation ranges). Data privacy guidelines (official Google recommendations): According to Gemini API Terms - Do not upload sensitive personal information such as health records, financial numbers, government IDs, biometric information unless legally necessary and appropriately secured. Gemini processes data in Google cloud infrastructure (not locally) - any shared data transmitted to Google servers. While Gemini doesn't use prompts/responses to train models (paid tier), free tier input may be used to improve AI models by default (check data settings in Google AI Studio). Production security checklist (2025): (1) Authentication - Use Google Cloud project authentication (not personal account) for production, enable single sign-on (SSO) with external identity providers, enforce 2-step verification to protect from stolen passwords, monitor password requirements and IAM security best practices. (2) Access control - Follow principle of least privilege (IAM roles: minimum permissions needed for task), assign Gemini CLI limited service account permissions (read-only by default, write only when required with approval), audit role assignments quarterly. (3) Network security - Run Gemini CLI in restricted networks when accessing internal systems (VPN, private subnets), firewall rules: allow only necessary outbound connections (Google API endpoints, MCP server ports), monitor network traffic for anomalies (unexpected data exfiltration, unauthorized API calls). (4) API key protection - Protect API keys: never log in plaintext, rotate regularly (90-day max), restrict by environment (dev keys != prod keys), monitor usage in Google Cloud Console (track request counts, token consumption), set budget alerts near quota limits (prevents unexpected billing from runaway automation), implement exponential backoff for rate limit errors (prevents quota exhaustion). (5) Vulnerability management - Keep Gemini CLI updated (npm update -g @google/generative-ai-cli checks for latest version), subscribe to security advisories (GitHub watch google-gemini/gemini-cli releases, security tab), patch immediately when vulnerabilities disclosed (example: v0.1.14 fixed data exfiltration risks in July 2025). (6) MCP server security - Audit third-party MCP servers before use (inspect source code for data collection, network calls, credential handling), run untrusted MCP servers in Docker containers with restricted network (--network none for local-only tools), validate MCP server protocol compliance with @modelcontextprotocol/inspector, implement MCP server rate limiting (max 10 tool calls/minute prevents runaway automation). Rate limiting (cost control + security): Free tier limits (Gemini 2.5 Pro: 5 RPM, 100 RPD | Gemini 2.5 Flash: 10 RPM, 250 RPD) prevent runaway automation costs and limit blast radius of compromised credentials (attacker can't exfiltrate unlimited data). Paid tier (300 RPM): implement application-level rate limiting (circuit breakers, token buckets) to prevent accidental quota exhaustion. High-security environment alternatives: For organizations with strict data residency requirements (government, healthcare, finance), consider: (1) Self-hosted LLM alternatives (Llama, Mistral) with on-premise inference (no cloud data transmission), (2) Manual code review workflow (AI generates suggestions offline, human reviews before applying), (3) Air-gapped development (run Gemini CLI in isolated network, transfer code via secure channels), (4) Contractual data processing agreements with Google Cloud (DPAs, BAAs for HIPAA compliance). Essential principle: Treat Gemini CLI as untrusted user - grant minimal permissions, require approval for critical operations, audit all actions, never give unrestricted access to production systems. Security is defense-in-depth (multiple layers: sandboxing + read-only + confirmations + logging + access control).

JSON output (2025) enables production automation integrating Gemini into CI/CD pipelines, data processing workflows, and monitoring systems. Core usage: gemini 'your prompt here' --output-format json --file path/to/code.ts outputs machine-parseable structured data (vs human-readable text). Response format: Top-level object with response field (AI-generated text content), toolCalls array (which tools were invoked with parameters and results), metadata object (model used, token counts, latency). Use jq (command-line JSON processor) for parsing: gemini 'count functions' --output-format json | jq -r '.response' extracts text, jq '.toolCalls[].name' lists tools used. Production automation patterns (real-world 2025): (1) CI/CD quality gates - GitHub Actions/GitLab CI script calls Gemini to analyze PR code quality, parses JSON to count issues by severity (critical/high/medium/low), fails build if critical issues >0. Example workflow: RESULT variable captures gemini --output-format json output, COUNT variable extracts issue count with jq '.issues | length', conditional exits with code 1 if COUNT >threshold. (2) Security scanning automation - Nightly cron job analyzes entire codebase for OWASP Top 10 vulnerabilities, outputs findings to security-report.json, integrates with Slack webhook to notify security team if new vulnerabilities detected. Schedule: 0 2 * * * (runs 2am daily). (3) Log analysis pipelines - Process server logs in batch: for each .log file, run gemini to extract structured error data (timestamp, error type, stack trace, affected user), save as .errors.json, aggregate with jq -s 'add' into single report, visualize in Grafana dashboard. Parallelization: xargs -P 4 runs 4 concurrent Gemini processes (respects 60/min rate limit: 4 parallel × 15/min each = 60 total). (4) Documentation generation - Weekly automation generates OpenAPI specs from TypeScript route handlers, converts Gemini JSON output to YAML format, commits to docs/ folder with git, triggers Netlify deploy. Uses --output-format json for reliable parsing (vs markdown requiring regex). (5) Compliance auditing - Monthly audit of database access patterns: Gemini analyzes SQL queries in codebase, flags non-parameterized queries (SQL injection risk), outputs JSON with file:line references, creates Jira tickets automatically via API. Advanced patterns (expert-level): (1) Error handling - Check exit codes: gemini returns 0 on success, non-zero on failure. Parse error field in JSON response for failure details. Implement retries with exponential backoff for transient API errors (rate limits, timeouts). Example: retry_count=0; until gemini ... || [ $retry_count -eq 3 ]; do sleep $((2**retry_count)); retry_count=$((retry_count+1)); done. (2) Parallel processing with rate limiting - Use GNU parallel or xargs -P to run multiple Gemini calls concurrently while respecting API rate limits (60 requests/minute free tier, 360/min paid). Calculate max parallelism: parallel_jobs = rate_limit / (60 / avg_request_duration_seconds). For 5-second average requests: 60 / (60/5) = 5 parallel jobs stays under limit. Monitor with Gemini API usage dashboard. (3) Result aggregation and reporting - Combine JSON outputs from multiple runs: jq -s 'add' merges array of objects, jq -s 'map(.issues) | add' flattens nested arrays. Generate HTML reports: use jq to transform JSON into data structure, pipe to template engine (mustache, handlebars), produce styled HTML with charts (Chart.js for visualizations). (4) Schema validation - Define JSON schema for expected response format using JSON Schema standard, validate with jq or ajv-cli before processing. Catches Gemini output format changes early (when model updates alter response structure). Example: ajv validate -s schema.json -d response.json exits non-zero if invalid. (5) Streaming and incremental processing - For large batch operations (analyzing 1000+ files), process incrementally: run Gemini on 10 files at a time, append results to aggregate JSON, prevents memory exhaustion and allows partial progress recovery on failures. Use jq streaming parser for very large JSON (>100MB): jq --stream processes without loading entire file into memory. Performance optimization (2025 production data): JSON parsing overhead: <10ms with jq (native C implementation), 50-100ms with JavaScript JSON.parse for large responses (>1MB). Negligible vs Gemini API latency (2-10 seconds median). Parallel execution: 4 concurrent requests vs sequential reduces total time 75% (40min → 10min for 100-file analysis, assuming 5s per request). Rate limiting impact: free tier 60/min handles up to 6 parallel requests with 10s average duration, paid tier 360/min supports 36 parallel. Output size: typical responses 1-10KB JSON (1-2K tokens text), large code analysis 50-100KB (include full file contents in toolCalls). Use jq to filter before storing (extract only issues array, discard verbose tool call details). Alternative output formats: (1) --output-format markdown - structured text with headings/lists/code blocks, easier human reading but requires regex for parsing (fragile). Use for reports intended for humans. (2) --output-format text (default) - unstructured prose, unsuitable for automation. (3) Custom formats via prompt engineering - request specific JSON schema in prompt (Respond with JSON containing fields: severity, description, file, line, remediation), Gemini attempts to match but not guaranteed. --output-format json wrapper more reliable. Common pitfalls and solutions: (1) Malformed JSON responses - Gemini occasionally outputs invalid JSON (unescaped quotes, trailing commas in arrays). Solution: validate with jq '.' before processing (exits non-zero if invalid), implement fallback to text parsing or retry request. (2) Response truncation - Very large outputs may truncate mid-JSON. Solution: use --max-tokens to set response limit, request paginated results (analyze files 1-10, then 11-20), check for truncation indicators in metadata.truncated field. (3) Inconsistent schema - Response structure varies between prompts (sometimes response is string, sometimes object). Solution: define expected schema explicitly in prompt (Return JSON object with response field as string), validate programmatically. (4) Rate limit exhaustion - Parallel automation hits 60/min limit causing 429 errors and failed workflows. Solution: implement token bucket rate limiter in script, queue excess requests, retry with exponential backoff. (5) Timeout handling - Long-running Gemini calls (complex analysis >60s) time out in CI/CD. Solution: use --timeout flag to extend (--timeout 120s), split large tasks into smaller chunks (analyze per-directory vs entire repo). Integration with observability tools: Export Gemini automation metrics to Prometheus (custom collector scrapes JSON output, exposes gemini_analysis_issues_total counter, gemini_api_latency_seconds histogram), visualize in Grafana dashboards, alert on anomalies (sudden spike in detected issues indicates code quality regression or Gemini false positives). Structured logging: Log all automation runs in JSON format (timestamp, prompt, file analyzed, issue count, duration) to centralized logging (ELK Stack, Splunk), enable tracing for debugging failures. Cost tracking: Parse token counts from metadata.usage field (prompt_tokens, completion_tokens), calculate costs (Gemini 2.0 Flash: $0.075 per 1M input tokens, $0.30 per 1M output), aggregate monthly expenses, set budget alerts. Typical automation costs: CI/CD analysis (100 PRs/month × 10K tokens/PR × $0.075/1M = $0.075/month), nightly security scans (30 runs × 100K tokens × $0.075/1M = $0.225/month). Total <$1/month for small/medium projects. Production-ready script template: Set up error handling (set -euo pipefail for bash strict mode), validate dependencies (check jq installed with command -v jq), define retry logic function, run Gemini with JSON output and timeout, validate JSON response schema, extract relevant fields with jq, aggregate results, generate report, send notifications (Slack webhook for failures), clean up temporary files, exit with appropriate code. Essential for scaling Gemini beyond interactive use to production automation (1000+ automated analyses daily in large organizations).

Gemini CLI checkpoints (2025 feature): save/restore conversation state enabling multi-session workflows with 2M token context window (largest in industry, 2x Claude Code). Commands: gemini checkpoint save (saves conversation context, history, loaded files, GEMINI.md config, model settings), gemini checkpoint load (restores exact state), gemini checkpoint list (shows all checkpoints with creation date, context size), gemini checkpoint delete (cleanup). Storage location: ~/.gemini/checkpoints/ as JSON files (example: codebase-review-2025-01.checkpoint, ~1-50MB depending on context). Use cases: (1) Large codebase analysis - load entire monorepo once (10min initial context loading, 500K tokens), save checkpoint, resume instantly for queries without reloading (saves 10min per session, cost: $0). (2) Iterative development - checkpoint after each feature discussion (feature-v1, feature-v2), branch for alternative approaches (a/b testing implementation strategies). (3) Documentation generation - save common starting points (api-docs-template with style guide loaded, readme-generator with project structure), instant resume with consistent configuration. (4) Team collaboration - share checkpoint files (.checkpoint JSON, version control safe after stripping sensitive data with gemini checkpoint sanitize ). Advanced patterns: (1) Branching workflows - load checkpoint, ask different questions, compare outputs side-by-side. (2) Progressive refinement - checkpoint after each iteration (refactor-step-1, refactor-step-2), rollback to previous state if experiment fails. (3) Multi-day projects - save daily checkpoints (mon-morning, mon-afternoon), context persists across sessions. Performance: save 100-500ms (context serialization), load <100ms (instant context restoration, 2M tokens in memory). Context window advantage: checkpoints with 2M tokens context (equivalent to ~1.5M words, entire large codebases like Next.js framework ~500K tokens). Security: checkpoints include full conversation (may contain API keys, passwords), review with gemini checkpoint inspect before sharing, use .gitignore for *.checkpoint files. Integration with GEMINI.md: checkpoint captures GEMINI.md project instructions at save time, ensures consistent behavior across sessions. Production workflow: name descriptively (project-milestone-YYYY-MM-DD), clean old checkpoints monthly (gemini checkpoint prune --older-than 30d), combine with version control (git tag checkpoint releases). Essential for complex multi-session tasks: large-scale refactoring (>1K files), comprehensive documentation generation, thorough code review workflows requiring multiple iterations.

Google Search grounding (2025) connects Gemini to real-time web data via Google Search API, providing current information beyond January 2025 training cutoff. Mechanism: When enabled, Gemini autonomously performs Google searches as needed (no manual search required), retrieves top 10 results with titles/snippets/URLs, grounds answers in cited sources, includes inline citations in responses (Source: [1] example.com/article). Grounding operates as MCP-like tool invocation counting toward rate limits. Activation methods: (1) Global config - gemini config set grounding true enables for all queries. (2) Per-query flag - gemini 'your question' --grounding activates for single invocation. (3) Automatic detection (experimental 2025) - Gemini decides when search needed based on query type (What's latest version of X? triggers search, Refactor this function doesn't). Configure with gemini config set auto-grounding true. Benefits quantified (2025 production data): (1) Current information accuracy - Grounding improves factual correctness 45% for queries about events/versions/releases after training cutoff (70-80% accurate vs 35-50% without grounding for 2024-2025 content). Example: What's new in React 19? with grounding returns accurate June 2024 features (Server Actions, async transitions), without grounding hallucinates or says I don't know about versions after my training. (2) Dependency version queries - npm package latest versions (What's current Vite version?), breaking changes in recent releases, compatibility matrices, security advisories (CVEs published 2024-2025). (3) Framework/library research - Compare modern tools (Bun vs Node.js 2025 benchmarks), evaluate new libraries (Is SWR or TanStack Query better for React 19 Server Components?), discover alternatives (What are Webpack alternatives in 2025? → returns Turbopack, Rspack, esbuild with current adoption stats). (4) Troubleshooting recent issues - Error messages from latest framework versions (Debugging Next.js 15 hydration errors), recently discovered bugs (Known issues with TypeScript 5.7?), community solutions from Stack Overflow 2024-2025 posts. (5) Best practices evolution - How have JWT security recommendations changed in 2025?, What's current OWASP Top 10?, Are CSS Modules still recommended vs Tailwind in 2025?. Grounding retrieves authoritative 2025 sources. Production use cases (real-world): (1) Dependency audit automation - Script queries Is [package]@[version] vulnerable? with grounding, retrieves CVE database results, flags security issues. Runs monthly for all package.json dependencies. (2) Tech radar updates - Monthly queries What are trending JavaScript frameworks 2025?, new developer tools, benchmark comparisons. Grounding provides current State of JS survey results, GitHub trending data. (3) Migration planning - Research breaking changes for upgrade paths: What changed between Next.js 14 and 15?, grounding finds official migration guides, blog posts, community experiences. (4) Competitive analysis - Compare SaaS pricing (What does Vercel Pro cost in 2025 vs Netlify?), feature comparisons, market positioning. Grounding retrieves current pricing pages. Performance characteristics: (1) Latency impact - Search adds 3-8 seconds to response time (2-5s search API call, 1-3s result processing). Total query time without grounding: 2-5s, with grounding: 5-13s (2-3x slower). Unacceptable for latency-sensitive automation (CI/CD code analysis), acceptable for research queries. (2) Token consumption - Search results add 1K-3K tokens to context (10 results × 150 tokens/snippet average). Grounded response consumes 30-50% more tokens than ungrounded (input: base prompt + search results, output: answer + citations). Costs: grounded query 5K-15K tokens vs ungrounded 3K-10K tokens. At Gemini 2.0 Flash pricing ($0.075/1M input): grounded $0.001-0.002 per query vs ungrounded $0.0003-0.001 (2-3x higher). (3) Rate limit impact - Each grounding search counts as tool invocation toward 60/min free tier limit. Heavy grounding usage (every query searches) consumes quota faster. Example: 30 grounded queries/hour uses 50% of free tier quota, leaving 30 requests for non-grounded work. Paid tier (360/min) handles grounding better. (4) Accuracy-latency tradeoff - Grounding improves accuracy 45% but increases latency 2-3x. Decision: use grounding for information queries where correctness critical, skip for code tasks where speed matters. When to enable grounding (decision criteria): (1) Version/release queries - Current versions of frameworks/libraries/languages, recent release notes, changelog details. Grounding essential (training cutoff limitation). (2) Security research - Latest CVEs, security advisories, OWASP updates, penetration testing techniques. Grounding provides current threat intelligence. (3) Comparison shopping - Pricing, features, performance benchmarks for SaaS/tools released or updated 2024-2025. Grounding ensures current data. (4) Troubleshooting errors - Searching for error messages, Stack Overflow solutions, GitHub issues from recent releases. Grounding finds community fixes. (5) Learning new technologies - Tutorials, best practices, getting started guides for tools/frameworks launched 2024-2025. Grounding discovers authoritative documentation. When NOT to use grounding (avoid waste): (1) Code generation/refactoring - Writing functions, refactoring classes, implementing algorithms. Grounding adds latency without benefit (codegen uses training knowledge, not web search). Disable for 100% of pure coding tasks. (2) Codebase analysis - Reviewing local files, finding bugs in your code, architectural analysis. Grounding searches public web (irrelevant to your private code). Use GEMINI.md context instead. (3) Well-known information - Standard algorithms (implement quicksort), established best practices (SOLID principles), language fundamentals (JavaScript async/await). Training data sufficient, grounding wastes time/tokens. (4) High-frequency automation - CI/CD pipelines analyzing 100+ PRs/day. Grounding latency (5-13s vs 2-5s) slows pipelines 2-3x, increases costs 2-3x. Disable for performance-critical automation. (5) Offline/airgapped environments - Grounding requires internet connectivity to Google Search API. Unusable in restricted networks (government, banking, healthcare with airgapped systems). Configuration best practices (2025 production): (1) Selective grounding - Keep global grounding disabled (gemini config set grounding false), use --grounding flag only when needed. Prevents accidental quota waste. (2) Query-specific prompts - For research queries, prompt explicitly: Search the web for latest information about X and cite sources. Triggers grounding via prompt engineering even without --grounding flag (model autonomously uses search tool). (3) Monitoring usage - Track grounding invocations with gemini config get usage, monitor search_queries metric. Alert if >30/day on free tier (indicates over-reliance, consider prompt optimization or paid tier). (4) Cost optimization - Batch research queries (one prompt asking 5 questions triggers single search vs 5 separate prompts = 5 searches). Combine: What are current versions of React, Vue, Angular, Svelte, Solid? retrieves all in one grounded response. (5) Result caching - Cache grounding results locally for frequently asked questions (What's current Node.js LTS? changes quarterly, cache for 90 days). Implement with gemini wrapper script storing responses in Redis/SQLite. Advanced: Citation validation - Grounding includes source URLs in responses, validate citations programmatically: extract URLs with regex, HTTP HEAD request to verify still accessible (catches link rot), compare response content with Gemini summary (detect hallucination despite grounding). Integration with automation: CI/CD dependency check: weekly scheduled job queries Is [package] latest version? with --grounding, compares against package.json versions, creates PR for outdated deps. Security monitoring: daily query Latest CVEs for Node.js, PostgreSQL, Docker with --grounding, parses CVE IDs from response, checks if production versions affected, alerts security team via Slack. Tech radar: monthly What are top 10 trending developer tools 2025? with --grounding, generates report from search results, posts to internal wiki. Common pitfalls: (1) Over-reliance on grounding - Using for all queries (slow, expensive), when training data sufficient for 80% of coding tasks. (2) Ignoring citations - Accepting grounded responses without checking sources (Gemini may misinterpret search results, always verify linked sources for critical decisions). (3) Stale cache assumptions - Assuming grounding always returns latest (search indexes update with lag, Google results may be hours/days old, not real-time). (4) Network failures - Grounding fails in restricted networks (corporate firewalls blocking Google APIs), no graceful fallback (query fails entirely vs degrading to ungrounded response). Implement retry without --grounding flag. Security considerations: Grounding exposes queries to Google Search API (Google logs search terms, may include sensitive project names, proprietary technology names). Don't use grounding with confidential information (internal product codenames, unreleased features, security vulnerabilities pre-disclosure). Search results from public web only (Gemini cannot access private documentation, internal wikis, enterprise knowledge bases via grounding - use MCP servers for internal data). Essential for queries requiring post-training-cutoff information (2024-2025 content), but overhead (latency, cost, quota) mandates selective use (research queries only, not coding tasks).

Gemini CLI custom commands (2025): reusable workflow templates enforcing team standards and AI interaction patterns. Configuration: create ~/.gemini/commands.json or project-local .gemini/commands.json (project overrides global). Format: {"commands": {"security-review": {"prompt": "Review this code for OWASP Top 10 vulnerabilities (SQL injection, XSS, CSRF), authentication/authorization issues, secret exposure, input validation. Provide file:line references with severity (critical/high/medium/low) and remediation steps.", "files": true, "outputFormat": "markdown", "model": "gemini-2.0-flash-exp"}, "api-docs": {"prompt": "Generate OpenAPI 3.1 spec with: endpoint descriptions, request/response schemas, auth requirements (OAuth 2.0), error codes (400/401/403/404/500), examples. Format as YAML.", "files": true, "outputFormat": "yaml"}, "test-gen": {"prompt": "Generate Jest tests: unit tests for all functions, edge cases (null/undefined/empty), >90% coverage, mocks for external dependencies, async/await handling.", "files": true}}}. Usage: gemini security-review --file src/auth.ts (executes custom command with standardized prompt). Advanced patterns: (1) Parameterized commands - {"prompt": "Analyze ${FILE} for ${CONCERN}"}, pass: gemini analyze --file app.js --var CONCERN="performance bottlenecks", (2) Multi-step workflows - {"steps": [{"prompt": "Analyze architecture", "checkpoint": "arch-analysis"}, {"prompt": "List improvements from previous analysis"}]}, (3) Conditional logic - {"if": "${LANG} == 'typescript'", "prompt": "Check type safety"}, (4) Output templates - include JSON schema in prompt for structured parsing. Team collaboration: (1) Commit .gemini/commands.json to repo (version control commands alongside code), (2) Document in README.md: available commands (gemini --list-commands), usage examples, expected outputs, (3) Code review commands as code - PR reviews for command updates, (4) Shared command registry - internal npm package with company-wide commands. Production use cases: (1) Security review - OWASP compliance checks before deployment, (2) API documentation - auto-generate OpenAPI specs from code, (3) Test generation - maintain >80% coverage automatically, (4) Code migration - standardized refactoring (React Class → Hooks, JavaScript → TypeScript), (5) Accessibility audits - WCAG 2.1 AA compliance checks. Performance: zero overhead vs manual prompts (commands expand to full prompts at runtime), caching applies normally. Model selection: specify per-command ("model": "gemini-2.0-flash-exp" for speed, "gemini-1.5-pro" for complex reasoning). Best practices: (1) Name convention: verb-noun (review-security, generate-tests, migrate-typescript), (2) Include concrete examples in prompts (few-shot learning improves output quality 40%), (3) Version commands with semantic versioning (review-security v1.2.0), (4) Test commands on sample data before team rollout (validate output format/quality), (5) Monitor usage: gemini metrics shows command execution frequency, (6) Iterate based on feedback - update prompts as team needs evolve. Integration: combine with CI/CD (run gemini security-review in GitHub Actions), pre-commit hooks (gemini lint-commit-message), IDE extensions (VS Code task integration). Essential for scaling AI-assisted development across teams (100+ engineers using standardized commands = consistent code quality).

Gemini CLI checkpoints save/restore conversation state for multi-session workflows with 2M token context window (largest in industry). Commands: gemini checkpoint save (saves conversation context, history, loaded files, GEMINI.md config, model settings), gemini checkpoint load (restores exact state), gemini checkpoint list (shows checkpoints with date and size), gemini checkpoint delete (cleanup). Storage: /.gemini/checkpoints/ as JSON files (1-50MB). Performance: save 100-500ms, load <100ms. Context window: supports 2M tokens (equivalent to ~1.5M words, entire large codebases like Next.js ~500K tokens). Security: checkpoints include full conversation (may contain secrets), review with gemini checkpoint inspect before sharing, use .gitignore for *.checkpoint files.

Checkpoint workflow patterns: (1) Large codebase analysis - load entire monorepo once (10min initial loading, 500K tokens), save checkpoint, resume instantly for queries without reloading (saves 10min per session). (2) Iterative development - checkpoint after each feature discussion (feature-v1, feature-v2), branch for alternative approaches (A/B testing implementations). (3) Documentation generation - save common starting points (api-docs-template with style guide, readme-generator with project structure), instant resume with consistent config. (4) Team collaboration - share checkpoint files (.checkpoint JSON, version control safe after gemini checkpoint sanitize strips sensitive data). (5) Progressive refinement - checkpoint after each iteration (refactor-step-1, step-2), rollback if experiment fails. (6) Multi-day projects - save daily checkpoints (mon-morning, mon-afternoon), context persists across sessions. Production workflow: name descriptively (project-milestone-YYYY-MM-DD), clean old checkpoints monthly (gemini checkpoint prune --older-than 30d), combine with version control (git tag checkpoint releases). Essential for large-scale refactoring (>1K files), comprehensive documentation, thorough code review requiring multiple iterations.