# CLI spec

URL: /code/cli/spec · Id: `page:code/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,b> --expire-in <duration>` | 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,b>` | 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:

```bash
OFFER=$(npx startup-builder do Offer.create --json '{"price":{"amount":29,"currency":"USD"},"interval":"month"}' | jq -r '.offer["$id"] | split("/") | last')
npx startup-builder do Offer.publish --json '{"offer":"'"$OFFER"'"}'
```

`get`, `update` and `delete` take the record as `id`; every other Verb takes it by its Noun. The [API spec](/code/api/spec#ids) 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.

```bash
npx startup-builder next --output json
npx startup-builder claim task_1
npx startup-builder done task_1 --json '{"result":"…"}'
npx startup-builder release task_1 --reason "needs input"
```

### 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). |