BWorlds CLI
Concepts

Security boundaries

What the server enforces, how repository credentials are handled, and which commands ask for confirmation.

Command JSON

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

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.

On this page