Command reference

This page covers every command in geo help --all, in the same groups. Run geo <command> --help for the full list of flags of any command; this page explains what each command is for and the options you will use most.

Options that every command takes

Options available on every command

Option	What it does
--home DIR	The folder where Geometer keeps its records. The default is $GEO_HOME, or ~/.geometer-host when that is not set.
-h, --help	Print help for the command.
-V, --version	Print the version (on geo itself).

Most commands take a project folder as [PATH], which defaults to the current folder. Many take --json to print a machine-readable result. A <PROBLEM> or <ID> is an identifier that an earlier command showed you.

geo --help shows the eight everyday commands. geo help --all lists every command, grouped as Explore, Guard, Prove, This computer and Advanced. Each command appears once below, under its group. Every command that worked before still works. Run geo on its own for a short status or a welcome.

Everyday

• geo check (Check this folder for problems.)
• geo status (What your agents may do now.)
• geo practice (Try the practice agent.)
• geo replay (Re-run a problem you found.)
• geo verify (Check my fix.)
• geo mcp (Use Geometer from Claude Code or Cursor.)
• geo regression (Keep a problem as a check, and re-run your kept checks.)
• geo guard (Watch and control what agents do right now.)

Running geo on its own

geo

Prints a short status and the next step when the current folder is a project Geometer already knows. Otherwise it prints a short welcome with the ways to start: geo practice and geo check. It changes nothing and exits with 0. Run geo --help for the everyday commands and geo help --all for every command.

Explore

geo check

geo check [PATH] [--json] [--budget SECONDS] [--declarations DIR] [--require-exercised]

Checks a folder and answers in plain words: a one-line verdict, the problems it found, and the next command to run. It does the same work as geo ci and exits with the same codes (0 nothing found, 1 a confirmed problem, 2 evidence is missing, 3 something could not run). --json prints the same report as geo ci --json. For scripts and CI, use geo ci, whose output never changes. See Run kept checks in CI.

geo ci

geo ci [PATH] [--json] [--report FILE] [--junit FILE] [--budget SECONDS] [--declarations DIR] [--require-exercised] [--assessment DIR]

Runs the project’s automatic checks headless, and then re-runs the kept checks. It writes structured JSON and JUnit XML. See Run kept checks in CI for each option, the exit codes and examples.

Exit codes of geo ci

Code	Meaning
0	Nothing failed.
1	A confirmed failure, including a kept check that reproduced a problem.
2	Required evidence is missing, or nothing could be checked.
3	An infrastructure failure.

Problems found by suggested rules are reported and never fail the run.

geo explore

geo explore [PATH] [--budget SECONDS] [--agent NAME] [--scenario NAME] [--json]

Explores the declared agent tasks and scenarios live in the controlled tool world. It makes a bounded search over held tool calls and lost-reply faults, with one trial per verified reset.

Options of geo explore

Option	What it does
--budget SECONDS	Wall-clock budget. The default is 600.
--agent NAME	Only tasks of this agent service.
--scenario NAME	Only this scenario or task.
--strategy NAME	random, exhaustive, sleep_sets or source_dpor. The default is bounded exhaustive search, then seeded random walks if the budget runs out. The reductions run only after the live adapter passes conformance.
--seed N, --depth N, --trials N, --random-trials N	The seed (0), the number of choices per trial (8; a step with one way to go, such as a lookup, does not count), trials per scenario (24) and random walks after an unfinished search (4).
--declarations DIR	Declarations folder used instead of the project’s .geometer/, for projects Geometer must not modify.
--answer ID=TEXT, --save-declarations DIR	As for geo onboard.

geo replay

geo replay <PROBLEM> [--clean-worker] [--json]

Replays a problem from a clean start with the model answers recorded when it was found. With --clean-worker, it replays the problem on a second clean machine, with a fresh records folder and fresh containers from a copy of the project at the saved revision, and reports exact, same problem, diverged or incompatible.

geo shrink

geo shrink <PROBLEM> [--budget N] [--confirm N] [--json]

Cuts a problem down to the smallest steps that still show it. Every candidate runs from a clean reset, twice by default (--confirm), and the results must agree. The result is replayed again before it is accepted. Unreliable results are reported, not accepted. --budget is the number of candidate runs allowed (60 by default).

