CLI command reference
Generated reference for every bworlds command and flag.
CLI command reference
CLI version: 0.1.0-preview.16. 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: agent, audit, auth, build, control, dossier, findings, telemetry.
bworlds agent
Access: Command group
Give the coding agents on this machine the BWorlds skills
bworlds agentSubcommands: setup, status.
bworlds agent setup
Access: Local utility
Install the skills this binary carries into every coding agent found
bworlds agent setup [flags]Flags:
--agent: install for one coding agent instead of every agent found: claude-code, codex, cursor, gemini-cli, github-copilot, opencode, windsurf--dry-run: report the actions without performing them--force: reinstall, replacing a skill copy another installer left behind--json: Output a stable JSON result--scope: install for every project (home) or this one (project) (defaulthome)
bworlds agent status
Access: Local utility
Report which skills the coding agents on this machine already have
bworlds agent status [flags]Flags:
--agent: report one coding agent instead of every agent found: claude-code, codex, cursor, gemini-cli, github-copilot, opencode, windsurf--json: Output a stable JSON result--scope: report on every project (home) or this one (project) (defaulthome)
bworlds audit
Access: Command group
Run and inspect Build audits
bworlds auditSubcommands: answer, list, override, reevaluate, run, runs, show, status.
bworlds audit answer
Access: Workspace operator
Answer a Control the Workspace settles by declaration
bworlds audit answer <slug> <control-id> <option-id> [flags]Flags:
--audit: Audit holding the Control (defaultfirst-look)--confirm: confirm recording a declaration on the Builder's Audit--json: Output a stable JSON result--request-id: UUID idempotency key to reuse when retrying
bworlds audit list
Access: Workspace operator
List every Audit a Build carries
bworlds audit list <slug> [flags]Flags:
--json: Output a stable JSON result
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 Control of one Audit and wait for its result
bworlds audit reevaluate <slug> <control-id> [audit-slug] [flags]Flags:
--confirm: optional; targeted checks display pricing and start without confirmation--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 credit 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 runs
Access: Workspace operator
List one Audit's recorded runs, newest first
bworlds audit runs <slug> [audit-slug] [flags]Flags:
--json: Output a stable JSON result
bworlds audit show
Access: Workspace operator
Show one Audit's Control results for a Build
bworlds audit show <slug> [audit-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 and maintain Builds in your Workspaces
bworlds buildSubcommands: info, list, notifications, refresh-capture, stack.
bworlds build info
Access: Workspace operator
Show authorized areas, credit balance, and GitHub status for a build
bworlds build info <slug> [flags]Flags:
--json: output a stable JSON result
bworlds build list
Access: Workspace operator
List Builds in your current Workspaces
bworlds build list [search] [flags]Flags:
--json, -j: Output a stable JSON result--wide, -w: Show full values without truncation
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 build refresh-capture
Access: Workspace operator
Refresh a Build's screenshot and app icon from its public URL
bworlds build refresh-capture <slug> [flags]Flags:
--confirm: confirm the Build image update--json: Output a stable JSON result--timeout: maximum time to retrieve and save images (e.g. 60s, 2m) (default2m0s)
bworlds build stack
Access: Workspace operator
Record how a Build is made, as the Builder states it
bworlds build stack <slug> <field> <value> [flags]Flags:
--confirm: confirm recording the Builder's statement on the Build--json: Output a stable JSON result
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: optional; targeted checks display pricing and start without confirmation--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, dismiss, edit, history, list, prompt, show, update-status, verify.
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 credit 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
Record a Finding for a Build under the Workspace's own authority
bworlds findings create <slug> [flags]Flags:
--ai-prompt: Optional AI fix prompt for the recommendation--area: Finding area (defaultoperations)--audit: Associate the Finding with this Audit's current view--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, low (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 dismiss
Access: Workspace operator
Dismiss a Finding that does not apply to the Build
bworlds findings dismiss <slug> <finding-id> [flags]Flags:
--confirm: confirm the Finding dismissal--json: Output a stable JSON result
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, low--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:
--authority: keep only Findings recorded under these authorities: bworlds, workspace--detection: keep only these detections: audit, manual, telemetry--json: Output a stable JSON result--severity: keep only these severities: critical, high, medium, low--stage: keep only these stages: launch, run, improve--status: keep only these statuses: open, needs_user, in_progress, resolved, dismissed
bworlds findings prompt
Access: Workspace operator
Print a Finding's ready-made fix prompt on stdout
bworlds findings prompt <slug> <finding-id>bworlds findings show
Access: Workspace operator
Show one Finding with its remediation content
bworlds findings show <slug> <finding-id> [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 findings verify
Access: Workspace operator
Ask BWorlds to recheck a Finding after a fix
bworlds findings verify <slug> <finding-id> [flags]Flags:
--confirm: optional; targeted checks display pricing and start without confirmation--json: Output the final verification 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 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