CLI reference — geopilot

Commands

Command	Usage
`scan`	Audit a URL, a repository, or both `geopilot scan [path\|url] [--url <u>...] [--max-pages n] [--max-depth n] [--render auto\|always\|never] [--rule id] [--skip-rule id] [--fail-on sev] [--min-readiness n] [--fail-on-incomplete] [--ignore-robots] [--follow-external]`
`explain`	Explain one rule: evidence, sub-checks, fixes, references `geopilot explain <ruleId>`
`rules`	List the rule catalogue `geopilot rules [--all] [--json]`
`fix`	Dry-run, apply, verify or roll back closed-list fixes `geopilot fix [path] [--rule id] [--apply [--approve <fixId>...]] [--verify <runId>] [--rollback <runId>] [--verify-cmd "<cmd>"] [--serve] [--allow-dirty] [--url <u>]`
`init`	Preview and write geo.config.json `geopilot init [--origin <url>] [--language <tag>] [--yes] [--force]`
`agent`	Install or check the portable agent skill `geopilot agent install --host claude-code [--yes] \| agent install --host agents-md --write-agents-md \| agent status`
`insights`	Validate an agent insights file (L1 schema, L2 references) `geopilot insights validate <file> [--run <id>]`
`report`	Merge insights into a report, or convert a saved report `geopilot report merge <report.json> [insights.json] [--output f] \| report convert <report.json> --format markdown`
`logs`	Prove which crawlers reached your site, from access logs `geopilot logs <file...> [--format json]`
`cloudflare`	Crawler requests and blocks from Cloudflare analytics `geopilot cloudflare --zone <id> [--hours n] [--format json]`
`inspect`	Google's index status for a URL `geopilot inspect <url> --site <property> [--format json]`
`citations`	Sample whether an AI answer engine cites your domain `geopilot citations <question> --domain <domain> [--runs n] [--model m] [--yes] [--format json]`
`review` Phase 3, not in this release	Diff-aware assessment `geopilot review [--base <ref>\|--staged\|--pre-push]`
`baseline` Phase 3, not in this release	Fingerprint baselines `geopilot baseline create\|update\|show`
`hook` Phase 3, not in this release	Opt-in pre-push hook `geopilot hook install\|uninstall\|status`

Global flags

--config, --cwd, --format pretty|json|markdown, --output, --non-interactive, --yes, --quiet, --verbose, --no-color, --no-cache, --print-config. Repeated --format/--output flags are paired in order; only one format may go to stdout.

Approvals

--apply applies safe fixes. Each guarded fix needs an interactive yes or its exact --approve <fixId>.
--yes never approves a guarded fix. Asking for a guarded fix by --rule without approval exits 2 before writing.
Applying on the default branch needs a prompt or --yes; dirty target files need --allow-dirty.
--serve authorises the configured fix.serve command for this run only.

Exit codes

Code	Meaning
`0`	Success, or no gate configured
`1`	An explicit gate failed, or an insights file is invalid
`2`	Usage error, or a required approval is missing (before any source file is written)
`3`	Invalid configuration
`4`	Incomplete assessment with --fail-on-incomplete; insights references unchecked
`5`	A fix was rolled back (takes precedence over 6)
`6`	A fix was applied but did not reach its required verification level
`70`	Internal error

An unreachable target without an incompleteness gate exits 0, but only with assessment: incomplete, readiness null and no “passed” wording.

Run cache

Runs live in .geo/runs/<runId> inside a repository (with a .geo/.gitignore), otherwise in the OS user cache. Ten runs are kept, plus any run holding fix snapshots. Reports and bounded, redacted DOM snapshots are stored for insight validation; cookies, auth headers and full bodies beyond the cap are not. --no-cache disables persistence, and anything that needs stored evidence then reports it as unavailable.