geo verify

geo verify <PROBLEM> [--path FOLDER] [--json]

Checks your fix: replays the problem on your changed code, confirms the risky path was really tried and looks at nearby cases. --path is the changed folder (the folder the problem was found in by default). It exits with 0 when the problem no longer happens, 1 when it still does, and 2 when it cannot tell.

geo regression

Kept checks.

Subcommands of geo regression

Subcommand	What it does
geo regression keep <PROBLEM> [--allow NODE=OUTCOME]	Keeps a problem as a check that cannot be edited, in the records and as a reviewable file under .geometer/regressions/ (or the external declarations’ regressions/). --allow allows a node an outcome it did not show when recorded, as an explicit decision, for example retry=rejection for a fix that refuses a duplicate with a 409. Repeatable. It shows what it will keep, names any allowed outcome and asks yes or no; it needs a terminal and refuses without one, and no option skips the question.
geo regression list [PATH]	Lists the kept checks for a project.
geo regression run [PATH] [--declarations DIR] [--json]	Re-runs the project’s kept checks on its current code. Exits 1 when any is reproduced and 2 when any is inconclusive or incompatible.

geo stability

geo stability [PATH] [--plan] [--model SPEC] [--candidate SPEC] [--variation NAME] [--samples N] [--json]

Checks constraint stability: does the agent keep its approved rules when its conversation is longer, when a tool’s reply asks it to skip approval, when its instructions are worded differently, or on another model? The project’s tasks and approved rules are reused. Every variation runs beside an unchanged run with the same seed, on tool doubles. --plan prints the plan (what would run, the commitments, the budget) and stops.

Options of geo stability

Option	What it does
--model SPEC	The model checked: scripted (with --model-script), ollama:<model>, openai:<model>@<base_url>. The default is the check model setting.
--candidate SPEC	Another model to run the unchanged tasks on, for the model-change variation.
--variation NAME	Only these variations (repeatable): long_conversation, hostile_tool_response, wording, compaction, handoff, model_change.
--samples N	Samples per variation (2 by default), each beside an unchanged run.
--long-messages N	Earlier exchanges that a longer conversation puts before the agent’s request (12).
--scenario NAME	Only this task (repeatable).
--max-calls, --max-prompt-tokens, --max-output-tokens, --max-total-tokens, --max-cost-usd-micros, --time-budget	Budgets for model calls, tokens, money (in millionths of a US dollar; the default 0 allows only free models) and seconds (1800).
--allow-hosted-model	Allow a hosted model for this run. Stored consent from geo model use also allows it.

It exits with 1 when a rule was broken, 2 when a run could not be decided or did not run, and 0 otherwise. Exit 0 means nothing broke in the runs that were made.

geo model-upgrade

geo model-upgrade [PATH] [--to SPEC] [--from SPEC] [--estimate] [--samples N] [--json]

Checks a model change: two separate experiments. The recorded model’s outputs are replayed against the application, which is an application regression check and says nothing about the new model. Then the new model is asked fresh about the agent’s own requests within a budget, and where its answer changes the agent’s tool calls, that branch runs live in the isolated tool world under the same rules.

Options of geo model-upgrade

Option	What it does
--to SPEC	The new model: scripted (with --model-script), ollama:<model>, openai:<model>@<base_url>. A hosted model needs your consent (--allow-hosted-model). Cloud (:cloud) models are always refused.
--from SPEC	The current model. stand-in (the default) uses the project’s scripted stand-in. Any backend spec asks that model fresh and records its answers as the baseline.
--estimate	Print the estimate (calls, tokens, cost) and which models would be asked, then stop.
--samples N, --baseline-samples N, --seed N	Fresh samples per scenario (1) and for the baseline, and the seed (1).
--max-calls, --max-prompt-tokens, --max-output-tokens, --max-total-tokens, --max-cost-usd-micros, --time-budget, --max-turns	Budgets.

Per scenario the result is same, changed with rules satisfied, changed with a rule violated, the current model varies, or not run or unknown. It exits with 1 when a rule was violated, 2 when any sample is unknown or not run, and 0 otherwise.

Guard

geo guard

