CLI spec
What npx startup-builder accepts, prints and returns.
npx startup-builder runs any operation from a terminal or a script, and drains work with next, claim, done, and release.
Commands
| Command | Arguments | Does |
|---|---|---|
login | --oidc --scope <namespace> | Signs in through the browser, with a key from the environment, or with --oidc by exchanging a CI runner’s token for a 15-minute one. |
whoami | None. | Prints the signed-in identity, its namespace, and its scopes. |
show | <path> | Prints any record, list, or definition at an api.sb path. |
search | <query> | Searches records, Nouns, Verbs, and docs. |
do | <Noun.verb> --json <input> | Runs one operation and prints its result. |
schema | <Noun.verb> | Prints the input and output schema of an operation. |
next | None. | Prints the next open work item for the signed-in worker. |
claim | <task> | Claims a work item with a 15-minute lease. |
done | <task> --json <result> | Finishes a claimed work item with its result. |
release | <task> --reason <text> | Returns a claimed work item to the queue with a reason. |
pending | None. | Lists pending Actions started by the signed-in identity. |
logs | tail --request <id> --level <level> --route <path> --follow | Prints the logs of the code a Startup runs, by request, level, or route; --follow keeps the stream open. |
listen | <selector> --forward-to <url> | Streams Events as they happen, and forwards each one, signed, to a local URL. |
connect | <account> | Connects an account you hold, such as email or LinkedIn, through the browser, as a Channel in your name. |
dev | None. | Watches the local project and previews each edit as a Change, with every output it recompiles. |
eval | --scenario <scenario> --agent <command> | Runs your agent against a fresh test Startup and grades it on the scenario’s checks. |
clock | advance --by <duration> | In test, moves the namespace’s clock forward; everything due in between fires in order. |
trigger | <Event> | In test, runs the Verbs that produce an Event, so a receiver gets a real delivery. |
keys | create | roll | revoke --name <text> --scope <namespace> --verbs <a, | Creates, rolls, and revokes keys; a scope only narrows. |
Every operation runs as do <Noun.verb>.
Flags
| Flag | Value | Description |
|---|---|---|
--json | <object> | The input, as one JSON object. |
--try | None. | Runs in Mode try: waits, stores nothing. |
--send | None. | Runs in Mode send: returns the pending Action at once. |
--do | None. | Runs in Mode do: waits for the Action to finish. The default for writes. |
--namespace | <domain> | The Startup to act in. Defaults to the key namespace. |
--env | test | live | The environment. Defaults to test. |
--output | json | md | text | The output format. Agent mode defaults to json. |
--fields | <a, | Prints only these fields of the result. |
--idempotency-key | <key> | Repeats with the same key return the first Action. |
Agent mode
The CLI runs in agent mode when its output is not a terminal, or when CI, CLAUDECODE, or CODEX is set. Agent mode prints JSON, never prompts, and never opens a browser.
Output
do prints the response body the API returns for the same call, so one jq path reads a result from either. A script passes a returned id to the next command:
OFFER=$(npx startup-builder do Offer.create --json '{"price":get, update and delete take the record as id; every other Verb takes it by its Noun. The API spec has the rule.
Authentication
The CLI uses the first key it finds: STARTUP_BUILDER_API_KEY, then the credentials login stored. whoami prints the identity in use.
The work loop
Any worker, human or agent, drains work with four commands.
npx startup-builder next --output json
npx startup-builder claim task_1
npx startup-builder done task_1 --json '{"result":Exit codes
| Code | Meaning |
|---|---|
0 | The Action is done, or the read succeeded. |
1 | The Action is failed, refused, or canceled. |
2 | The input or the command is invalid. |
3 | The Action is pending (with --send). |