Agents and 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

Create the token from a signed-in local session, before configuring the agent or runner:

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.

Non-interactive contract

Set every target and authorization explicitly:

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

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

Every command names its fields in camelCase, at every depth of the result. Write one selector shape and reuse it across commands:

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:

{
  "schemaVersion": "2",
  "error": {
    "code": "payment_required",
    "message": "workspace tokens are insufficient for Build \"storefront\": payment required (HTTP 402)",
    "exitCode": 7
  }
}

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 records the exact flags for the documented CLI version.

Exit codes

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:

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

#!/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

Store the personal token as the repository secret BWORLDS_TOKEN. Pin the CLI version and name the Build explicitly:

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:

bworlds auth token list --json
bworlds auth token revoke CREDENTIAL_ID --confirm