Guard: propose and configure a separate Guard program from the project’s reviewed rules, start it, and approve or deny held calls. Nothing here deploys to production on its own. See Guard and Watch with Guard. Every subcommand takes [PATH].

Subcommands of geo guard

Subcommand	What it does
setup	Proposes a policy from the reviewed rules and tool contracts and asks the one question. --answer watch (recommended) or --answer not_now. With watch it applies the proposal: files only, nothing starts. Without --answer it only shows the proposal. --upstream says where the real tool runs: host:port for plain HTTP or https://host[:port].
bundle	Writes the immutable, content-addressed policy bundle built from reviewed rules. A rule that is not reviewed cannot enter.
start	Starts the configured Guard programs as separate processes. --supervise runs it so it starts again with backoff if it crashes.
stop, status	Stops Guard, or shows its state. status takes --json.
login-item	On a Mac, starts Guard, supervised, when you log in. It shows what it would write unless you add --confirm. --remove deletes it. It is never loaded for you. It is not available on Linux.
approve ID	Approves one held call: exactly that call, once.
deny ID	Denies one held call.
revoke ID	Withdraws an approval.
reviews	Lists the calls waiting for a person: who asked, the exact arguments, the rule and its version, how fresh the policy is, when the request expires and who it is waiting for.
approvers	Shows who may approve, their roles, issued credentials and stopped agents.
approver-add ID --tool TOOL [--max-amount N]	Adds an approver for one tool, optionally with an amount limit in the rule’s own units. Their credential is printed once and not kept on your computer.
approver-remove ID	Removes an approver. Their credentials stop working and their approvals are not used.
agent-credential AGENT [--hours N] [--tool TOOL]	Issues a new credential for an agent, optionally expiring after some hours. It is printed once.
rotate-agent AGENT [--overlap-minutes N]	Replaces an agent’s credential. The old one keeps working for the overlap (15 minutes by default).
rotate-admin	Replaces the admin credential while Guard keeps running.
credential-revoke ID	Revokes one issued credential. Others keep working.
agent-stop AGENT [--off] [--reason TEXT]	Stops one agent’s new calls. --off allows them again. Other agents are not affected.
kill [--off] [--reason TEXT]	Stops all new calls at the Guard. --off releases. Effects already sent are not undone.
exception-grant	Lets calls that match skip one rule for a while, as an approver. Needs at least one --match FIELD=VALUE, and --tool, --rule, --hours (at most 7 days), --reason and optionally --max-amount.
exception-revoke ID	Ends an exception now.
tools	Lists the tools each running Guard has pinned, and the ones whose definition changed since.
tool-review NAME	Reviews a tool whose definition changed. --accept uses the new definition, --reject keeps its calls refused.
reconcile	Settles calls whose outcome is uncertain, or only acknowledged, from the provider’s own records. Nothing is sent again.
rollout, rollback	Rolls the policy bundle written for a tool out to the running Guard (--tool), or back.
backup --to FOLDER	Backs up each Guard’s store and evidence into a folder, checked with geo-verify.
promote --confirm-production	Reviews the rules to production and switches the Guard to stopping calls. An explicit decision, which needs --confirm-production. It does not mean Guard is ready for production traffic.

Prove

geo assessment

Assessment reports, which Geometer also calls certificates: create a signed report from a finished check, read it, export it as a folder anyone can check without Geometer, check a report with a key you choose, and record that it was withdrawn or no longer applies. A report states what a bounded check found within its limits. See Prove and certificates.

Subcommands of geo assessment

