# CLI

URL: /code/cli · Id: `page:code/cli`

> npx startup-builder is api.sb in a terminal, for people, scripts, CI and coding agents.

`npx startup-builder` runs every operation from a terminal, a script, or a coding agent, with the same `Noun.verb` names and JSON input as the API. It also drains work: any [Worker](/business/nouns/worker), human or agent, takes [Tasks](/business/nouns/task) from it.

## Sign in
```bash
npx startup-builder login
npx startup-builder whoami
```

`login` opens the browser and stores a key. In CI, set `STARTUP_BUILDER_API_KEY` instead: the CLI uses the key in the environment first, then the stored one. `whoami` prints the identity, namespace, and scopes in use, which answers most access errors before they happen.

## Read
The examples follow `ledgerline.co`, which closes the books each month for small online stores at $149 a month. [Agents](/business/nouns/agent) categorize every [Transaction](/business/nouns/transaction); a human bookkeeper reviews what they cannot.

```bash
npx startup-builder show /
npx startup-builder show /orders --fields '$id,total'
npx startup-builder search "stores with an open close"
```

`show` prints anything at an [api.sb](/code/platform/api-sb) path: the [Startup](/business/nouns/startup) at `/`, a list, a record, or a definition. `search` finds records, [Nouns](/business/nouns/noun), [Verbs](/business/nouns/verb), and docs by keyword or meaning.

## Run any operation
```bash
npx startup-builder schema Order.refund
npx startup-builder do Order.refund --json '{"order":"order_31","amount":{"amount":149,"currency":"USD"},"reason":"Close missed the 5th"}' --try
npx startup-builder do Order.refund --json '{"order":"order_31","amount":{"amount":149,"currency":"USD"},"reason":"Close missed the 5th"}'
```

`do` takes the operation name and its input as one JSON object, the exact body the API takes. `schema` prints that input and the result's shape, so neither a person nor an agent guesses.

`--try`, `--send`, and `--do` pick the [Mode](/business/nouns/mode), and writes default to `--do`. The first command above previews the refund and moves no money. The test environment is the default; `--env live` acts on live, and only with a key that reaches it.

## Scripts and agents
The CLI switches to agent mode when its output is not a terminal, or when `CI`, `CLAUDECODE`, or `CODEX` is set. In agent mode it prints JSON, never prompts, and never opens a browser. A script reads the result from standard output and branches on the exit code:

| Exit code | Meaning |
| --- | --- |
| `0` | The [Action](/business/nouns/action) is `done`, or the read succeeded. |
| `1` | The Action is `failed`, `refused`, or `canceled`. |
| `2` | The command or its input is invalid. |
| `3` | The Action is `pending`, after `--send`. |

A refused Action prints its problem document, with the `fix` and the `next` call. A coding agent reads both and retries without a search.

## The work loop
Work that needs a Worker waits as a Task. Four commands take it, finish it, or hand it back:

```bash
npx startup-builder next
npx startup-builder claim task_88
npx startup-builder done task_88 --json '{"result":{"categorized":14,"flagged":0}}'
npx startup-builder release task_88 --reason "needs the store's March bank statement"
```

`next` prints the next open Task the signed-in Worker's [Role](/business/nouns/role) may take: here, 14 transactions the agent could not categorize. `claim` takes it with a 15-minute lease, so two Workers never do the same work. A lapsed lease returns the Task to the queue.

`done` finishes the Task with a result and resumes the Action that waited on it, so the close continues. `release` hands it back with a reason the next Worker reads first. `pending` lists the Actions the caller started that are still running.

Each command is one Verb, so the loop runs the same on all four [Interfaces](/business/nouns/interface):

| Command | Verb |
| --- | --- |
| `next` | `Task.next`, a read |
| `claim` | [Task.claim](/business/nouns/task/claim) |
| `done` | [Task.complete](/business/nouns/task/complete) |
| `release` | [Task.return](/business/nouns/task/return) |

The bookkeeper and the categorizing agent drain one queue with the same four commands. Once the agent's answers match the bookkeeper's on 95% of a sample, that kind of Task stops reaching a person. The [eval ladder](/agents/autonomy-levels/evals) sets the sample and demotes the agent on any regression.

[create-startups](/code/create-startups) is the command that creates a Startup.