# CLI

`subs` is the command-line front end to the engine. It runs turns locally
against your worker and manages a hosted cloud app.

## Install

```sh
npm install -g @substructure.ai/cli
```

## Running a turn

`subs run` sends one input to the engine, streams the turn, and exits.

```sh
export ANTHROPIC_API_KEY=sk-ant-...
subs run \
    --worker-url http://localhost:4444 \
    --agent my-agent \
    --provider anthropic \
    --output pretty \
    --input '{"type":"client.message","message":{"role":"user","content":"hi"}}'
```

| Flag | Meaning |
| --- | --- |
| `--input` | A `ClientInput` JSON. Required. Its `type` picks submit, resume, or settle. |
| `--agent` | The agent id the worker routes on. |
| `--worker-url` | Where the engine POSTs decisions. Default `http://localhost:3000/agent`. |
| `--session` | Resume a session. Omit to start one; the id is printed. |
| `--provider` | Engine-run LLM provider: `anthropic`, `openai`, or `openrouter`. |
| `--output` | `ag-ui` (default), `jsonl`, or `pretty`. |
| `--db` | SQLite file. Default `data.db`. |

After a turn it prints the command to continue the session.

## Local server

`subs serve` runs the engine as an HTTP server.

```sh
subs serve --dev --provider anthropic --worker-url http://localhost:4444
```

`--dev` disables auth for local use. It also takes `--host`, `--port`, and
`--db`.

## Cloud

Sign in and manage a hosted app.

| Command | Does |
| --- | --- |
| `subs login` / `logout` / `whoami` | Authenticate. |
| `subs apps` | List, create, show, rename, delete apps. |
| `subs keys` | Create and revoke API keys. |
| `subs sessions` | List sessions and stream their events. |
| `subs webhook` | Set the worker URL and signing secret. |
| `subs link` | Pin an org and app in `substructure.toml`. |

## Next

- [Quick start](./10-quick-start.md): the CLI in a full walkthrough.
- [Protocol](./150-protocol.md): the `ClientInput` that `--input` carries.
- [Durability](./110-durability.md): what `data.db` holds.