Audits and Controls

An Audit is one evidence-based view of a Build. From the CLI you read any Audit, run any available Audit, check one Control on its own, answer a question only the Builder can settle, and correct a verdict when you know better than the probe. Reading is free. Workspace runs and Control checks cost credits.

See which Audits a Build carries

bworlds audit list storefront

SLUG              STATE      CONTROLS  ATTENTION  FINDINGS  LAST RUN   NAME
first-look        available   12        2          3        completed  First Look
security          available   9         0          0        never run  Keep Strangers Out
second-look       archived    8         0          1        completed  Launch Review

available can be run and read. planned is not built yet. archived keeps its recorded results readable but starts no new run.

Read before you run

bworlds audit show storefront
bworlds audit show storefront security
bworlds audit show storefront --json

Without an Audit slug, audit show reads First Look. Pass any available or archived slug from audit list to read that Audit instead. A planned Audit has nothing to read yet, and says so.

audit show lists every Control of that Audit 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. Two groups carry no verdict. An error is a technical error: BWorlds failed to run the check, and its Reason: line gives the cause the server recorded. Retry later. A not-observed or inconclusive Control is one BWorlds couldn't confirm either way. A check stopped by the Builder's app or its URL, such as an unreachable app or an invalid or private URL, is listed there too: its effectiveStatus is not-observed while result.status stays error. Fix the app or its URL, then rerun. A review that reached no verdict reads as inconclusive the same way. Neither group creates a Finding or counts toward coverage; see Control results. 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 results stay readable with audit show and audit runs.

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.

Read an Audit's history

bworlds audit runs storefront
bworlds audit runs storefront security --json

RUN ID                                STATE      EVIDENCE  STARTED           COMPLETED
aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa  completed  live      2026-09-20 08:30  2026-09-20 08:41
bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb  completed  live      2026-08-14 11:02  2026-08-14 11:15

Pass a run ID to audit status to read what that run produced. Times are UTC.

Answer a question only the Builder can settle

Some Controls are not probed: their result is the Builder's own answer. audit show prints the question and its option IDs; audit answer records the choice, settles the Control, and charges nothing.

bworlds audit answer storefront version-control yes --confirm
bworlds audit answer storefront runaway-spend yes --audit costs --confirm

A new answer replaces the standing one and costs nothing. --audit defaults to first-look, and --confirm is required because the answer is recorded as the Builder's own declaration.

A result settled this way reads declared by the Builder, not verified: it is a declaration, not evidence BWorlds observed. The record does not distinguish an answer a Workspace member typed from one the Builder gave, so confirm the facts with the Builder before answering for them.

Recheck one Control after a fix

When one thing changed, do not rerun the Audit. Two commands recheck a single Control, and they differ on where the verdict lands.

audit reevaluate rechecks one Control of one Audit, records the new result in that Audit, and waits for it. The Control's Finding resolves on its own when the reevaluation passes, and a failing reevaluation puts the new evidence on the Audit while the Finding stays open. The Builder sees both on their Findings and Audit screens.

Name the Audit after the Control; without it the command rechecks First Look. The Audit must be available and must have run on the Build at least once, because a reevaluation records its result against that run. audit list prints every Audit the Build carries, including planned and archived ones this command refuses.

bworlds audit reevaluate storefront app-open-access
bworlds audit reevaluate storefront security-headers security

Working from a Finding rather than a Control, use bworlds findings verify, described in Agent workflows. It names only the Finding. BWorlds reevaluates its Control or verifies its recorded exploratory claim. Exploration verification changes the Finding without creating or changing a Control result.

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, so nothing the Builder sees moves. Use it to confirm a fix before you rerun or reevaluate.

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

Both commands show the server price and request ID on standard error. They start without a confirmation prompt; --confirm is optional. They 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 credits for a deterministic Control, 70 for the deep secrets review (secrets-full), 100 for an agentic Control that inspects the live app, 150 for any other agentic Control that reads the repository. A First Look Control costs 20 or 100, since First Look has no repository Control. 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 credits.