Authentication and tokens

Sign in from a terminal

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

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:

bworlds auth login
bworlds auth token create \
  --name coding-agent \
  --expires-in-days 30 \
  --confirm

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

For a one-off process, pass it through the environment:

BWORLDS_TOKEN="$SECRET_TOKEN" bworlds auth status --json

To store it on a machine without a browser and without putting it in process arguments:

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

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

bworlds auth logout

This deletes the local session on this machine only. Tokens you created stay valid until they expire or you revoke them.