Subcommand	What it does
create [CHECK] [--path PATH] [--profile classical|hybrid]	Creates a report from a finished check (by default the newest finished check of the project). Creating it again returns the same report. hybrid signs with Ed25519 and ML-DSA-65, both required, in a larger file.
list [PATH]	Lists the project’s reports, each with what it found, whether it is unchanged and whether it still applies.
show ID [--html] [--markdown]	Shows one report in plain words, or as its stored HTML or Markdown page.
export ID [--out DIR] [--public] [--include-private]	Saves a report as a folder anyone can read and check without Geometer. Private evidence stays on your computer unless you add --include-private. Anything that looks like a secret is withheld. --public exports a separate redacted copy for sharing publicly, with its own id.
verify BUNDLE [--trust-key FILE] [--trust-this-computer] [--anchor FILE]	Checks a report file or folder. It never trusts a key that came with the report. Choose --trust-key (a key file you got from the issuer) or --trust-this-computer.
status ID [--out FILE]	Shows the report’s status now, signed: issued, replaced, marked as no longer applying, or withdrawn.
withdraw ID --reason TEXT	Withdraws a report: you no longer stand behind it. Its results are kept as they were.
invalidate ID --because WHAT --reason TEXT	Marks a report as no longer applying because something changed. Its results are not changed.
renew ID	Keeps today’s check of the report, a fresh signed status and an anchor of the record with it.
forget ID EVIDENCE --reason TEXT	Removes one evidence file of a report. The report keeps listing it, as deleted.
key [--out PATH]	Saves this computer’s public key and key log, for the people who will check your reports.

geo prove

Prove: what is recorded, whether it still matches a copy you saved elsewhere, evidence export, and turning a Guard incident into a check. A match shows the record was not changed since the copy. It does not show the record is true or complete.

Subcommands of geo prove

Subcommand	What it does
status [--json]	Shows what is recorded and whether it matches the copy you saved.
export [--out DIR]	Writes evidence (JSON, CSV and an OpenTelemetry trace file) and an anchor to keep elsewhere. --token-file exports with an export-only reader’s credential.
anchor [--out FILE]	Saves only an anchor: a signed statement of where the record stands, to keep elsewhere.
copies [DIR] [--off]	Chooses the place, outside this computer if you can, where copies of the record’s state are kept on their own each time a batch of entries is recorded. --off stops it.
verify PACK --anchor FILE [--require-profile classical|pq|hybrid]	Checks an evidence pack against anchors you kept. The standalone geo-verify does the same with no Geometer.
maintain	Runs upkeep now: the key rotation schedule, retention limits, archiving and encrypting older call details.
retention	Sets retention limits of one record: --payload-days, --payload-mb and --archived-days. A value of 0 turns a limit off. Every removal stays visible.
access	Export-only reader credentials: add-reader (shown once), list and revoke.
keys	Signing keys: list, rotate, revoke, recover, store (move keys to private files or, on a Mac, the keychain) and profile (which signatures every new checkpoint carries: classical, pq or hybrid).
forget SEQ [--reason TEXT]	Removes a retained payload (the call’s arguments). The record keeps showing that it existed.
incidents [PATH]	Lists Guard calls that were stopped, held or would have been stopped.
incident DECISION [PATH]	Turns an incident into a check: copies it into an isolated case on test copies of your tools, verifies what it needs and runs it. It never resends, keeps or promotes anything, and never changes a policy. --no-wait starts the case and returns.
incident-status INCIDENT	Shows where an incident stands.
incident-keep INCIDENT	Keeps a reproduced incident as a regression check. This is your decision: it asks yes or no and needs a terminal, like geo regression keep. A policy change is separate.

geo decisions

The recorded lifecycle decisions: proposing a rule, accepting its meaning, turning it on in CI, switching Guard to stopping calls, and deciding to publish an assessment.

Subcommands of geo decisions

Subcommand	What it does
geo decisions list [PATH] [--json]	Lists the project’s decisions, and rule decisions not tied to a project, newest first.
geo decisions publish-assessment <SUBJECT> [PATH] [--confirm]	Records the decision to publish an assessment. Only the decision is recorded; nothing is published.

This computer

geo mcp

geo mcp install --client claude-code|cursor [--write] [--yes] [--config FILE]
geo mcp serve
geo mcp wrap [FILE] [--write] [--yes]
geo mcp unwrap [FILE] [--write] [--yes]
geo mcp mode SERVER|--all pass|guard [--config guard.toml]
geo mcp tools [SERVER]
geo mcp try [--pack NAME] [--scenario NAME] [--fault lost-reply|lost-request|crash] [--tool NAME] [--for 30m] [--record-model] [-- COMMAND]
geo mcp try keep
geo mcp try replay [ID]
geo mcp record SERVER|--all [--for 10m] [--yes] [--list] [--delete ID] [--http BASE-URL] [--listen ADDR]
geo mcp twin SERVER|ID... [--name NAME] [--list]

