Command-line reference

Synopsis

probe init [--repo PATH] [--language go|typescript|javascript|python|rust]
probe lint [--base main] [--head HEAD] [--ci] [flags]
probe review [--base main] [--reviewer=false] [--ci] [flags]
probe review [flags] BASE..HEAD
probe plan --intent-file FILE [--base main] [--ci]
probe review --plan .probe/PLAN.json [flags]
probe report [--input .probe/confidence-report.json] [--out DIR] [--format LIST] [--report-url URL]
probe version

• lint analyzes a change statically. It never executes repository code and never calls an AI provider.
• review adds sandboxed checks in Docker, the opt-in evidence stages (changed baseline tests, impacted tests, differential fuzzing, mutation, dependency preparation) and, when a model is configured, an AI investigation.
• plan asks the configured provider for an implementation plan before any code is written, evaluates it with fixed rules, and turns it into a contract that lint --plan and review --plan check the diff against.
• Only committed files are analyzed; uncommitted edits and untracked files are ignored.
• Reports are written to .probe/ in the repository by default. Console output stays short.
• Flags accept one or two dashes (-ci or --ci). Booleans are set with --ci or --ci=true and cleared with --checks=false. A value is given as --base main or --base=main.
• Run probe <command> --help for the flags of a command.

Choosing revisions

Both sides of a comparison resolve to immutable commit IDs, recorded in the report. Renames, deletions, binary files and file type changes are handled.

A range may appear before or after the flags: probe review main..HEAD --ci and probe review --ci main..HEAD are equivalent. At most one range is accepted. Any revision Git understands works: branches, tags, origin/main, HEAD~3 or a commit ID. CI jobs need enough history to resolve the base (for example fetch-depth: 0).

The trusted policy is always read from the base branch, never from the change under review, so a pull request cannot loosen its own rules.

probe lint

Static analysis of a change: Git comparison, risk signals and a report. No Docker, no provider call, no execution of repository code. Safe to run on untrusted branches.

probe lint HEAD~1..HEAD                 # the last commit
probe lint --base origin/main --ci      # this branch as a pull request, for CI
probe lint --base main --format json    # JSON report only
probe lint --base main --plan .probe/PLAN.json   # scope drift against an approved plan

probe review

Everything lint does, plus the policy's test, typecheck, build and coverage commands in disposable Docker containers, plus an AI investigation when a model is configured. Requires Docker with Linux containers and a preloaded sandbox.image.

probe review --base main --ci                        # typical pull request run
probe review HEAD~1..HEAD --reviewer=false           # checks only, no provider
probe review --base main --checks=false --reviewer=false   # static only, like lint
probe review --base main --intent-file PR.md         # give acceptance criteria
probe review --base main --impacted-tests --base-tests --ci   # run tests on both revisions
probe review --base main --format markdown,json,sarif,pr-comment --report-url "$RUN_URL"

Dependency preparation runs first, when the policy has a prepare object. Checks then run in the order test, typecheck, build, then coverage, followed by the evidence stages and the reviewer. Each container is non-root, has a read-only root and source mount, no added capabilities, no network by default, and the CPU, memory, PID and time limits of the sandbox policy. The Docker socket, your working checkout and API keys are never mounted. If Docker or the image is missing, the run ends with exit 4; nothing ever falls back to your host.

probe plan

Before the change is written: the configured provider simulates, read-only, how it would implement an intent at the base commit and submits a structured plan (files, symbols, dependencies, steps). Probe evaluates it with fixed rules and writes PLAN.json and PLAN.md. The model produces the plan; it never judges its risk. Nothing is modified or executed.

The planner's tools are read-only and work on a snapshot of the base commit: list_files, read_file, search_code and the index-backed find_references, inspect_symbol and find_callers, then submit_plan once. The assessment flags four categories from the plan and the base commit only:

Exit codes: 0; 2 with --ci when a category is flagged; 3 usage or configuration; 4 provider failure or no accepted plan.

Scope drift: --plan

lint --plan and review --plan read the plan's contract and compare the real diff with it. Each difference in the diff also becomes a plan_drift signal. The section is drifted when an item is medium or higher.

probe plan --intent-file task.md --ci                     # 1. plan; exit 2: a human validates it
# 2. an agent implements the plan
probe review --base origin/main --plan .probe/PLAN.json --ci   # 3-4. exit 0: merge; exit 2: review

The plan gate

review --plan ends with a decision, plan_drift.decision, printed on stdout and at the top of the Plan Conformance section. With --ci, it is the exit code.

The flags and contract stored in PLAN.json are never trusted: the contract is re-derived from the proposal, so an edited plan cannot widen the scope unassessed, and probe report recomputes the decision from the recorded report. The gate is a process decision, not a verdict on correctness. A plan that raises nothing is not proof that the change is safe, and drift does not check that the change implements the intent. See pre-change plans and the CI recipe.

probe init

Write a starter .probe.json for the project. It refuses to overwrite an existing file. Review the commands and image, then commit the file to your base branch.

probe report

