Command line
Set defaults once, start Jobs, follow progress, and inspect results from a script or terminal.
This reference describes the earlier Job workflow. It does not start website mapping or operate on mapping tests. Use the dashboard or connect Codex or Claude Code to Proof for that workflow.
Build this checkout with pnpm --dir packages/cli build, then use node packages/cli/dist/cli.js in place ofproof in these examples.
proof configure
Saves the API URL, organization API key, project ID, and browser target. Pass only values you want to change. Existing values stay the same.
proof configure --api-url https://proof.example.com --api-key "$PROOF_API_KEY" --project project_storefront --base-url https://storefront.example.comThe API key determines the organization. The CLI cannot change that organization. This path needs current approved context and target settings from the earlier workflow. Mapping does not create those context approvals. The CLI requires a base URL, but it cannot override the Project’s saved test URL or network allowlist.
Set PROOF_CONFIG to use a different configuration file. The default file is ~/.config/proof/config.json.
proof job
proof job "Create an account with an already-used email and confirm no duplicate user is created"Use --test for a saved context-workflow test:
proof job --test test_duplicate_email --jsonJob options
| Option | Behavior |
|---|---|
--project | Override the configured project ID. |
--base-url | Change the URL sent in the request. Execution still uses the Project’s saved test URL. |
--commit-sha | Job against a specific commit of at least seven characters. |
--test | Replay a saved test instead of a natural-language task. |
--no-wait | Print the new Job ID immediately instead of streaming progress. |
--json | Write machine-readable JSON and keep progress off stdout. |
--timeout | Maximum wait in seconds; defaults to 1,800 and caps at 7,200. |
proof status
Get the Job as formatted JSON. It includes the Job, timeline events, safe artifact details, and Findings.
proof status job_abc123Use the CLI in automation
Pass --json so stdout contains one JSON object. Exit code 0 means passed or healed. Exit code 2 means the expected outcome did not pass. Exit code 1 means a CLI or connection problem. With --no-wait, exit code 0 only means the request was accepted; it does not mean the test passed.