# Coding agent workflows (/docs/agent-workflows)
Source code shows what an application is meant to do. BWorlds adds what has actually been observed around that code: current Audit results, production errors, user-session friction, uptime, prioritized Findings, and operator-maintained context. Give both to a coding agent so it can investigate the right problem and explain a change against real evidence.
Use `--json` when an agent consumes a command. Reads never ask for confirmation. Paid or sensitive changes require `--confirm` and should happen only after the user has authorized that specific action. This is a CLI safety check; the server separately authorizes and attributes the request. New to the vocabulary? Read the [Product model](./concepts/product-model) first.
## Start an investigation with Build context [#start-an-investigation-with-build-context]
Begin every agent session by resolving the identity and exact Build, then load the durable operational context:
```console
bworlds auth status --json
bworlds build info storefront --json
bworlds dossier pull storefront --json
bworlds findings list storefront --json
bworlds audit show storefront --json
```
This gives the agent:
* the authenticated operator and Workspace that grant access;
* the Build and connected repository it is allowed to inspect;
* the Dossier's maintained context and guardrails;
* current Findings and their recommended next actions;
* the latest Audit's Control results, evidence, rationale, and remediation guidance.
`dossier pull` returns the path of the operator workspace it updated. Let the agent read the returned `context.md` and `guardrails.md` before proposing a change.
## Investigate a production error [#investigate-a-production-error]
First retrieve grouped errors to identify frequency, recency, and source:
```console
bworlds telemetry errors storefront --json
```
Then find recent sessions affected by an error and inspect one session in detail:
```console
bworlds telemetry sessions storefront --time-range 24h --has-errors --json
bworlds telemetry sessions storefront SESSION_ID --json
```
A session detail is a summary: identity, visited pages, captured requests, detected signals, and the recorded errors and console lines. A coding agent can correlate those with routes and code paths, form a root-cause hypothesis, and identify the smallest useful reproduction before editing.
Add `--failed-only` to keep only the requests that failed. Add `--depth full` for the whole server record, including every recorded interaction and the signed replay media links. The full record is large; read it when the summary is missing what you need, not by default.
The email address of the Builder's end user is withheld from every telemetry result. An identified session reports `"userEmailWithheld": true` in its place. `--include-personal-data` returns the address, so use it only when you need to reach that person, never when the result feeds an agent.
## Understand user friction without a reported error [#understand-user-friction-without-a-reported-error]
Users can struggle without triggering an exception. Start with sessions containing repeated clicks:
```console
bworlds telemetry sessions storefront --time-range 7d --has-rage-clicks --json
bworlds telemetry sessions storefront SESSION_ID --json
```
Ask the agent to relate the clicked element and surrounding session events to the implementation. Treat the replay evidence as a clue, then verify the hypothesis in the code and tests.
## Plan work from an Audit [#plan-work-from-an-audit]
Read the current Audit before starting a new one:
```console
bworlds audit show storefront --json
```
Each entry of `controls` carries its current `result`, or `null` when the Control has none. A failed result can include `whatWeFound`, `whyItMatters`, `howToFix`, and supporting signals. Combine those fields with the repository and Dossier instead of turning a Control status directly into a code change.
Recheck one Control only after the relevant implementation or configuration has changed. `control run` checks any Control and waits for the verdict without changing the Audit. `audit reevaluate` records a new First Look result and waits for it. Both print the final ControlEvaluation and can consume Workspace tokens. After a timeout, `control status` reads the check without charging. A result with `evidenceBasis: declared` is the Builder's answer, not verified evidence:
```console
bworlds control run storefront CONTROL_ID --confirm --json
bworlds audit reevaluate storefront CONTROL_ID --confirm --json
bworlds control status storefront EVALUATION_ID --json
```
## Preserve the result for the next operator [#preserve-the-result-for-the-next-operator]
When an investigation produces a durable issue, record it as a Finding with evidence and concrete remediation steps. When it discovers lasting context or a guardrail, update the Dossier. These writes require explicit authorization:
```console
bworlds findings create storefront \
--service-line run \
--area operations \
--severity high \
--title "Checkout retries hide sustained failures" \
--description "Payment requests repeatedly fail before the user sees an error." \
--rationale "Customers can abandon checkout while the failure remains invisible." \
--steps "Surface the terminal payment error" \
--steps "Record retry exhaustion with the request identifier" \
--confirm \
--json
bworlds dossier push storefront --confirm --json
```
## A reusable agent instruction [#a-reusable-agent-instruction]
Give this instruction to a local coding agent after installing the portable `bworlds-cli` skill:
```text
Use the bworlds CLI to inspect Build "storefront" before changing code.
Read Build info, Dossier, Findings, current Audit results, grouped errors, and
relevant sessions as JSON. Correlate that evidence with the repository, explain
the likely cause, and propose the smallest verified change. Do not start a paid
Audit or perform a mutation until I explicitly authorize that action.
```
See [Authentication and tokens](./reference/authentication) to create a personal token and [Agents and automation](./guides/automation) for the JSON, exit code, and retry contracts.
# Overview (/docs)
BWorlds takes an AI-built app from "it works" to a product clients can rely on. For each **Build** (one app a Builder ships), it audits the live app against production essentials, watches it in production, and keeps a prioritized list of what needs attention. Builders see all of this in the app at `app.bworlds.co`.
`bworlds` brings the same Build to your terminal, your coding agent, and your CI. Source code only says what an app is meant to do. The CLI adds what has actually been observed around that code, so a change is planned against evidence instead of a guess.
## Who uses it [#who-uses-it]
* **A Builder on their own Builds.** Sign in with the identity you use in the app. Every Build in your Workspace is available.
* **A developer or consultant helping a Builder.** The Builder invites you to their Workspace from the app. You use your own BWorlds identity and see their Builds until they remove you.
* **A coding agent or an automated runner.** Claude Code, Codex, or a CI job runs the same commands with a personal token that represents you. Every result is available as stable JSON.
Access is the Workspace Membership itself. There are no per-Build permissions to configure. See [Access and context](./concepts/access-and-context).
## What you can do [#what-you-can-do]
Each row maps one BWorlds capability to the screen a Builder knows in the app and to the commands that reach it.
| Capability | In the app | From the CLI |
| ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------ |
| Read the Audit: what passed, what needs attention, how to fix it | Audits | `audit show`, `audit run`, `audit reevaluate`, `audit override`, `control run`, `control status` |
| Work the Build's prioritized to-do list | Findings | `findings list`, `findings create`, `findings update-status` |
| See what breaks in production and what your users live through | Errors, Sessions, Uptime | `telemetry errors`, `telemetry sessions`, `telemetry uptime` |
| Fix in the connected repository without handling a GitHub credential | GitHub connection | `repo clone`, `repo refresh`, `repo push`, `repo local-setup` |
| Keep the Build's shared memory: how it works and what never to touch | CLI only | `dossier pull`, `dossier push` |
| Know who you are, which Workspaces you belong to, which Build you target | Workspace sharing | `auth status`, `repo list`, `build info` |
Reads are free and immediate. Starting or rerunning an Audit, or checking one Control, consumes the Workspace's tokens and always asks for `--confirm`. See [Pricing and tokens](./reference/pricing).
## What this preview does not cover [#what-this-preview-does-not-cover]
* The Trust Page, SDK installation, billing, and Build settings stay in the app.
* Windows and Linux on ARM have no release binary.
* The CLI works on its own temporary clone of the repository. It does not attach to a folder you already have checked out.
## Start here [#start-here]
## Agent-readable sources [#agent-readable-sources]
Code agents can start from [`/llms.txt`](/llms.txt), read the whole corpus at [`/llms-full.txt`](/llms-full.txt), fetch any page as Markdown, and validate flags against [`/command-reference.json`](/command-reference.json).
Three portable skills install for every coding agent on your machine, each depending only on `bworlds` and these pages: [`bworlds-cli`](/bworlds-cli-SKILL.md) for the command contract, [`bworlds-audit`](/bworlds-audit-SKILL.md) to audit a Build end to end, and [`bworlds-check`](/bworlds-check-SKILL.md) for a recurring health check.
```console
npx skills add https://docs.bworlds.co/bworlds-cli-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-audit-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-check-SKILL.md -g
```
# Quickstart (/docs/quickstart)
You end this page with the current Audit of one Build in your terminal, the same Audit its Builder sees in the app. Nothing here consumes tokens.
## 1. Install [#1-install]
On macOS, install with Homebrew:
```console
brew install vulk-corp/tap/bworlds
bworlds --version
```
On Linux, run the installer script. It verifies the release checksum and installs `bworlds` into `$HOME/.local/bin`:
```console
curl -fsSLO https://docs.bworlds.co/install.sh
sh install.sh
bworlds --version
```
Neither path places the skills your coding agent reads. Add them once with the commands in [The skills](./reference/installation#the-skills). Pin `BWORLDS_VERSION` in automation and set `BWORLDS_INSTALL_DIR` when you want another directory. Details in [Installation and updates](./reference/installation).
## 2. Sign in [#2-sign-in]
If you are operating a Build owned by someone else, ask its Workspace Owner to invite you first from **Workspace sharing** at `https://app.bworlds.co/account/team`, and accept the invitation with the identity you will use here. Your own Builds need no invitation.
```console
bworlds auth login
```
The browser signs you in and the CLI stores the session in your user configuration directory, readable only by you. Check what the server sees:
```console
bworlds auth status
```
```text
Identity: Lea Marchand (@lea)
Workspaces: 2
8f1c2a7e-3b4d-4c5e-9f60-1a2b3c4d5e6f Lea Marchand (owner)
a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d Atelier Nord (member)
Builds: 5
```
## 3. Pick the Build [#3-pick-the-build]
```console
bworlds repo list
```
```text
Operator: @lea Environment: prod
SLUG NAME WORKSPACE WORKSPACE ID LOCAL
storefront Storefront Atelier Nord a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d -
inventory Inventory Desk Atelier Nord a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d -
```
Every Build command takes the slug from this list. Before acting on one, confirm what you are looking at:
```console
bworlds build info storefront
```
```text
Operator: lea (member)
Workspace: Atelier Nord (a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d)
Build: storefront (3d9e7f10-2b4c-4d8e-9a1f-6c7d8e9f0a1b), builder maxime
Authorized areas: security, operations
Token balance: 1240 tokens
GitHub: connected to atelier-nord/storefront (installation 4821931)
```
One screen tells you who you are for this Build, whether its Builder connected a repository, how many tokens the Workspace holds, and in which areas the Builder authorized BWorlds to fix code.
## 4. Read the Audit [#4-read-the-audit]
```console
bworlds audit show storefront
```
```text
Results (17 Controls):
FAIL (2):
app-open-access FAIL
Found: Signed-out visitors can reach content identified as private.
Why: Requiring a sign-in stops anyone with the link from seeing private information or using paid features.
Fix: Require a signed-in session on private pages and redirect other visitors to sign-in.
privacy-policy FAIL
Found: A published privacy policy was not found on the app pages checked.
Why: A clear privacy policy tells people what information the app collects and how it is used.
Fix: Publish a privacy policy and link it from the footer.
pending (3):
data-backup pending
code-ownership-clean pending
version-control pending
pass (12):
secrets-exposed pass
database-not-public pass
https-enabled pass
...
```
Every failed Control comes with what BWorlds found, why it matters, and how to fix it. This is the **Audits** screen of the Build in the app, and reading it is free. Pending Controls are still running or wait for the Builder's answer to a question in the app.
## Next [#next]
* Hand this to a coding agent: [Coding agent workflows](./agent-workflows).
* Rerun the Audit, reevaluate one Control after a fix, correct a verdict: [Audits and Controls](./guides/audits).
* See what breaks in production: [Production evidence](./guides/production).
* Run unattended with a personal token: [Agents and automation](./guides/automation).
# Access and context (/docs/concepts/access-and-context)
## One identity [#one-identity]
You act as your BWorlds Builder identity, the one you sign in with in the app. A user session and a personal token in an automated runner resolve to that same identity. A token creates no separate agent account and no second set of rights. **Operator** describes a Builder using the CLI, directly or through an agent; it is not a stored role.
## Membership is the grant [#membership-is-the-grant]
A Workspace Membership is the complete operational grant. As Owner or Member you have the same CLI rights to read and act on every Build the Workspace owns. There are no per-Build permissions, operator levels, or permission matrix to configure. Verified platform administrators are the separate server-side exception and can reach Build operations without a Membership.
The Owner manages this from **Workspace sharing** at `https://app.bworlds.co/account/team`: invite an email address, cancel a pending invitation, remove a Member. You accept the single-use link with your own identity. The same page shows Members the Workspaces they joined.
The server reloads Memberships on every request. When an Owner removes you, their Builds disappear from `bworlds auth status` at once and every request from your session or your tokens is rejected, without waiting for anything to expire. Your identity and your other Workspaces are unaffected.
## Outside your Workspaces, nothing exists [#outside-your-workspaces-nothing-exists]
Anything outside your Workspaces is reported as not found, whether you list it or name it directly: Builds, Audit runs, Findings, Dossier documents, telemetry. A `not_found` on an identifier you were given usually means a missing Membership, so check `bworlds auth status` before assuming the identifier is wrong.
## Name the Build every time [#name-the-build-every-time]
Every Build command takes the Build slug explicitly. Before you act, confirm what you are targeting:
```console
bworlds auth status
bworlds build info BUILD_SLUG
```
The second command names the acting identity, the Workspace, and the Build in one screen. This matters most when you belong to several Workspaces, including your own. The CLI never infers a Build from the folder you are in.
# Product model (/docs/concepts/product-model)
The CLI uses the vocabulary of the app. A handful of words cover almost everything.
## Build [#build]
A Build is one app a Builder ships: a live URL, optionally a connected GitHub repository, and everything BWorlds has observed about it. Every command that touches a Build takes its slug, the short name shown by `bworlds repo list` and in the app's URL.
## Workspace and Membership [#workspace-and-membership]
A Workspace owns Builds and the token balance that pays for Audits. Every Builder has a personal Workspace. Its Owner can invite other Builders as Members from **Workspace sharing** in the app. A Membership is the whole grant: a Member operates every Build of that Workspace, from the app and from the CLI, until the Owner removes them.
This documentation calls a Builder acting on a Build through the CLI an **operator**, whether they type the command or delegate it to a coding agent. Operator is not a separate role. Active Owner and Member Memberships carry the same operational rights across that Workspace's Builds; a personal token carries its creator's current rights.
## Audit, Control, Control result [#audit-control-control-result]
An Audit collects evidence about a Build. The CLI can run any available Audit. Omitting the Audit slug selects **First Look**, which probes the live app and asks the Builder three questions about how it is run. Its 17 Controls are organized in areas:
| Area | Area ID | What First Look covers |
| -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| Security | `security` | exposed secrets, public database, HTTPS, browser protections, public debugging files, open sign-up, private pages |
| Operations | `operations` | first-load speed, error handling, error alerts, uptime alerts, backups, version control |
| Legal and compliance | `legal-compliance` | privacy policy, trackers before consent, code ownership |
| Code quality | `code-quality` | known flaws in the libraries the page loads |
Four repository Audits read the connected GitHub repository and require one: **Security** checks exposed credentials, sign-in protection, and unsafe input paths. **Costs** checks limits on expensive requests and asks about AI, hosting, and per-user spending caps. **Shipping** checks whether the code is organized so changes remain safe to make. **Rights & Licenses** checks direct software licences and the path to request account deletion. Their CLI slugs are listed in [Audits and Controls](../guides/audits#run-an-audit).
Each check or question is a **Control** with a stable ID such as `app-open-access`. Its result is one of `pass`, `fail`, `error`, `not-applicable`, `pending`, or `dismissed`. The app folds those into three buckets a Builder reads at a glance:
| Bucket | Control results | Meaning |
| --------- | ------------------------ | --------------------------------------------------- |
| Covered | `pass`, `not-applicable` | evidence passed, or the Control does not apply here |
| Attention | `fail`, `error` | evidence failed, or could not be gathered |
| Pending | `pending`, no result yet | still running, or waiting for the Builder's answer |
A Builder can also dismiss a Control from the app. It stays visible and leaves the coverage score.
A failed Control carries three things the CLI prints and the JSON exposes: what BWorlds found (`whatWeFound`), why it matters (`whyItMatters`), and how to fix it (`howToFix`), plus the raw signals behind the verdict. These are written for the Builder's coding tool as much as for the Builder.
An **Audit run** is one execution. The server owns it: closing your terminal never cancels a run, and `audit status` reads it back by ID.
An **override** is your correction of a verdict, with a written reason, recorded under your identity. Use it when you verified something the probe could not see. It applies to what the Builder sees and persists across runs until cleared.
## Finding [#finding]
A Finding is one item on the Build's to-do list: what needs attention, why it matters, how to fix it, and where it stands. Failed Controls create Findings on their own, and a passing rerun resolves them. Operators and agents create Findings for anything they discover outside an Audit. Each Finding has a severity (`critical`, `high`, `medium`), an area, a service line, and a lifecycle status:
| Status | Meaning |
| ------------- | -------------------------------------------------------------- |
| `open` | needs attention |
| `needs_user` | waiting for the Builder: an answer, an approval, a publication |
| `in_progress` | someone is working on it |
| `resolved` | no longer needs action |
| `dismissed` | deliberately set aside, with a reason |
The **service line** says which part of the job a Finding belongs to: `launch` for getting ready for production, `run` for keeping it running, `improve` for making it better. Audit Findings are `launch`. What you find in production telemetry is usually `run`.
The **origin** says who raised a Finding:
| Origin | Raised by |
| ----------- | --------------------------------------------------- |
| `audit` | a failed Control |
| `operator` | an operator or agent, with `findings create` |
| `telemetry` | BWorlds itself, from production errors and sessions |
`findings list` returns every origin. The Builder's Findings screen, Overview, and sidebar count show `audit` and `operator` Findings. They show `telemetry` Findings only when BWorlds enables them. A Finding's own page opens from its link whatever its origin, so an open link does not prove that the Builder's list shows it. `findings edit` changes a Finding's content, never its origin.
## Production signals [#production-signals]
Once the Builder installs the BWorlds SDK in the app, three kinds of evidence accumulate and are readable from the CLI:
* **Errors**: client-side errors grouped by message, with counts and last-seen time, plus whether the SDK is still reporting.
* **Sessions**: what a visitor did, page by page, with errors, console output, and rage clicks (repeated clicks on the same element, the signature of friction with no exception).
* **Uptime**: current status, daily uptime and response time, recent incidents.
They match the **Errors**, **Sessions**, and **Uptime** screens of the Build in the app.
## Dossier [#dossier]
The Dossier is the Build's shared operator memory: two documents, `context.md` (how this app works and what matters to its Builder) and `guardrails.md` (what never to touch, what to check before shipping). It lives on the server, so every operator and agent starts from the same baseline. The CLI syncs it into a local operator workspace, always outside the cloned repository, so nothing of it ends up in the Builder's code.
## Repository [#repository]
When the Builder connected GitHub, the CLI can clone, refresh, and push the repository with a short-lived credential scoped to that one repository. It can also bring up a local Supabase instance seeded with the Build's shared fixture, so you reproduce a production problem on realistic data. See [Fix in the repository](../guides/repository).
# Security boundaries (/docs/concepts/security-boundaries)
## The server decides [#the-server-decides]
Every Build access is checked on the server against your current Workspace Membership. Passing a Build slug, a Finding ID, or an Audit run ID never bypasses that check, and lists are filtered the same way. Which commands the CLI shows or hides is a convenience, never a control.
A personal token represents the Builder who created it; it grants no separate agent role. The server reloads that Builder's current Memberships and platform capability on every request. No request field can claim an exemption from authorization or from billing.
Device Approval binds a short-lived, single-use code to one pending CLI login. Only an already signed-in Builder user session can approve it; a CLI credential cannot approve a code. The session the CLI receives belongs to the approving Builder, whether approval happens on the same device or another one.
## Repository credentials [#repository-credentials]
Repository commands ask the server for a short-lived GitHub App credential scoped to the one connected repository. Clone and refresh get read access; push gets write access. The CLI refuses a push without `--confirm`, but that flag is a local safety check, not evidence sent to the server. Server authorization comes from the authenticated Builder's current access. Git receives the credential through a process-only header. Before a refresh or push, the CLI verifies that `origin` still points to the exact repository the server authorized. The credential is never written to `remote.origin.url`, to the CLI's config file, or to normal output.
When `bworlds repo push` creates a new commit, it uses the GitHub App identity and adds your verified BWorlds handle and identity as trailers; `--message` cannot replace them. If the CLI resumes a commit that already exists, it preserves that commit's existing metadata. Direct use of a repository credential is outside these CLI attribution guarantees.
Keep Git tracing off around repository commands. The CLI also strips common Git trace variables from the processes it starts.
## What asks for confirmation [#what-asks-for-confirmation]
The CLI requires `--confirm` before anything that costs tokens or changes shared state: Audit runs, reevaluations, and Control runs, overrides, Finding writes, Dossier pushes, repository pushes, token creation and revocation. Without a terminal, a missing confirmation fails immediately instead of prompting. Confirmation prevents accidental CLI use; server authorization and attribution remain independent checks.
# Audits and Controls (/docs/guides/audits)
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 [#read-before-you-run]
```console
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:
```json
{
"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 [#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:
```console
bworlds audit run storefront --confirm
```
Pass an Audit slug to run another available Audit:
| Audit slug | Audit | What it checks |
| ----------------- | ------------------------------------- | ----------------------------------------------------------------- |
| `first-look` | First Look | the live app, plus three questions for the Builder |
| `security` | Keep Strangers Out | exposed credentials, sign-in protection, and unsafe input paths |
| `costs` | Never Wake Up to a Five-Figure Bill | limits on expensive requests, plus three spending-cap questions |
| `shipping` | Keep Shipping Without Breaking Things | whether the code is organized so changes remain safe to make |
| `rights-licenses` | Rights & Licenses | direct software licences and the path to request account deletion |
The last four read the connected GitHub repository, so they require one:
```console
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:
```text
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:
```console
bworlds audit run storefront --area security --confirm
```
First Look Controls live in `security`, `operations`, `legal-compliance`, and `code-quality`. See the [area table](../concepts/product-model#audit-control-control-result). 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:
```console
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 [#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.
```console
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.
```console
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.
```console
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 [#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.
```console
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 [#what-it-costs]
| Command | Tokens |
| ---------------------------------------------- | ------------------------------ |
| `audit show`, `audit status`, `control status` | 0 |
| `audit run` (the Workspace's first First Look) | 0 |
| `audit run` | Shown by the Audit detail |
| `audit reevaluate` | Control price: 20 or 100 |
| `control run` | Control price: 20, 100, or 150 |
| `audit override set / clear / list` | 0 |
Details and safe retries in [Pricing and tokens](../reference/pricing).
# Agents and automation (/docs/guides/automation)
A personal token lets a coding agent, a remote machine, or a CI runner act as you. It represents your Builder identity, whose current Memberships and platform capability are reloaded by the server on every request, and it can be revoked at any time.
## Get a personal token [#get-a-personal-token]
Create the token from a signed-in local session, before configuring the agent or runner:
```console
bworlds auth login
bworlds auth token create --name coding-agent --expires-in-days 30 --confirm --json
```
The command reveals the token once. Store its `token` value as `BWORLDS_TOKEN`. The full flow, including revocation, is in [Authentication and tokens](../reference/authentication).
## Non-interactive contract [#non-interactive-contract]
Set every target and authorization explicitly:
```console
export BWORLDS_TOKEN="$SECRET_TOKEN"
bworlds auth status --json
bworlds build info BUILD_SLUG --json
bworlds audit run BUILD_SLUG --confirm --no-wait --json
```
Automated execution with `BWORLDS_TOKEN` needs no browser. A plain `auth login` instead uses Device Approval and may try the system browser, but its printed code and URL work on headless machines. Paid or sensitive commands fail when `--confirm` is absent. Commands with an interactive fallback, such as replacing an existing temporary clone, offer a non-interactive flag such as `--force`.
## Output streams [#output-streams]
Human-readable output is the default. Use `--json` whenever a command offers it. Result data goes to standard output. Progress, warnings, and request IDs go to standard error, so standard output stays parseable.
Every successful JSON result has a top-level `"schemaVersion": "2"`. Other fields stay at the top level, so selectors such as `.id`, `.findings`, and `.sessions` read directly.
### Field names [#field-names]
Every command names its fields in camelCase, at every depth of the result. Write one selector shape and reuse it across commands:
```console
bworlds telemetry sessions storefront --json | jq '.sessions[].startedAt'
bworlds telemetry errors storefront --json | jq '.errors[].firstSeen'
```
Until the next `schemaVersion`, a result also carries each field's snake\_case name, so `.started_at` keeps working; that `schemaVersion` removes the duplicates. Write new selectors against the camelCase name. The one exception is a session detail at its default depth: the summary is a shape of its own and carries camelCase names only, and `--depth full` returns the whole server record with both spellings.
Two kinds of value keep their keys exactly as they were written, because those keys are data rather than fields: a Finding's or a Decision's `metadata`, and a session event's `payload`.
Errors use this shape when `--json` is present:
```json
{
"schemaVersion": "2",
"error": {
"code": "payment_required",
"message": "workspace tokens are insufficient for Build \"storefront\": payment required (HTTP 402)",
"exitCode": 7
}
}
```
### Personal data [#personal-data]
Telemetry results withhold the email address of the Builder's own end users. A session that carried one reports `"userEmailWithheld": true` instead, so an identified session reads differently from an anonymous one.
Pass `--include-personal-data` when the address is what you need. Do not pass it when the result goes into a coding agent's context.
The command index at [`/command-reference.json`](/command-reference.json) records the exact flags for the documented CLI version.
## Exit codes [#exit-codes]
| Code | Meaning | What an agent should do |
| ----: | --------------------------------------------------- | ------------------------------------------------------------------------------ |
| `0` | Success | Consume the result. |
| `1` | Runtime failure outside the invocation | Read the message: a local tool, the filesystem, or a wait the server outlived. |
| `2` | Invalid command, argument, or local input | Fix the invocation. Do not retry unchanged. |
| `3` | Missing, expired, or revoked authentication | Replace or refresh the credential. |
| `4` | Authenticated but forbidden | Check Workspace Membership. Token management needs a user session. |
| `5` | Resource not found or outside accessible Workspaces | Recheck the Build target and Membership without probing elsewhere. |
| `6` | Conflict | Read current server state before deciding whether to retry. |
| `7` | Insufficient Workspace tokens | Stop the paid operation. |
| `8` | Network failure | Retry with the same request ID for a paid mutation. |
| `9` | Rate limited | Back off before retrying. |
| `10` | Server failure | Retry only when safe. Preserve the request ID. |
| `130` | Stopped by Ctrl-C or SIGTERM | Treat as a deliberate stop. Check server state before retrying. |
## Paid retries and long-running Audits [#paid-retries-and-long-running-audits]
`audit run`, `audit reevaluate`, and `control run` create a UUID request ID when none is supplied. Record it from standard error or from the JSON result. If the response is lost, repeat the exact command with `--request-id UUID`. Server-side idempotency prevents a second debit for the same operation. `bworlds control status BUILD_SLUG EVALUATION_ID --json` reads a Control check started by `audit reevaluate` or `control run` without charging; the id is the `controlEvaluationId` of the JSON result and appears in a timeout message.
Start an Audit without holding the runner open, then poll its durable identifier:
```console
result=$(bworlds audit run BUILD_SLUG --confirm --no-wait --json)
run_id=$(printf '%s' "$result" | jq -r '.id')
bworlds audit status "$run_id" --json
```
A local timeout or disconnect never cancels a server-owned Audit run.
## Generic shell example [#generic-shell-example]
```sh
#!/bin/sh
set -eu
: "${BWORLDS_TOKEN:?set BWORLDS_TOKEN in the secret store}"
: "${BUILD_SLUG:?set BUILD_SLUG explicitly}"
bworlds auth status --json >/tmp/bworlds-context.json
bworlds build info "$BUILD_SLUG" --json >/tmp/bworlds-build.json
bworlds findings list "$BUILD_SLUG" --json
```
Do not enable shell tracing around secrets. Never print `BWORLDS_TOKEN` or place it in a repository file.
## Run in GitHub Actions [#run-in-github-actions]
Store the personal token as the repository secret `BWORLDS_TOKEN`. Pin the CLI version and name the Build explicitly:
```yaml
name: BWorlds check
on:
workflow_dispatch:
permissions:
contents: read
jobs:
inspect:
runs-on: ubuntu-latest
env:
BWORLDS_TOKEN: ${{ secrets.BWORLDS_TOKEN }}
BWORLDS_VERSION: 0.1.0-preview.1
BUILD_SLUG: storefront
steps:
- name: Install the verified CLI
run: |
curl -fsSLO https://docs.bworlds.co/install.sh
sh install.sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Verify identity and target
run: |
bworlds auth status --json
bworlds build info "$BUILD_SLUG" --json
- name: Read current Findings
run: bworlds findings list "$BUILD_SLUG" --json
```
The example only reads. Add `--confirm` explicitly when the workflow is authorized to make a paid or sensitive change, and keep the same `--request-id` across a retry of a paid operation.
Revoke the token from a signed-in local session when the workflow is retired:
```console
bworlds auth token list --json
bworlds auth token revoke CREDENTIAL_ID --confirm
```
# Production evidence (/docs/guides/production)
Once the Builder installed the BWorlds SDK in the app, the CLI reads three kinds of production evidence. All reads are free.
## Errors first [#errors-first]
```console
bworlds telemetry errors storefront
```
```text
Heartbeat: alive (last seen: 2026-09-07T09:41:12Z)
COUNT MESSAGE LAST SEEN SOURCE
----- ------------------------------------------------------------ -------------------- ------
38 TypeError: Cannot read properties of undefined (reading 'id') 2026-09-07T09:38:50Z window.onerror
12 Failed to fetch /api/leads: 500 2026-09-07T08:12:04Z fetch
```
The heartbeat line tells you whether the SDK is still reporting. The table groups errors by message: how often, how recently, and where they came from. Start with the most frequent recent one.
## Then the sessions that hit it [#then-the-sessions-that-hit-it]
```console
bworlds telemetry sessions storefront --time-range 24h --has-errors
```
```text
ID STARTED DURATION PAGES ERRORS RAGE
------------------------------------ -------------------- ---------- ----- ------ ----
6b1e6b4e-2c3d-4e5f-8a9b-1c2d3e4f5a6b 2026-09-07T09:37:02Z 4m 12s 6 yes yes
0f8a7d6c-5b4a-4c3d-9e8f-7a6b5c4d3e2f 2026-09-07T08:11:40Z 1m 3s 2 yes -
Showing 20 of 43 sessions (use --json for full results)
```
Open one:
```console
bworlds telemetry sessions storefront 6b1e6b4e-2c3d-4e5f-8a9b-1c2d3e4f5a6b
```
```text
Session: 6b1e6b4e-2c3d-4e5f-8a9b-1c2d3e4f5a6b
Started: 2026-09-07T09:37:02Z
Ended: 2026-09-07T09:41:14Z
Duration: 4m 12s
Pages: 6
Errors: yes Rage clicks: yes
Error Events (2):
[184230ms] TypeError: Cannot read properties of undefined (reading 'id') (window.onerror)
[184260ms] Failed to fetch /api/leads: 500 (fetch)
Rage Clicks (1):
[186900ms] 7 clicks on button.checkout-submit
Console Entries (3):
[184100ms] [error] POST /api/leads 500
...
```
A timeline like this takes a coding agent from "an error happened" to "this button, on this page, right after this request". Correlate it with the route and the code path, reproduce, then edit.
## Friction without an error [#friction-without-an-error]
Users struggle silently: a button that does nothing, a form that never confirms. Rage clicks catch that.
```console
bworlds telemetry sessions storefront --time-range 7d --has-rage-clicks
```
Treat the clicked element and what happened around it as a clue, and verify in the code before concluding.
## Uptime [#uptime]
```console
bworlds telemetry uptime storefront
```
```text
Status: up
Uptime: 99.87%
Avg Response: 412ms
Daily Rollups (7 days):
DATE UPTIME % AVG RESP MS INCIDENT
2026-09-07 100.00 398 -
2026-09-06 99.12 455 yes
...
Recent Incidents (1):
2026-09-06T02:14:00Z - 2026-09-06T02:27:00Z (780s): connection refused
```
## Notifications for this Build [#notifications-for-this-build]
```console
bworlds build notifications storefront --window 7
```
This reads notifications associated with `storefront` only. The Build route does not expose Builder-wide or Build-less administration notifications. Filter by `--workflow` when you are tracing one notification workflow.
## Record what you found as a Finding [#record-what-you-found-as-a-finding]
When the investigation yields something durable, write it where the Builder and the next operator will see it: a Finding, with why it matters and the concrete steps.
```console
bworlds findings create storefront \
--service-line run \
--area operations \
--severity high \
--title "Checkout fails silently when /api/leads returns 500" \
--description "Since 2026-09-06, 12 sessions hit a 500 on /api/leads. The button stays enabled and shows nothing." \
--rationale "Customers abandon checkout without knowing it failed, and nobody is alerted." \
--steps "Surface the terminal error state on the checkout button" \
--steps "Log and alert on 5xx responses from /api/leads" \
--confirm
```
```text
Finding 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b created for build "storefront".
```
The Finding appears on the Build's **Findings** screen with you as reporter. Add `--ai-prompt` to hand the Builder a ready-made prompt for their coding tool, and `--source-ref` to give a recurring check a stable identifier so it never files the same Finding twice.
Follow it through its lifecycle in [Shared memory](./shared-memory).
# Fix in the repository (/docs/guides/repository)
When the Builder connected their GitHub repository, the CLI works on it for you with a short-lived credential scoped to that one repository. During normal CLI use, the credential stays out of saved Git configuration and command output.
## Clone [#clone]
```console
bworlds repo clone storefront
```
```text
Cloning storefront into /tmp/bworlds-cli-storefront...
Repo cloned to /tmp/bworlds-cli-storefront
```
The clone is a temporary directory the CLI manages. Work there, or point your coding agent at it. Pull the latest changes later with `bworlds repo refresh storefront`. Before fetching, the CLI checks that the remote still matches the repository the server authorized.
## Reproduce locally on the Build's data [#reproduce-locally-on-the-builds-data]
Many production problems only show with data shaped like production. For Supabase-based Builds, the CLI brings up a local Supabase instance seeded with the Build's shared fixture:
```console
bworlds repo local-setup storefront
```
```text
Local instance ready for storefront:
API: http://127.0.0.1:54321
Studio: http://127.0.0.1:54323
Users: admin@local.test, user@local.test, user2@local.test (password: demo1234)
Env: /tmp/bworlds-cli-storefront/.env.local
When done: bworlds repo local-teardown storefront
```
It needs `git`, the Supabase CLI, and `psql` on your machine, and a `supabase/config.toml` in the repository. When no seed has been stored for the Build, the local users are created and no data is seeded. `local-teardown` stops the instance and restores the files setup touched, so the clone is clean for pushing.
## Push under your name [#push-under-your-name]
```console
bworlds repo push storefront --message "fix(checkout): surface /api/leads failures" --confirm
```
```text
Pushed changes for storefront
```
The CLI stages, commits, and pushes, requesting write access for this one operation. When it creates a new commit, that commit is authored by the BWorlds GitHub App and carries your BWorlds handle and identity in trailers. Commit hooks run without the credential in their environment, and the final push skips `pre-push` hooks for the same reason. Run your own pre-push checks before the command.
If the push fails after the local commit exists, rerun the same command with `--confirm`. The CLI detects the pending commit and pushes it without committing twice. It preserves that existing commit's metadata, so the actor trailers are guaranteed only when the CLI created the commit. Using a repository credential directly is outside the CLI's attribution guarantees.
## Clean up [#clean-up]
```console
bworlds repo clean storefront --confirm
```
This removes only the CLI-managed clone. Your Dossier workspace and credentials are untouched.
## Boundaries [#boundaries]
* The CLI attaches to no other folder. Use its clone.
* The credential lives in the process only. It never lands in `remote.origin.url`, Git config, or output.
* `--confirm` is the CLI's local safety check. The server separately authorizes issuance of the repository credential from your identity and current Workspace access.
* Keep Git tracing off (`GIT_TRACE`, `GIT_TRACE_CURL`, `GIT_CURL_VERBOSE`) around these commands.
* Repository operations cost no tokens. They change the Builder's repository, so get their authorization before `repo push`.
# Shared memory (/docs/guides/shared-memory)
Two things outlive a session on a Build. The Findings say what needs attention. The Dossier says how this Build works and what never to touch. Both live on the server, under the identity that wrote them.
## Findings: the Build's to-do list [#findings-the-builds-to-do-list]
```console
bworlds findings list storefront
```
```text
ID STATUS SEVERITY AREA TITLE
5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b open high operations Checkout fails silently when /api/leads returns 500
2a41f0e9-7d6c-4b5a-9e8f-3c2d1b0a9f8e needs_user medium security Rate limiting: confirm the Cloudflare rule covers /api/*
c09b8a7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d resolved high security Database is open to the public
```
Move a Finding as work happens. The reason you give becomes part of its history in the app:
```console
bworlds findings update-status storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b in_progress \
--reason "Fix in review on branch fix/checkout-errors" \
--confirm
bworlds findings update-status storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b resolved \
--reason "Shipped in 2f8a1c0, verified in production" \
--confirm
```
Use `needs_user` when only the Builder can move it forward, and say what you need from them:
```console
bworlds findings update-status storefront 2a41f0e9-7d6c-4b5a-9e8f-3c2d1b0a9f8e needs_user \
--decision-summary "Confirm whether the Cloudflare rate-limit rule also covers /api/webhooks" \
--confirm
```
Statuses are `open`, `needs_user`, `in_progress`, `resolved`, and `dismissed`. Their meaning is in the [Product model](../concepts/product-model#finding). Creating a Finding is covered in [Production evidence](./production#record-what-you-found-as-a-finding).
Edit content and inspect attributed activity through the same Build-scoped surface:
```console
bworlds findings edit storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b \
--severity medium \
--confirm
bworlds findings history storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b
```
Both commands resolve the Finding inside the named Build. A direct Finding ID never grants access outside the Build's Workspace.
## Dossier: context and guardrails [#dossier-context-and-guardrails]
```console
bworlds dossier pull storefront
```
```text
Workspace: /Users/lea/.local/share/bworlds/prod/storefront
Pulled context (4812 bytes, updated 2026-09-02T16:40:11Z by maxime)
Pulled guardrails (1290 bytes, updated 2026-09-02T16:40:11Z by maxime)
```
Read `context.md` and `guardrails.md` before changing anything, and have your agent read them too. When nobody has written a Dossier yet, the pull succeeds with a notice. That is the normal state of a fresh Build.
Edit the files, then publish:
```console
bworlds dossier push storefront --confirm
```
```text
Pushed context (5104 bytes)
Pushed guardrails (1290 bytes)
```
What keeps the Dossier trustworthy:
* Pull at the start of a session, push right after you edit. The server is the source of truth and the last push wins. Attribution shows who overwrote what.
* The workspace is outside every clone. Nothing from the Dossier goes into the Builder's repository.
* `context.md` holds how the app works and what matters to its Builder. `guardrails.md` holds what never to touch and what to check before shipping.
# Authentication and tokens (/docs/reference/authentication)
## Sign in from a terminal [#sign-in-from-a-terminal]
```console
bworlds auth login
bworlds auth status
```
The CLI prints a one-time code and an approval URL, then waits. Open that URL on any device where you are already signed in to BWorlds. A local browser is attempted for convenience, but no loopback listener or browser on the CLI machine is required, so the flow works over SSH and in a container.
Any signed-in Builder can approve a code. The resulting Operator Session belongs to that approving Builder; platform administrator access is not required. Approval accepts a web user session only, so a personal CLI token cannot approve another machine. The CLI stores the resulting session in your user configuration directory, readable only by you. `auth status` shows the identity the server sees, its Workspaces, and the number of Builds you can reach. Help works without signing in.
## Create a personal token [#create-a-personal-token]
A BWorlds personal token lets an agent or a runner act as you. It is created from the CLI. It is not a GitHub token and is not copied from any Build setting.
Sign in once from a terminal, then create the token from that session:
```console
bworlds auth login
bworlds auth token create \
--name coding-agent \
--expires-in-days 30 \
--confirm
```
```text
Token ID: 7c1d9e2f-4a5b-4c6d-8e9f-0a1b2c3d4e5f
Expires: 2026-10-07T10:02:41Z
Token: bworlds_pat_...
Store this token now; it cannot be shown again.
```
Put the token in your password manager or your secret store right away. The server keeps only a one-way hash, an identifying prefix, the expiry, and usage timestamps.
Creating, listing, and revoking tokens requires a signed-in user session. A machine token cannot create a replacement or manage your other tokens.
## Use a token [#use-a-token]
For a one-off process, pass it through the environment:
```console
BWORLDS_TOKEN="$SECRET_TOKEN" bworlds auth status --json
```
To store it on a machine without a browser and without putting it in process arguments:
```console
printf '%s\n' "$SECRET_TOKEN" | bworlds auth login --with-token
```
A plain `bworlds auth login` uses the same Device Approval flow on a headless machine: copy the printed code and URL to a device where you are signed in.
## List and revoke [#list-and-revoke]
```console
bworlds auth token list
bworlds auth token revoke CREDENTIAL_ID --confirm
```
Expired and revoked tokens return an authentication error. Being removed from a Workspace also removes that Workspace from every token you hold, immediately.
## Sign out [#sign-out]
```console
bworlds auth logout
```
This deletes the local session on this machine only. Tokens you created stay valid until they expire or you revoke them.
# CLI command reference (/docs/reference/cli)
# CLI command reference [#cli-command-reference]
CLI version: `0.1.0-preview.1`. This page and the machine-readable command index are generated from the Cobra command tree.
## `bworlds` [#bworlds]
**Access:** Command group
Operator CLI for BWORLDS Controls, audits, and repository management
```console
bworlds
```
Subcommands: `audit`, `auth`, `build`, `control`, `dossier`, `findings`, `repo`, `telemetry`.
## `bworlds audit` [#bworlds-audit]
**Access:** Command group
Run and inspect Build audits
```console
bworlds audit
```
Subcommands: `override`, `reevaluate`, `run`, `show`, `status`.
## `bworlds audit override` [#bworlds-audit-override]
**Access:** Command group
Manage operator overrides for Control results
```console
bworlds audit override
```
Subcommands: `clear`, `list`, `set`.
## `bworlds audit override clear` [#bworlds-audit-override-clear]
**Access:** Workspace operator
Clear the active override for a Control
```console
bworlds audit override clear [flags]
```
Flags:
* `--confirm`: confirm clearing the Control result override
* `--json`: Output a stable JSON result
## `bworlds audit override list` [#bworlds-audit-override-list]
**Access:** Workspace operator
List all active overrides for a build
```console
bworlds audit override list [flags]
```
Flags:
* `--json`: Output a stable JSON result
## `bworlds audit override set` [#bworlds-audit-override-set]
**Access:** Workspace operator
Set an operator override for a Control result
```console
bworlds audit override set [flags]
```
Flags:
* `--confirm`: confirm the Control result override
* `--json`: Output a stable JSON result
* `--reason`: Operator justification (required, max 1000 chars)
* `--status`: Overridden verdict: pass, fail, not-applicable, skip
## `bworlds audit reevaluate` [#bworlds-audit-reevaluate]
**Access:** Workspace operator
Reevaluate one metered First Look Control and wait for its result
```console
bworlds audit reevaluate [flags]
```
Flags:
* `--confirm`: confirm the Workspace token charge
* `--json`: Output the final ControlEvaluation as stable JSON
* `--request-id`: UUID idempotency key to reuse when retrying
* `--timeout`: maximum time to wait for the final result (e.g. 60s, 5m, 10m) (default `10m0s`)
## `bworlds audit run` [#bworlds-audit-run]
**Access:** Workspace operator
Run an Audit through the Workspace surface
```console
bworlds audit run [audit-slug] [flags]
```
Flags:
* `--area`: filter the audit to a single area ID
* `--confirm`: confirm the Audit execution and potential Workspace token charge
* `--json`: Output a stable JSON result
* `--no-wait`: start the server-owned audit run and return immediately
* `--request-id`: UUID idempotency key to reuse when retrying
* `--wait-timeout`: override the default 10m wait for the server runner (e.g. 15m, 20m)
## `bworlds audit show` [#bworlds-audit-show]
**Access:** Workspace operator
Show the current Audit results for a Build
```console
bworlds audit show [flags]
```
Flags:
* `--json`: Output a stable JSON result
## `bworlds audit status` [#bworlds-audit-status]
**Access:** Workspace operator
Read the server-owned state of an AuditRun
```console
bworlds audit status [flags]
```
Flags:
* `--json`: Output a stable JSON result
* `--timeout`: request timeout (default `15s`)
## `bworlds auth` [#bworlds-auth]
**Access:** Command group
Manage authentication credentials
```console
bworlds auth
```
Subcommands: `login`, `logout`, `status`, `token`.
## `bworlds auth login` [#bworlds-auth-login]
**Access:** Local utility
Authenticate with the BWORLDS API
```console
bworlds auth login [flags]
```
Flags:
* `--json`: output a stable JSON result
* `--with-token`: read, verify, and store a personal CLI token from stdin
## `bworlds auth logout` [#bworlds-auth-logout]
**Access:** Local utility
Remove saved credentials from this device
```console
bworlds auth logout [flags]
```
Flags:
* `--json`: output a stable JSON result
## `bworlds auth status` [#bworlds-auth-status]
**Access:** Local utility
Verify and show the current identity, Workspaces, and Builds
```console
bworlds auth status [flags]
```
Flags:
* `--json`: output a stable JSON context
## `bworlds auth token` [#bworlds-auth-token]
**Access:** Local utility
Print the Operator Session token or manage personal tokens
```console
bworlds auth token [flags]
```
Subcommands: `create`, `list`, `revoke`.
Flags:
* `--json`: output a stable JSON result
## `bworlds auth token create` [#bworlds-auth-token-create]
**Access:** User session
Create a personal token and reveal it once
```console
bworlds auth token create [flags]
```
Flags:
* `--confirm`: confirm creation of a new credential
* `--expires-in-days`: expiry from now (1-365 days) (default `90`)
* `--json`: output stable JSON
* `--name`: credential name, such as ci-production
## `bworlds auth token list` [#bworlds-auth-token-list]
**Access:** User session
List personal token metadata
```console
bworlds auth token list [flags]
```
Flags:
* `--json`: output stable JSON
## `bworlds auth token revoke` [#bworlds-auth-token-revoke]
**Access:** User session
Revoke one personal token
```console
bworlds auth token revoke [flags]
```
Flags:
* `--confirm`: confirm credential revocation
* `--json`: output stable JSON
## `bworlds build` [#bworlds-build]
**Access:** Command group
Inspect a build's operator-facing state
```console
bworlds build
```
Subcommands: `info`, `notifications`.
## `bworlds build info` [#bworlds-build-info]
**Access:** Workspace operator
Show authorized areas, token balance, and GitHub status for a build
```console
bworlds build info [flags]
```
Flags:
* `--json`: output a stable JSON result
## `bworlds build notifications` [#bworlds-build-notifications]
**Access:** Workspace operator
List the notifications BWorlds sent for a build
```console
bworlds build notifications [flags]
```
Flags:
* `--json`: Output a stable JSON result
* `--limit`: Maximum notifications to read, 1-100 (default `50`)
* `--window`: Days back to read, 1-90 (default `7`)
* `--workflow`: Keep only this workflow key
## `bworlds control` [#bworlds-control]
**Access:** Command group
Run standalone Build Controls
```console
bworlds control
```
Subcommands: `run`, `status`.
## `bworlds control run` [#bworlds-control-run]
**Access:** Workspace operator
Run one Control independently from an Audit
```console
bworlds control run [flags]
```
Flags:
* `--confirm`: confirm the Workspace token charge
* `--json`: Output the final ControlEvaluation as stable JSON
* `--request-id`: UUID idempotency key to reuse when retrying
* `--timeout`: maximum time to wait for the final result (e.g. 60s, 5m, 10m) (default `10m0s`)
## `bworlds control status` [#bworlds-control-status]
**Access:** Workspace operator
Read a ControlEvaluation without starting or charging anything
```console
bworlds control status [flags]
```
Flags:
* `--json`: Output the ControlEvaluation as stable JSON
* `--timeout`: request timeout (default `15s`)
## `bworlds dossier` [#bworlds-dossier]
**Access:** Command group
Sync a build's dossier (operator memory) between the API and the workspace
```console
bworlds dossier
```
Subcommands: `pull`, `push`.
## `bworlds dossier pull` [#bworlds-dossier-pull]
**Access:** Workspace operator
Download the build's dossier into the operator workspace
```console
bworlds dossier pull [flags]
```
Flags:
* `--json`: Output a stable JSON result
## `bworlds dossier push` [#bworlds-dossier-push]
**Access:** Workspace operator
Upload workspace dossier documents to the API
```console
bworlds dossier push [flags]
```
Flags:
* `--confirm`: confirm updating the shared Build Dossier
* `--json`: Output a stable JSON result
## `bworlds findings` [#bworlds-findings]
**Access:** Command group
Manage Build-scoped findings
```console
bworlds findings
```
Subcommands: `autofix`, `create`, `edit`, `history`, `list`, `update-status`.
## `bworlds findings autofix` [#bworlds-findings-autofix]
**Access:** Workspace operator
Start an automatic correction for a Finding
```console
bworlds findings autofix [flags]
```
Flags:
* `--confirm`: confirm the Workspace token cost and repository correction
* `--json`: Output the exact agent job as stable JSON
* `--no-wait`: return once the correction job starts
* `--request-id`: UUID idempotency key to reuse when retrying
* `--timeout`: maximum time to start and follow the correction (e.g. 60s, 5m, 10m) (default `10m0s`)
## `bworlds findings create` [#bworlds-findings-create]
**Access:** Workspace operator
Create an operator finding for a Build
```console
bworlds findings create [flags]
```
Flags:
* `--ai-prompt`: Optional AI fix prompt for the recommendation
* `--area`: Finding area (default `operations`)
* `--confirm`: confirm creating the Finding
* `--description`: Finding description
* `--disposition`: Disposition metadata: restraint
* `--fix-summary`: Recommendation summary label (defaults to "Fix: \")
* `--json`: Output a stable JSON result
* `--rationale`: Why this finding matters (required)
* `--service-line`: Service line: launch, run, improve (default `run`)
* `--severity`: Severity: critical, high, medium (default `medium`)
* `--source-ref`: Stable producer reference (e.g. cto-audit:2026-06-10:rls-missing-orders)
* `--status`: Initial status: open, needs\_user, in\_progress, resolved, dismissed (default `open`)
* `--steps`: How-to-fix step; repeat for multiple (at least one required)
* `--title`: Finding title
## `bworlds findings edit` [#bworlds-findings-edit]
**Access:** Workspace operator
Edit the content of an existing finding
```console
bworlds findings edit <slug> <finding-id> [flags]
```
Flags:
* `--ai-prompt`: AI fix prompt for the recommendation
* `--area`: Finding area
* `--confirm`: confirm editing the Finding
* `--description`: Finding description
* `--fix-summary`: Recommendation summary label
* `--json`: Output a stable JSON result
* `--rationale`: Why this finding matters
* `--service-line`: Service line: launch, run, improve
* `--severity`: Severity: critical, high, medium
* `--steps`: How-to-fix step; repeat for multiple, replacing the whole list
* `--title`: Finding title
## `bworlds findings history` [#bworlds-findings-history]
**Access:** Workspace operator
Show a finding's activity history, newest first
```console
bworlds findings history <slug> <finding-id> [flags]
```
Flags:
* `--json`: Output a stable JSON result
* `--limit`: Number of events to list (1-200) (default `50`)
## `bworlds findings list` [#bworlds-findings-list]
**Access:** Workspace operator
List findings for a Build
```console
bworlds findings list <slug> [flags]
```
Flags:
* `--json`: Output a stable JSON result
## `bworlds findings update-status` [#bworlds-findings-update-status]
**Access:** Workspace operator
Update a finding lifecycle status
```console
bworlds findings update-status <slug> <finding-id> <status> [flags]
```
Flags:
* `--confirm`: confirm the Finding status change
* `--decision-summary`: What the builder must do or provide (required when setting needs\_user without an existing decision)
* `--json`: Output a stable JSON result
* `--reason`: Operator note for the status change
## `bworlds repo` [#bworlds-repo]
**Access:** Command group
Manage build repositories
```console
bworlds repo
```
Subcommands: `clean`, `clone`, `list`, `local-setup`, `local-teardown`, `push`, `refresh`.
## `bworlds repo clean` [#bworlds-repo-clean]
**Access:** Local utility
Remove the local temp directory for a cloned build
```console
bworlds repo clean <slug> [flags]
```
Flags:
* `--confirm`: confirm removal of the local clone
* `--json`: output a stable JSON result
## `bworlds repo clone` [#bworlds-repo-clone]
**Access:** Workspace operator
Clone a build's repository to a local temp directory
```console
bworlds repo clone <slug> [flags]
```
Flags:
* `--force`: delete existing clone without prompting
* `--json`: output a stable JSON result
## `bworlds repo list` [#bworlds-repo-list]
**Access:** Workspace operator
List Builds in your current Workspaces
```console
bworlds repo list [search] [flags]
```
Flags:
* `--json, -j`: Output a stable JSON result
* `--wide, -w`: Show full values without truncation
## `bworlds repo local-setup` [#bworlds-repo-local-setup]
**Access:** Workspace operator
Spin up a seeded local Supabase instance for a cloned build
```console
bworlds repo local-setup <slug> [flags]
```
Flags:
* `--json`: output a stable JSON result
## `bworlds repo local-teardown` [#bworlds-repo-local-teardown]
**Access:** Local utility
Stop the local Supabase instance and restore the clone for pushing
```console
bworlds repo local-teardown <slug> [flags]
```
Flags:
* `--json`: output a stable JSON result
## `bworlds repo push` [#bworlds-repo-push]
**Access:** Workspace operator
Stage, commit, and push changes from the local clone
```console
bworlds repo push <slug> [flags]
```
Flags:
* `--confirm`: confirm the repository commit and push
* `--json`: output a stable JSON result
* `--message, -m`: commit message (default `fix: operator-applied changes [bworlds-cli]`)
## `bworlds repo refresh` [#bworlds-repo-refresh]
**Access:** Workspace operator
Fetch latest changes with a fresh repository credential
```console
bworlds repo refresh <slug> [flags]
```
Flags:
* `--json`: output a stable JSON result
## `bworlds telemetry` [#bworlds-telemetry]
**Access:** Command group
Explore build telemetry: errors, sessions, and uptime
```console
bworlds telemetry
```
Subcommands: `errors`, `sessions`, `uptime`.
## `bworlds telemetry errors` [#bworlds-telemetry-errors]
**Access:** Workspace operator
Show grouped client errors for a build
```console
bworlds telemetry errors <slug> [flags]
```
Flags:
* `--json`: Output as JSON
* `--limit`: Maximum error groups to render (default `20`)
* `--url`: Keep only errors whose route or message contains this fragment
* `--window`: Window in days (1-90) (default `7`)
## `bworlds telemetry sessions` [#bworlds-telemetry-sessions]
**Access:** Workspace operator
List sessions or show session detail for a build
```console
bworlds telemetry sessions <slug> [session-id] [flags]
```
Flags:
* `--depth`: Session detail JSON: summary, or full for the whole server record (default `summary`)
* `--failed-only`: Session detail: keep only failed requests
* `--has-errors`: Filter to sessions with errors
* `--has-rage-clicks`: Filter to sessions with rage clicks
* `--include-personal-data`: Include the end user's email address, which is withheld by default
* `--json`: Output as JSON
* `--time-range`: Time range: 24h, 7d, 30d (default `7d`)
## `bworlds telemetry uptime` [#bworlds-telemetry-uptime]
**Access:** Workspace operator
Show uptime status, daily rollups, and incidents for a build
```console
bworlds telemetry uptime <slug> [flags]
```
Flags:
* `--json`: Output a stable JSON result
# Reference (/docs/reference)
* [Installation and updates](./installation): supported targets, checksum verification, pinning a version.
* [Authentication and tokens](./authentication): Device Approval, personal tokens for agents and CI, revocation.
* [Pricing and tokens](./pricing): what costs tokens, who pays, safe retries.
* [Troubleshooting](./troubleshooting): identity, access, billing, network, and repository failures.
* [CLI command reference](./cli): every command and flag, generated for the CLI version shown at its top. Agents read the same catalog at [`/command-reference.json`](/command-reference.json).
## Access labels [#access-labels]
Each command in the reference carries the access the server requires:
* **Workspace operator**: a Builder holding an active Owner or Member Membership in the Build's Workspace. Operator is a usage label, not a separate role. Verified platform administrators are the server-side exception.
* **User session**: an authenticated Builder web/Operator Session. Managing personal tokens refuses a machine token.
* **Local utility**: runs on this machine without Build authorization.
* **Command group**: lists subcommands and performs no action of its own.
The label documents the server contract. The server enforces it on every request.
# Installation and updates (/docs/reference/installation)
## Homebrew on macOS [#homebrew-on-macos]
Homebrew is the recommended path on macOS. It installs the current version and upgrades it with everything else on your machine.
```console
brew install vulk-corp/tap/bworlds
bworlds --version
```
Homebrew verifies the release checksum before it installs. The tap is a public repository that carries the formula only.
Upgrade with the rest of your tools:
```console
brew upgrade
```
A package install cannot write into your home directory, so it installs no skills. The formula prints the commands that add them, and [The skills](#the-skills) explains where they land.
## Installer script [#installer-script]
Use the script on Linux, in automation, and on macOS without Homebrew. Download it from this site, inspect it if your organization requires it, then run it:
```console
curl -fsSLO https://docs.bworlds.co/install.sh
less install.sh
sh install.sh
```
The installer downloads one archive and the release's `checksums.txt`, verifies SHA-256 before extraction, and installs the `bworlds` executable. It supports:
| Operating system | Architecture | Archive suffix |
| ---------------- | ------------- | -------------- |
| macOS | Apple silicon | `darwin-arm64` |
| macOS | Intel | `darwin-amd64` |
| Linux | x86-64 | `linux-amd64` |
It installs into `$HOME/.local/bin` by default and tells you when that directory is not on your `PATH`. Set `BWORLDS_INSTALL_DIR` to choose another directory.
## The skills [#the-skills]
Three skills teach a coding agent how to operate a Build: `bworlds-cli` for the command contract, `bworlds-audit` to audit a Build end to end, and `bworlds-check` for a recurring health check. Install them with the cross-agent skill installer, whichever way you installed the executable:
```console
npx skills add https://docs.bworlds.co/bworlds-cli-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-audit-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-check-SKILL.md -g
```
Each command serves every agent on your machine. It keeps one copy at `$HOME/.agents/skills/<name>/SKILL.md`, which Codex and around twenty other agents read directly, and links that copy into the directory each remaining agent reads, such as `$HOME/.claude/skills/<name>` for Claude Code. Run a command again to move to a newer skill: it replaces that copy in place, so an older version never sits beside it.
Drop `-g` to install into the repository you are working in instead of your home directory.
Without Node, save each published skill, [`bworlds-cli`](/bworlds-cli-SKILL.md), [`bworlds-audit`](/bworlds-audit-SKILL.md) and [`bworlds-check`](/bworlds-check-SKILL.md), as `$HOME/.agents/skills/<name>/SKILL.md`, then link those directories into your agent's own skills directory.
## Pin a version [#pin-a-version]
Homebrew always installs the newest published version. Automation should pin one instead, which the script does:
```console
BWORLDS_VERSION=0.1.0-preview.1 sh install.sh
```
Run `bworlds --version` after installation. The same version appears at the top of the [CLI command reference](./cli) and in the `cliVersion` field of [`/command-reference.json`](/command-reference.json).
## Update [#update]
`brew upgrade bworlds` moves a Homebrew install to the newest published version. With the script, run it again with a newer explicit `BWORLDS_VERSION`; it replaces the executable. Your sign-in survives either path, and the skill commands move the skills. Review the generated reference for the new version before changing the pinned version in automation.
# Pricing and tokens (/docs/reference/pricing)
Reading is free. Running an Audit or checking one Control consumes the same Workspace tokens as the app. A verified platform administrator is exempt by identity, including when using the Workspace route.
## What costs tokens [#what-costs-tokens]
| Command | Tokens | When |
| -------------------------------------------------- | --------------: | ------------------------------------------ |
| `audit run BUILD_SLUG --confirm` | 0 | the Workspace's first First Look run, once |
| `audit run BUILD_SLUG --confirm` | 900 | every later full First Look run |
| `audit run BUILD_SLUG --area AREA_ID --confirm` | 100 to 400 | a later First Look run limited to one area |
| `audit run BUILD_SLUG security --confirm` | 300 | every run |
| `audit run BUILD_SLUG costs --confirm` | 150 | every run |
| `audit run BUILD_SLUG shipping --confirm` | 600 | every run |
| `audit run BUILD_SLUG rights-licenses --confirm` | 300 | every run |
| `audit reevaluate BUILD_SLUG CONTROL_ID --confirm` | 20 or 100 | one First Look Control, after a fix |
| `control run BUILD_SLUG CONTROL_ID --confirm` | 20, 100, or 150 | one Control of any available Audit |
A First Look area run costs 400 tokens for `security`, 200 for `operations` or `legal-compliance`, and 100 for `code-quality`. A single Control costs 20 tokens when a deterministic check settles it, 100 when an agent inspects the live app, and 150 when an agent reads the repository.
Everything else is free: Build info, Findings, Dossier, telemetry, personal token management, and repository operations. Repository pushes cost no tokens and still change the Builder's repository, so they need their own authorization.
## How the charge works [#how-the-charge-works]
* The server checks the Workspace balance before starting. If it cannot cover the run, the command stops with exit code `7` and nothing is charged.
* An Audit run is debited when it starts successfully. The CLI cannot request an exemption; the server derives it from the authenticated identity.
* Only First Look has a free run: the first First Look of the Workspace, full or limited to one area. No other Audit, Build, or repository gets a free run.
* A single-Control check is debited only when it settles on `pass` or `fail`. A check that errors, or that the Builder's answer settles, costs nothing.
* The Audit detail exposes `runCostTokens`; the server recomputes the amount from the registered manifest and requested area.
* `build info` shows the balance as `Token balance`.
## Retrying a paid command [#retrying-a-paid-command]
Every paid command carries a request ID. The CLI prints it on standard error and includes it in the JSON result. If the response is lost, repeat the exact command with the same ID. The server returns the run it already started and never debits twice.
```console
bworlds audit run BUILD_SLUG AUDIT_SLUG \
--confirm \
--request-id 74862134-91e4-41e1-a682-496efae67e18 \
--json
```
# Troubleshooting (/docs/reference/troubleshooting)
## Start with verified context [#start-with-verified-context]
```console
bworlds --version
bworlds auth status
bworlds build info BUILD_SLUG
```
These three commands catch the most common mismatch: a valid identity without the expected Workspace Membership, or the wrong Build slug.
## Identity, access, and target [#identity-access-and-target]
| Exit code | What it means | What to do |
| --------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
| `3` | Session or personal token is missing, expired, or revoked. | Sign in again, or replace the automation secret. |
| `4` | The identity is signed in but lacks the required access. | Check Workspace Membership. Token management needs a user session. |
| `5` | The target is absent or outside your Workspaces. | Check the Build slug and your Memberships. Do not probe other slugs. |
| `7` | The Workspace cannot cover the metered operation. | Stop and ask the Workspace Owner to review tokens. |
The full table, including network and server codes, is in [Agents and automation](../guides/automation#exit-codes).
## A command waits for input in CI [#a-command-waits-for-input-in-ci]
Supply every required argument and `--confirm` flag. Use `--force` when replacing an existing CLI-managed clone. A plain `auth login` prints a Device Approval code and URL even on a headless machine; approve it from a signed-in device. Use `BWORLDS_TOKEN` in CI.
## The Audit stopped reporting [#the-audit-stopped-reporting]
An Audit run belongs to the server. A local timeout or a dropped connection does not cancel it. Read it back by its identifier:
```console
bworlds audit status AUDIT_RUN_ID --json
```
If the start response itself was lost, repeat the start command with the same `--request-id`. The server returns the existing run without charging again.
## Repository access fails [#repository-access-fails]
Confirm that the Build has a connected repository and that the BWorlds GitHub App is authorized on it. Clone and refresh need read access. Push needs write access and `--confirm`.
The CLI rejects repository URLs with embedded credentials and keeps the short-lived credential out of the saved Git remote. Do not enable `GIT_TRACE`, `GIT_TRACE_CURL`, or `GIT_CURL_VERBOSE` around repository commands.
If a push fails after the CLI created the local commit, rerun the same command with `--confirm`. The CLI detects the pending commit, obtains a fresh credential, and pushes without committing twice. It preserves existing commit metadata; actor trailers are guaranteed only on a new commit the CLI creates.
## Documentation and command disagree [#documentation-and-command-disagree]
Compare `bworlds --version` with the version at the top of the [CLI command reference](./cli). Install the matching binary or update the pinned version. Reference drift is checked in CI.