geo mcp install prints the line that adds Geometer to your coding assistant, for you and not for a project. With --write it adds it after you say yes (--yes skips the question). geo mcp serve is what the assistant starts; you do not run it yourself. geo mcp wrap puts a relay in front of the servers in your MCP configuration (a preview first; geo mcp unwrap restores the file exactly), geo mcp mode sets what the relay does, and geo mcp tools lists what each server offers. geo mcp try runs your own agent against a simulated service with a fault and says which rules held; with --record-model, geo mcp try keep turns the try into a check that geo mcp try replay runs again. geo mcp record writes a redacted record of a server’s calls on this computer, after asking, and geo mcp twin learns a simulated copy of the service from it, for geo mcp try --pack twin:NAME and geo check --pack twin:NAME. See Use Geometer from your coding assistant and Put Geometer in front of your MCP servers.

geo status

geo status [PATH] [--json]

Prints, in plain words, what Guard does with each action of your agents, what would turn Guard on, the three gauges, the faults tried and the next step with the command for it. If the project was never inspected, it first runs a read-only inspect. --json prints the summary as JSON, including each action’s level (0 or 1) and Guard’s sentence. When a next step has no command, it says so.

geo practice

geo practice [--world payments|games] [--check]

Writes the practice project (a small refund agent with a known mistake; --world games is a game item restoration desk, with the same agents) into Geometer’s own records folder and prints where it is and the next command. --check also checks it straight away. Nothing outside that folder is changed. Its check reaches all three of the project’s rules and finds the one planted mistake.

geo model

Model help: which model, if any, suggests rules and which one a model-change check (geo model-upgrade) tries. The default is no model. See Choose a model.

Subcommands of geo model

Subcommand	What it does
status	Shows the current choice for each use and the state of the free local model. This is the default for geo model.
use none|local|api|geometer	Chooses how Geometer gets model help, with --scope proposals|check, --model, --base-url, --key-env, --key-stdin, --limit-usd, --limit-tokens and --yes-send-code. The geometer choice is not available yet.
forget HOST [--scope S] [--key]	Takes back the agreement that code goes to a provider and, with --key, the stored key.
price	Records a hosted model’s price per million tokens so a money limit can bound it.
setup-local [--model NAME]	Gets the free local model: finds your Ollama, or downloads the pinned official release into Geometer’s home, checks memory and disk, then downloads qwen3:8b with progress. Stop with Ctrl-C: it continues where it stopped.

geo doctor

geo doctor [--quiet] [--fix | --no-fix] [--json]

Checks what Geometer depends on and repairs what can be repaired without harm. One line per check, each ok, fixed or needs you: the adapter bundle, Docker (running, at least version 24), disk space, your records and their format, evidence integrity, checks left running by a process that ended, and leftover containers, networks and images. --quiet prints only what is not fine, and --no-fix reports only and changes nothing. --fix also sets Docker up when it is missing or stopped: it shows the exact commands, asks Run them now? [y/N] and runs nothing until you say yes. See Install.

geo gc

geo gc [--dry-run]

Cleans up. It removes sandboxes, environments, networks and images owned by this host that no live owner claims, and clears old checks and evidence by the retention defaults (the newest 20 checks per project, with everything behind problems you found and checks you kept). It reports the space freed. --dry-run says what would be cleared without clearing it. Your own containers are never removed.

Advanced

geo inspect

geo inspect [PATH] [--json]

A read-only report of the project: modules, toolchains, targets, ambiguities and gaps. It starts nothing.

geo onboard

geo onboard [PATH] [--json] [--answer ID=TEXT] [--declarations DIR] [--save-declarations DIR]

Onboarding without configuration: what Geometer works out about a project by itself, such as outside services, how the agent is run and rules to review, where it found each, and the one question left. It reads files and starts nothing.

Options of geo onboard

Option	What it does
--answer ID=TEXT	Answer the question, using the id shown with it. Repeatable. Answers are remembered for the project.
--declarations DIR	Use a declarations folder instead of the project’s .geometer/.
--save-declarations DIR	Export what Geometer inferred into a folder for review. It refuses to overwrite a file and never writes into the project.

geo run

