CLI command reference
Generated reference for every bworlds command and flag.
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
Access: Command group
Operator CLI for BWORLDS Controls, audits, and repository management
bworldsSubcommands: audit, auth, build, control, dossier, findings, repo, telemetry.
bworlds audit
Access: Command group
Run and inspect Build audits
bworlds auditSubcommands: override, reevaluate, run, show, status.
bworlds audit override
Access: Command group
Manage operator overrides for Control results
bworlds audit overrideSubcommands: clear, list, set.
bworlds audit override clear
Access: Workspace operator
Clear the active override for a Control
bworlds audit override clear <slug> <control-id> [flags]Flags:
--confirm: confirm clearing the Control result override--json: Output a stable JSON result
bworlds audit override list
Access: Workspace operator
List all active overrides for a build
bworlds audit override list <slug> [flags]Flags:
--json: Output a stable JSON result
bworlds audit override set
Access: Workspace operator
Set an operator override for a Control result
bworlds audit override set <slug> <control-id> [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
Access: Workspace operator
Reevaluate one metered First Look Control and wait for its result
bworlds audit reevaluate <slug> <control-id> [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) (default10m0s)
bworlds audit run
Access: Workspace operator
Run an Audit through the Workspace surface
bworlds audit run <build-slug> [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
Access: Workspace operator
Show the current Audit results for a Build
bworlds audit show <slug> [flags]Flags:
--json: Output a stable JSON result
bworlds audit status
Access: Workspace operator
Read the server-owned state of an AuditRun
bworlds audit status <audit-run-id> [flags]Flags:
--json: Output a stable JSON result--timeout: request timeout (default15s)
bworlds auth
Access: Command group
Manage authentication credentials
bworlds authSubcommands: login, logout, status, token.
bworlds auth login
Access: Local utility
Authenticate with the BWORLDS API
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
Access: Local utility
Remove saved credentials from this device
bworlds auth logout [flags]Flags:
--json: output a stable JSON result
bworlds auth status
Access: Local utility
Verify and show the current identity, Workspaces, and Builds
bworlds auth status [flags]Flags:
--json: output a stable JSON context
bworlds auth token
Access: Local utility
Print the Operator Session token or manage personal tokens
bworlds auth token [flags]Subcommands: create, list, revoke.
Flags:
--json: output a stable JSON result
bworlds auth token create
Access: User session
Create a personal token and reveal it once
bworlds auth token create [flags]Flags:
--confirm: confirm creation of a new credential--expires-in-days: expiry from now (1-365 days) (default90)--json: output stable JSON--name: credential name, such as ci-production
bworlds auth token list
Access: User session
List personal token metadata
bworlds auth token list [flags]Flags:
--json: output stable JSON
bworlds auth token revoke
Access: User session
Revoke one personal token
bworlds auth token revoke <credential-id> [flags]Flags:
--confirm: confirm credential revocation--json: output stable JSON
bworlds build
Access: Command group
Inspect a build's operator-facing state
bworlds buildSubcommands: info, notifications.
bworlds build info
Access: Workspace operator
Show authorized areas, token balance, and GitHub status for a build
bworlds build info <slug> [flags]Flags:
--json: output a stable JSON result
bworlds build notifications
Access: Workspace operator
List the notifications BWorlds sent for a build
bworlds build notifications <slug> [flags]Flags:
--json: Output a stable JSON result--limit: Maximum notifications to read, 1-100 (default50)--window: Days back to read, 1-90 (default7)--workflow: Keep only this workflow key
bworlds control
Access: Command group
Run standalone Build Controls
bworlds controlSubcommands: run, status.
bworlds control run
Access: Workspace operator
Run one Control independently from an Audit
bworlds control run <build> <control> [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) (default10m0s)
bworlds control status
Access: Workspace operator
Read a ControlEvaluation without starting or charging anything
bworlds control status <build> <evaluation-id> [flags]Flags:
--json: Output the ControlEvaluation as stable JSON--timeout: request timeout (default15s)
bworlds dossier
Access: Command group
Sync a build's dossier (operator memory) between the API and the workspace
bworlds dossierSubcommands: pull, push.
bworlds dossier pull
Access: Workspace operator
Download the build's dossier into the operator workspace
bworlds dossier pull <slug> [flags]Flags:
--json: Output a stable JSON result
bworlds dossier push
Access: Workspace operator
Upload workspace dossier documents to the API
bworlds dossier push <slug> [flags]Flags:
--confirm: confirm updating the shared Build Dossier--json: Output a stable JSON result
bworlds findings
Access: Command group
Manage Build-scoped findings
bworlds findingsSubcommands: autofix, create, edit, history, list, update-status.
bworlds findings autofix
Access: Workspace operator
Start an automatic correction for a Finding
bworlds findings autofix <build> <finding-id> [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) (default10m0s)
bworlds findings create
Access: Workspace operator
Create an operator finding for a Build
bworlds findings create <slug> [flags]Flags:
--ai-prompt: Optional AI fix prompt for the recommendation--area: Finding area (defaultoperations)--confirm: confirm creating the Finding--description: Finding description--disposition: Disposition metadata: restraint--fix-summary: Recommendation summary label (defaults to "Fix: <title>")--json: Output a stable JSON result--rationale: Why this finding matters (required)--service-line: Service line: launch, run, improve (defaultrun)--severity: Severity: critical, high, medium (defaultmedium)--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 (defaultopen)--steps: How-to-fix step; repeat for multiple (at least one required)--title: Finding title
bworlds findings edit
Access: Workspace operator
Edit the content of an existing finding
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
Access: Workspace operator
Show a finding's activity history, newest first
bworlds findings history <slug> <finding-id> [flags]Flags:
--json: Output a stable JSON result--limit: Number of events to list (1-200) (default50)
bworlds findings list
Access: Workspace operator
List findings for a Build
bworlds findings list <slug> [flags]Flags:
--json: Output a stable JSON result
bworlds findings update-status
Access: Workspace operator
Update a finding lifecycle status
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
Access: Command group
Manage build repositories
bworlds repoSubcommands: clean, clone, list, local-setup, local-teardown, push, refresh.
bworlds repo clean
Access: Local utility
Remove the local temp directory for a cloned build
bworlds repo clean <slug> [flags]Flags:
--confirm: confirm removal of the local clone--json: output a stable JSON result
bworlds repo clone
Access: Workspace operator
Clone a build's repository to a local temp directory
bworlds repo clone <slug> [flags]Flags:
--force: delete existing clone without prompting--json: output a stable JSON result
bworlds repo list
Access: Workspace operator
List Builds in your current Workspaces
bworlds repo list [search] [flags]Flags:
--json, -j: Output a stable JSON result--wide, -w: Show full values without truncation
bworlds repo local-setup
Access: Workspace operator
Spin up a seeded local Supabase instance for a cloned build
bworlds repo local-setup <slug> [flags]Flags:
--json: output a stable JSON result
bworlds repo local-teardown
Access: Local utility
Stop the local Supabase instance and restore the clone for pushing
bworlds repo local-teardown <slug> [flags]Flags:
--json: output a stable JSON result
bworlds repo push
Access: Workspace operator
Stage, commit, and push changes from the local clone
bworlds repo push <slug> [flags]Flags:
--confirm: confirm the repository commit and push--json: output a stable JSON result--message, -m: commit message (defaultfix: operator-applied changes [bworlds-cli])
bworlds repo refresh
Access: Workspace operator
Fetch latest changes with a fresh repository credential
bworlds repo refresh <slug> [flags]Flags:
--json: output a stable JSON result
bworlds telemetry
Access: Command group
Explore build telemetry: errors, sessions, and uptime
bworlds telemetrySubcommands: errors, sessions, uptime.
bworlds telemetry errors
Access: Workspace operator
Show grouped client errors for a build
bworlds telemetry errors <slug> [flags]Flags:
--json: Output as JSON--limit: Maximum error groups to render (default20)--url: Keep only errors whose route or message contains this fragment--window: Window in days (1-90) (default7)
bworlds telemetry sessions
Access: Workspace operator
List sessions or show session detail for a build
bworlds telemetry sessions <slug> [session-id] [flags]Flags:
--depth: Session detail JSON: summary, or full for the whole server record (defaultsummary)--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 (default7d)
bworlds telemetry uptime
Access: Workspace operator
Show uptime status, daily rollups, and incidents for a build
bworlds telemetry uptime <slug> [flags]Flags:
--json: Output a stable JSON result