Audits and Controls

An Audit is one evidence-based view of a Build. From the CLI you read First Look, run any available Audit, check one Control on its own, and correct First Look when you know better than the probe. Reading is free. Workspace runs and Control checks cost tokens.

Read before you run

bworlds audit show storefront
bworlds audit show storefront --json

audit show lists every First Look Control under the status the Builder sees, and for each failure what was found, why it matters, and how to fix it. That status follows the Control's Finding: a failure whose Finding was dismissed shows as dismissed, without fix steps. A recheck waiting for the Builder's answer shows as awaiting-answer, an open question without a result as pending, and any other Control without a result as not evaluated. A result the Builder declared by answering a question is marked declared by the Builder, and a Control with a recheck in progress names that ControlEvaluation. Give the JSON to a coding agent as its planning input. One entry of controls, trimmed:

{
  "controlId": "app-open-access",
  "title": "Private pages require a sign-in",
  "effectiveStatus": "fail",
  "result": {
    "status": "fail",
    "source": "live",
    "evaluatedAt": "2026-09-28T10:00:00Z",
    "detail": {
      "whatWeFound": "Signed-out visitors can reach content identified as private.",
      "whyItMatters": "Requiring a sign-in stops anyone with the link from seeing private information or using paid features.",
      "howToFix": [
        "Require a signed-in session on private pages and redirect other visitors to sign-in."
      ],
      "signals": [
        {
          "type": "page",
          "value": "/dashboard served while signed out",
          "indicates": "negative"
        }
      ]
    }
  },
  "activeEvaluation": null
}

result is null for a Control without a result.

Treat a fail as a lead to investigate with the repository and the Dossier, never as a code change to apply blindly.

Run an Audit

Rerun after the Builder shipped fixes, or when the evidence is stale. The command asks for --confirm because it can charge the Workspace. Omitting the Audit slug runs First Look:

bworlds audit run storefront --confirm

Pass an Audit slug to run another available Audit:

The last four read the connected GitHub repository, so they require one:

bworlds audit run storefront security --confirm

An archived Audit, such as Launch Review (second-look), starts no new run. Its recorded runs stay readable in the app.

The CLI follows the run and reports each Control as it settles, then prints the Audit summary:

Request id: 74862134-91e4-41e1-a682-496efae67e18
Audit run started, id=9c2f4e1a-7b3d-4f5e-8a9b-0c1d2e3f4a5b (14 automated, 3 question controls)
→ https-enabled started
✓ https-enabled pass
→ app-open-access started
✓ app-open-access fail
...
Awaiting builder input (not executed):
  · data-backup
  · code-ownership-clean
  · version-control

Question Controls wait for the Builder's answer in the app. The CLI never answers for the Builder.

Limit a First Look run to one area when only that part changed. The server derives the price from the selected Controls:

bworlds audit run storefront --area security --confirm

First Look Controls live in security, operations, legal-compliance, and code-quality. See the area table. The repository Audits always run all their Controls and reject --area.

Do not hold the terminal for a long run. Start it, then read it back by ID:

bworlds audit run storefront --confirm --no-wait --json
bworlds audit status AUDIT_RUN_ID --json

Keep the request ID printed on standard error. If the connection drops before you get a response, rerun the exact command with --request-id and the server returns the run it already started instead of charging again.

Recheck one Control after a fix

When one thing changed, do not rerun the Audit. Two commands recheck a single Control.

audit reevaluate rechecks a First Look Control, records the new result in First Look, and waits for it. The Control's Finding resolves on its own when the reevaluation passes.

bworlds audit reevaluate storefront app-open-access --confirm

control run checks one Control of any available Audit, including a repository Control, and waits for the verdict. It opens no Audit run and changes no Audit result or Finding. Use it to confirm a fix before you rerun or reevaluate.

bworlds control run storefront rate-limiting --confirm
bworlds control run storefront rate-limiting --confirm --json

Both commands print the request ID on standard error, then wait up to --timeout (10 minutes by default) for the ControlEvaluation to end:

• completed: the command prints the verdict and exits 0.
• failed or cancelled: the command prints the server's reason and exits non-zero.
• awaiting_input: the check needs a Builder answer. The command prints the question and exits 0 without a verdict. The check stays open on the server; after the answer, read it with control status. A result settled by that answer reads Evidence: declared by the Builder, not verified.

--json prints the final ControlEvaluation in every case. When the wait times out or you stop it, the check keeps running on the server. Read it with control status, which starts and charges nothing and exits 0 whatever state it reads, or rerun the same command with the printed --request-id to wait again: the server returns the same check instead of starting and charging a second one. A question Control cannot be rechecked this way, because only the Builder answers it.

bworlds control status storefront EVALUATION_ID

Both commands charge the Control's price, and only when BWorlds settles the check on pass or fail: 20 tokens for a deterministic Control, 100 for an agentic Control that inspects the live app, 150 for an agentic Control that reads the repository. First Look has no repository Control, so audit reevaluate costs 20 or 100. A check the Builder's answer settles costs nothing.

Correct a verdict you verified yourself

A probe sees the app from outside. When you verified a Control by other means, override its result with a reason. The override is recorded under your identity, applies to what the Builder sees, and survives later runs until cleared.

bworlds audit override set storefront uptime-monitoring \
  --status pass \
  --reason "Better Stack monitors the home page every minute and pages the Builder, verified on 2026-09-07" \
  --confirm
bworlds audit override list storefront
bworlds audit override clear storefront uptime-monitoring --confirm

--status takes pass, fail, or not-applicable. Overrides apply to First Look, and only to Controls that probe the live app. A question Control's answer is already the Builder's evidence.

What it costs

Details and safe retries in Pricing and tokens.