Re-render a saved JSON report, for example to regenerate Markdown or produce SARIF in CI. Nothing is re-run, and re-rendering does not authenticate the evidence it contains; every status is re-derived from the recorded checks, so an edited report is corrected rather than trusted.

probe version and help

Exit codes

No code means "approved". A 0 says that nothing was reproduced, not that the change is correct.

Environment variables

The AI provider belongs to the deployment rather than to the repository, so these settings can come from the environment. Nothing else can: the image, commands, budgets and sensitive paths are always decided by the trusted policy.

A blank variable counts as unset. Key files are read whole with surrounding whitespace stripped, bounded to 8 KiB and must hold a single line. When the reviewer runs, the log names where each value came from, never the value itself. Whoever controls this environment chooses where redacted source is sent: keep it out of jobs that run untrusted fork code.

Output files

Add .probe/ to .gitignore. The console prints one summary: files and lines changed, number of signals and reproduced issues, the focused review surface and changed-line execution.

Risk signals

Signals are reasons to look, not confirmed defects. Go files get syntax-aware analysis; TypeScript/JavaScript, Python, Rust and other languages use labelled text heuristics. Signals on the same lines are merged into one review range in the report. File-level signals (sensitive_path, dependency_change, migration_change, infrastructure_change, binary_change, file_deleted, file_type_change, large_change, branch_growth, no_test_change, prepare_input_changed, plan_drift) concern the file, not a line: the report lists them under the file as whole file, and the JSON marks them "scope": "file". Their line only places them on the file's first changed line.

Impact analysis

With --impact (the default), lint and review build a static index of the candidate commit on the host, from committed Git objects, without running repository code. For each changed function it lists the places in unchanged code that call it and the existing tests that reach it within 3 calls, adds low impacted_caller signals, and backs the reviewer's find_references, inspect_symbol and find_callers tools.

Every answer is approximate: a listed caller is a place to review, and an absent caller is not proof that none exists. --impacted-tests runs reaching Go tests only. See impact analysis.

Languages

Policy file: .probe.json

The policy decides which commands run, in which image, with which limits, and whether an AI provider is used. It is read from .probe.json on the base branch, or from --config PATH. When there is none, built-in defaults for the detected language apply. Keys you omit take the default values shown below.

The file must be a single JSON object of at most 1 MiB. Unknown keys, unknown command names and duplicate keys are rejected with exit 3, so an older binary rejects a key it does not know.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "PROBE_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".probe.json"]
}

commands

Each command is an argv array, not a shell string: ["npm", "test"], never "npm test". At most 128 arguments; configure only the checks your project provides.

sandbox

reviewer

sensitive_paths

Globs of paths that always raise a high sensitive_path signal when changed. Paths are relative to the repository root with forward slashes; * matches within a path segment and ** across segments. Absolute paths, backslashes and .. are rejected.

fuzz v0.4

Runs the same seeded inputs through each changed package-level Go function and changed exported TS/JS function (with an unchanged signature) on baseline and candidate, and compares what the two revisions recorded. A diverged function is an observation, never a defect: it requests review (exit 2 with --ci) and never produces exit 1. {} enables it with the defaults.

mutation v0.4

Makes small deterministic changes to the added lines of changed non-test Go files and runs the package's tests once per mutant. A mutant no test notices becomes a medium surviving_mutant signal; no score is computed. All four keys are required.

"mutation": {
  "command": ["go", "test", "-json", "-count=1", "-failfast", "{package}"],
  "max_mutants": 20, "timeout_seconds": 60, "max_runtime_seconds": 300
}

prepare v0.4

Lets the trusted base-branch policy build the dependency layer: before any candidate code runs, its command runs once, in one bounded container, on dependency files exported from the base commit, and the container becomes the local image of every check. A later review of the same base and inputs reuses it. When it produces no image, the review exits 4; it never falls back to the unprepared image.

"prepare": { "command": ["go", "mod", "download"], "inputs": ["go.mod", "go.sum"], "network": true }

Language defaults

Written by probe init, and used when the base branch has no policy. Stock Node.js, Python and Rust images do not contain your dependencies: build an image that does, or add a prepare object, and adapt the commands.

AI reviewer

Optional. When a model is configured, review lets it investigate the change with bounded tools: reading redacted files and diffs, searching source, looking up references and callers in the static index, running existing checks, and creating and running temporary tests on base and candidate. It has no shell and no URL fetcher. Its claims stay hypotheses until a test reproduces a difference.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "PROBE_API_KEY"
  }
}

export PROBE_API_KEY=…                       # from your shell or CI secret store
probe review --base main --config .probe.json   # try it before committing
probe review --base main --reviewer=false            # turn it off for one run

• Only the trusted policy, --config or the deployment environment can enable the reviewer; a pull request cannot.
• Bounded, redacted source context is sent to the provider. Masking of secrets is best effort; use a local provider (for example http://127.0.0.1:1234/v1) if source must stay local.
• API keys never enter test containers. lint never calls a provider.
• Provider failures and exhausted budgets keep the deterministic results and mark the investigation incomplete; with --ci that requires human review.