geo-score CLI reference: flags, exit codes and diffs

The geo-score CLI scores a site against the AIV rubric v1.1 and prints a report as text, JSON, SARIF or JUnit. This page lists the flags of release 1.8.3, the exit codes a CI job can rely on, and how to compare two runs. The full reference, including the watch commands for level 3, is cli/README.md in the repository.

How do I run a basic score?

geo-score example.com                 # human-readable report
geo-score example.com --brief         # pillar totals and the three biggest gaps only
geo-score example.com --explain       # the evidence behind every check
geo-score example.com --json          # JSON that conforms to schema/report.v2.json

Without installing anything, replace geo-score with uvx geo-score@1.8.3, or with python3 cli/geo_score.py in a clone of the release tag.

Which flags does the CLI take?

Flag	What it does
`--brief`	Pillar totals and the three biggest gaps, sized for a screenshot.
`--explain`, `-e`	Print the evidence behind every check, not only the score.
`--json`	Machine-readable output that conforms to schema/report.v2.json.
`--json-out FILE`	Also write that JSON to a file, from the same run as the report on screen.
`--sarif FILE`	Also write SARIF 2.1.0: one rule per check, one result per check below full marks.
`--junit FILE`	Also write JUnit XML: one test per check; a check at zero fails, one not measured is skipped.
`--sample N`	How many pages to sample. The default, 8, is what the rubric specifies.
`--timeout SECONDS`	How long each request may wait (default 15, at most 300).
`--urls FILE`	Score exactly these pages, up to 8, one URL or path per line.
`--urls-from REPORT`	Score the pages an earlier JSON report sampled, so two runs read the same pages.
`--baseline REPORT`	Score the baseline's pages again and print what changed, check by check.
`--fail-on-drop`	With `--baseline`: exit 4 when a check lost points, a gate reached zero or the band fell.
`--compare URL`	Score another site too and print both side by side. Repeatable.
`--badge [FILE]`	Also write an SVG badge with the score and band.
`--badge-json FILE`	The same badge as shields.io endpoint JSON.
`--share`	Print a one-line summary for a post, plus the badge Markdown.
`--fail-under N`	Exit 1 when the score is below N.
`--fail-on-gate`	Exit 1 when any gate check scores zero, and name it on stderr.
`--assert EXPR`	Exit 1 unless a check meets a value, such as `g.robots=max` or `p1.llms-txt>=4`. Repeatable.
`--quiet`, `-q`	No progress lines on stderr.
`--version`	Print the tool version and the rubric version it scores.
`--ask QUESTION`	Level 2: also ask the AI engines this question through their APIs, with your keys. Up to 5.
`--brand NAME`, `--domain DOMAIN`	With `--ask`: the brand name to look for, and other domains that count as yours.

Subcommands: diff BEFORE AFTER compares two saved reports; watch … runs level 3; mcp starts the MCP server. geo-score --help lists them all with examples.

How do I compare two runs?

Each run samples up to 8 pages, and the sample can change between runs. To see whether the site changed rather than the sample, score the same pages again.

geo-score example.com --json-out before.json
# … deploy the change …
geo-score example.com --baseline before.json            # same pages, printed check by check
geo-score diff before.json after.json --format md        # compare two saved reports

Every check shows its points before and after with a state: up, down, same, became unobservable or became observable. A check that became unobservable left the denominator; it is never shown as a drop to zero.

What do the exit codes mean?

Code	Meaning (level 1)
0	Scored.
1	Below `--fail-under`, a gate at zero under `--fail-on-gate`, or a failed `--assert`.
2	The site could not be fetched or served only bot-challenge pages, a usage error, or an internal error. Under `--json` it prints a JSON error with a `kind` such as `dns`, `timeout` or `http_403`.
4	A drop found by `--fail-on-drop`, when nothing else exited 1.

Each fault kind has a section in the troubleshooting guide, and the CLI links to it when a site cannot be fetched.

How do I run it behind a proxy?

HTTPS_PROXY and NO_PROXY are honoured. NO_COLOR=1 turns colour off, as does piping to a file. When a site cannot be fetched through a proxy, the error names the proxy the request went through.

Which checks does the CLI leave out?

The CLI scores the 17 checks a static fetch can observe. Four are left out of the denominator rather than guessed: third-party listings, independent mentions and question coverage need off-site search or human judgement, and Chinese engine readiness is only scored when a sampled page is in Chinese or the host ends in .cn. The Claude Code skill scores all 21.