run-wb

CLI for workbook.run — create a workbook, load data, query with SQL, fork, and propose changes for human review.

Install

npm install -g run-wb
# or without installing:
npx run-wb create revenue

Quickstart

# Anonymous create — prints url, agent token, and claim link once
npx run-wb create revenue --json

export WB_TOKEN=wbt_...
export WB_WORKBOOK=wb_...

npx run-wb tables
npx run-wb fork
npx run-wb sql "select 1"
npx run-wb propose

Commands talk to production (https://api.workbook.run/v1 and https://{workbook}.vms.workbook.run). Set WB_ENV=staging to target staging. WB_URL and WB_ADMIN_URL replace one host. There is no flag for the environment.

Device login for humans:

npx run-wb login
# open the printed URL, paste the key, Ctrl-D
npx run-wb tables

Connect to an existing workbook

A workbook owner can mint a one-time connect link (…/connect/exk_…) for an agent. run-wb connect redeems it into the saved config and verifies the connection. The link is a secret, so it is read from one of three private channels, in this order, and never from arguments:

1. WB_CONNECT_URL, set in your environment or secret settings.
2. stdin, when piped (for example from a secret manager).
3. A hidden prompt in a terminal. Nothing you paste is echoed.

npx -y run-wb@latest connect
# paste the link at the hidden prompt, then Enter

WB_CONNECT_URL='<link>' npx -y run-wb@latest connect   # or from a secret store

On success the token is saved to ~/.config/wb/config.json (mode 0600, directory 0700) with the workbook as the default, only a redacted preview such as wbt_…<redacted> is printed, and run-wb tables runs to confirm access. --json prints { workbookId, tokenPreview, saved, verified }. No flag prints the raw token.

• The link is single-use and expires after an hour. The first redeem that reaches workbook.run spends it, even if the response is lost on the way back, so there is no automatic retry. If redemption is refused as invalid, expired or already used, ask the owner for a fresh link.
• Malformed input, claim links and invite links are refused before anything is sent, so a bad paste never spends the link.
• If verification fails after the token is saved, the command exits non-zero with token saved; verification failed: ….
• If you used WB_CONNECT_URL, remove it afterwards: it is spent.
• run-wb login refuses connect links and points here.

Credentials

Tokens are read from the WB_TOKEN environment variable, the saved config (run-wb login, which also accepts a piped token), or a connect link — never passed on the command line where shell history and process listings would capture it. The global --token <secret> option still works for older scripts but is deprecated: it prints a warning on stderr and will be removed in the next major release.

Related

• TypeScript SDK: @workbook-run/sdk
• Agent skill: https://workbook.run/SKILL.md

License

MIT