geo run [PATH] [--json] [--target TEXT] [--timeout SECONDS] [--install-timeout SECONDS] [--observe]

Runs the project’s own tests inside sandboxes and imports per-test results. --target limits the run to test targets whose id contains the text (repeatable). --timeout and --install-timeout are per-target deadlines in seconds (900 by default). --observe observes backing-service boundaries through protocol gateways.

geo rules

Candidate rules from declared constraints, API schemas, tool contracts and tests, and the reviews that let them gate.

Subcommands of geo rules

Subcommand	What it does
geo rules propose [PATH]	Lists candidate rules with their sources, their state, the check against the seed state, the review state, and every rejected proposal with its reason. It starts nothing. With --model SPEC it also asks a model once. Its proposals are validated like every other source and stay candidates, and the call is recorded. Later runs replay that answer and never call a model.
geo rules review <ID> [PATH]	Records a review of one candidate’s exact meaning, by id or digest prefix. --accept marks the intent as reviewed, --enable-ci makes its problems fail geo explore, --reject withdraws it. --note and --reviewer (default $USER) are recorded.

geo workload

Workloads: sequences of requests built from tests, schemas, routes, tasks and conversations, run in a provisioned environment.

Subcommands of geo workload

Subcommand	What it does
geo workload import [PATH]	Lists the workloads Geometer can build for a project, with their sources, facts and gaps, without starting anything.
geo workload run [PATH]	Runs workloads and compositions from clean resets. Options include --recipe, --compose, --repeat and --until-contention. Exits 1 when an approved rule is violated and 2 when a node could not run.
geo workload replay <RECIPE>	Replays a promoted session workload in fresh sandboxes from its frozen workspace. Exits 0 when every run matches, 3 when it diverged and 2 when the recipe cannot claim replay.

geo decide

geo decide [PATH] --module MODULE --subject SUBJECT --choice CHOICE

Remembers a decision that resolves an ambiguity reported by geo inspect.

geo env

Dependency environments: plan, provision, reset and remove.

Subcommands of geo env

Subcommand	What it does
plan [PATH] [--agents]	Shows the environment plan (services, recipes, bindings, gaps) without starting anything. --agents prints static agent discovery instead.
up [PATH]	Provisions the project’s dependencies and applications and prints the instance id.
reset INSTANCE	Runs the reset barrier. Exits 2 if the receipt is incomplete.
status, list	Shows an environment’s services, generation and last receipt, or lists recorded environments.
down INSTANCE	Removes an environment and everything it owns.
exec INSTANCE SERVICE [SCRIPT]...	Runs a shell command inside one service.

geo shell

geo shell [PATH] [--image IMAGE] [--detach]

Sandboxed terminal sessions: a command line inside a container with a copy of your project. Subcommands: attach ID re-attaches a terminal, stop ID stops a session and keeps its transcript, list lists sessions, revision reports whether the workspace changed since the session started, exec runs a command without attaching, and promote promotes a running session to a workload (its recorded commands on its frozen workspace; secrets are not stored). promote exits 2 when the recipe has gaps that block replay.

geo bundle

The adapter bundle that ships with an installed Geometer. geo bundle verify checks the installed bundle against the program. geo bundle emit writes the bundle into a folder; it is release tooling.

geo rollback

geo rollback

Goes back to the records from before the last upgrade. The newer records are set aside, not deleted. The installer’s --rollback calls this for you. See Install.

Other programs that install with geo

The installer also puts three programs next to geo. geo-verify checks an evidence pack or a certificate with no Geometer and no network; see Verify records yourself. geo-guard is Guard itself; you start it with geo guard start rather than directly. geo-model-gateway stands in front of a model you host, for the shops on your server; see Deploy on your server.

Environment variables

Environment variables that Geometer reads

Variable	What it does
GEO_HOME	The records folder. The default is ~/.geometer-host.
GEO_VERSION	Used by the installer to choose another release.
GEO_MODEL, GEO_MODEL_PROPOSALS, GEO_MODEL_CHECK, GEO_MODEL_API_KEY, GEO_MODEL_CONSENT	Choose a model and agree to send code from the environment. See Choose a model.
GEO_KEEP_CHECKS	How many of the newest checks geo gc keeps for each project. The default is 20.