Quick Start

Run with npx

npx gemini-cli-scanner

No install required. Launches an interactive TUI:

Menu Item	What It Does
Quick Scan	Environment scan, optional repo discovery — no API key needed
Full Scan	Everything + AI-powered skill suggestions from your conversation patterns
View Report	Scrollable markdown report with t for TOC section-jump navigation
Maturity Dashboard	Score breakdown (0–67), tier, advisory recommendations
Auth Settings	Credential switching with export hints for session persistence

Headless Mode

# Quick scan, no AI
npx gemini-cli-scanner --skip-suggestions

# Full scan with repos, last 30 days
npx gemini-cli-scanner --repos ~/Code --chat-days 30

# Deep repo discovery, JSON only
npx gemini-cli-scanner --repos ~/Code --repo-depth 4 --json-only

Pass -- before flags if npx intercepts them: npx gemini-cli-scanner -- --skip-suggestions

Install as Agent Skill

Install as a reusable skill so your AI assistant can scan on demand:

npx skills add pauldatta/gemini-cli-scanner@scan -g -y

Then just ask: "scan my environment" or "audit my setup".

Install as Extension

For /scan commands inside Gemini CLI:

gemini extensions install https://github.com/pauldatta/gemini-cli-scanner

Then use natural language or slash commands:

• "Scan my environment"
• /scan — full scan + read the report
• /scan-repos ~/Code — auto-discovers and scans repos

Configure

Set one of these for AI-powered skill suggestions:

# Option A: Vertex AI (uses gcloud auth ADC)
export GOOGLE_CLOUD_PROJECT="your-project"

# Option B: API key
export GOOGLE_API_KEY="your-key"

Without either variable, the scanner still runs — it just skips skill suggestions.

CLI Options

npx gemini-cli-scanner [OPTIONS]

--version, -v         Show version and exit
--gemini-dir PATH     Path to .gemini dir (default: ~/.gemini)
--home-dir PATH       Home directory for Claude scanning (default: ~)
--output-dir PATH     Output directory (default: ./scan-results)
--repos PATH [PATH..] Code repo paths or parent directories to scan
--repo-depth N        Max depth for recursive repo discovery (default: 3)
--chat-days N         Only include conversation data from the last N days
--skip-suggestions    Skip AI skill suggestion (no API key needed)
--json-only           Output JSON only, no markdown report
--include-prompts     Include raw prompts, topics, and project names in output manifest
--skip-update-check   Don't check GitHub for newer versions

Output

After running, check scan-results/:

• gemini-env-manifest.json — Structured data for aggregation
• gemini-env-report.md — Human-readable report with scores, recommendations, and skills

Privacy & Redaction

Auto-redacted: API keys (AIza..., sk-...), OAuth tokens (ya29...), GitHub PATs (ghp_...), and any field named token, secret, password, or api_key.

Privacy by default (v3.5.6+): The output manifest contains only aggregate statistics — counts, tool names, and chain fingerprints. Raw prompts, topics, and project names are not written to disk. Use --include-prompts to include them for local analysis.

Not touched: Shell history, browser data, or files outside ~/.gemini/, ~/.claude/, and --repos paths.

Developer Install

git clone https://github.com/pauldatta/gemini-cli-scanner.git
cd gemini-cli-scanner
make          # Interactive TUI
make test     # 263 tests across 12 test files