> ## Documentation Index
> Fetch the complete documentation index at: https://lousho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

Installing the package also installs the `lousho` command. It scaffolds
projects, checks your setup, runs an agent locally, serves it over MCP, runs
evals, builds a deployable artifact and launches the Agent Forge dashboard.
Run it with `npx lousho <command>` inside a project that has the SDK installed.

| Command | What it does | Details |
| - | - | - |
| `lousho init [dir]` | Scaffold a project: an agent with an example tool, an offline test, `.env.example`; installs dependencies and runs `git init`. | [Installation](/installation#scaffolding-a-new-project) |
| `lousho doctor [spec] [--json]` | Check Node, peer packages, provider keys, and optionally a spec file; prints a fix for every problem. | [Installation](/installation#troubleshooting-lousho-doctor) |
| `lousho dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI with a session per tab and streamed events, hot reload on save. | [Below](#lousho-dev) |
| `lousho chat <path>` | Terminal REPL for a spec file, an agent directory or a TS agent: streams replies, shows tool calls, asks for approvals and questions. | [Below](#lousho-chat) |
| `lousho acp <path>` | Serve a spec file, an agent directory or a TS agent to an editor (Zed and other ACP clients) over the Agent Client Protocol on stdio. | [ACP](/acp) |
| `lousho add <name>` | Install a tool, skill, channel, schedule or memory slot from a JSON registry into an agent directory, after showing its permission manifest. | [Registry](/registry) |
| `lousho mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [Configuration](/configuration#serve-an-agent-over-mcp) |
| `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](/evals#lousho-eval) |
| `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](/deployment) |
| `lousho studio` | Launch Agent Forge, the visual dashboard, on one local port. | [Agent Forge](/agent-forge) |

Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
`.yml` or `.json`, see [Configuration](/configuration#agent-spec-files-agentspec)).

## Usage

```text theme={null}
lousho init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]
lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--no-schedules]
lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [--session id] [--store sqlite:<file>]
lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run]    (or --list)
lousho build <agent-dir|spec> --target=<name> [--out=<dir>]    (or --agent=<path>)
lousho studio [--port N] [--host H] [--prod|--dev]
lousho mcp <agent.yaml|json> [--http --port N --host H]
lousho doctor [agent.yaml|json] [--json]
lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]]
```

Every command parses its flags the same way (Node's `parseArgs`, strict):
`--flag value` and `--flag=value` both work, the last of a repeated flag wins
(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` prints the
command's usage and exits 0. An unknown flag, a flag without its value (it
never takes the next flag as its value) or an extra argument fails with
`LOUSHO_CONFIG_INVALID` and the usage line. A value that starts with `-` needs
the `=` form: `--model=-x`.

`npm create lousho-agent my-agent` runs `lousho init` with the same arguments.
To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
[Installing from a local build](/installation#installing-from-a-local-build)).

## `lousho dev`

```bash theme={null}
npx lousho dev agent.yaml                  # a spec file
npx lousho dev ./my-agent                  # an agent directory
npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
npx lousho dev ./my-agent --no-schedules   # do not fire the directory's cron schedules
```

For an agent directory, `channels/` are mounted under `/channels` and
`schedules/` are started (and both are swapped on reload, the old schedules
stopped first); `--no-schedules` starts none. See
[Agent directories](/agent-directories#run-it-with-lousho-dev).

Serves a chat UI on `GET /`, `GET /health`, `GET /dev/status` and the chat
endpoints below (1MB body limit). What `<path>` is follows from the path:

| Path | Loaded with |
| - | - |
| `.yaml`, `.yml`, `.json` | `loadSpec()` + `specToAgent()` ([Configuration](/configuration)) |
| a directory | `loadAgentDir()` ([Agent directories](/agent-directories)) |
| `.ts`, `.mts`, `.js`, `.mjs`, `.cjs` | the module's default export, or its `agent` export: a `SimpleAgent` (what `createAgent()` returns) or a `createAgent()` options object |

Any other extension, a missing path, or a module with no agent export fails
with a coded error (`LOUSHO_SPEC_UNSUPPORTED_FORMAT`, `LOUSHO_CONFIG_INVALID`)
and its fix. A `.ts` module is imported by the running Node (22.19 or later
strips types, so relative imports need their file extension); use `.js` for
code that needs a transpiler.

**Chat sessions.** The chat UI keeps one session per browser tab (its id is in
`sessionStorage`; "New session" starts another) and shows the streamed turn:
text as it arrives, tool calls with their arguments and results, errors, and
tokens and cost from `run.done`. A tool call that needs approval shows
Approve / Reject buttons; an `ask_question` call shows its options as buttons
plus a free-text field. The same endpoints work from `curl` or your own page:

| Endpoint | What it does |
| - | - |
| `POST /chat` `{ "sessionId", "input" }` | Runs `agent.session({ id: sessionId }).stream(input)` and streams the turn as SSE: one `data: <AgentEvent JSON>` per event ([Streaming](/streaming)), then `event: done`. History is kept per `sessionId` (1-128 characters of `A-Za-z0-9_-`). |
| `GET /chat/:sessionId` | The session's transcript: `{ sessionId, messages, pending }`; `pending` is `{ status, approvalId? }` while a turn waits on an approval, else `null`. |
| `POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }` | Decides the pending approval (`agent.approvals.resolve()`), or answers a question (`agent.approvals.answer()`), and streams the continued turn as SSE. It can pause again with another `approval.requested`. `404` when `id` is not pending. |
| `POST /chat` `{ "message" }` | Deprecated: no session, no streaming. Returns the agent's `ExecutionResult` as JSON, with a `Deprecation: true` header. |

Sessions live in an in-process `memoryStore()` (gone when `lousho dev` stops),
or in the agent's own `store` when a module's `createAgent()` options set one.
The continuation of an approval is not streamed token by token: the endpoint
runs it with `agent.approvals.resolve()` and sends the turn's tool results and
text as events once it finishes.

`lousho build` servers (`node-server`, `docker`) serve these same endpoints from
the same code, with sessions in a store chosen by `LOUSHO_STORE` and optional
bearer auth: see [Deployment: HTTP API](/deployment#http-api).

**Hot reload.** The agent is rebuilt a moment (100 ms) after a file changes,
without restarting the server or dropping the port:

* a spec: the spec file;
* a directory: everything under it (`instructions.md`, the config file,
  `tools/`, `skills/`, `subagents/`), except `node_modules` and `.git`;
* a module: the file and the local files it imports (relative `import` /
  `require` specifiers, found once at startup; no bundler).

Directory and module files are imported with a `?t=<time>` cache-busting query,
so an edited tool or agent file is re-evaluated. A file *imported by* that file
(a shared helper) stays cached by Node: restart `lousho dev` after editing one.
The console logs what reloaded. The new agent is built (and `ready()`, so MCP
servers connect) before it replaces the old one, and the old one is then
`close()`d. If the rebuild fails, the last good agent keeps answering, the error
is logged and shown in a banner on the chat page (and as `error` in
`GET /dev/status`); the next good edit clears it. Sessions survive a reload: the
store outlives the agent swap, so the next message continues the conversation
on the new agent. An approval that was pending on the old agent is not known to
the new one (`404`); start a new session.

Directories and modules are your code and run with your permissions; only run
`lousho dev` on ones you trust.

* `--port` - default `3737`.
* `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
  to opt in to LAN access.

## `lousho chat`

```bash theme={null}
npx lousho chat agent.yaml                          # a spec file
npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
```

A terminal REPL: each line you type is one turn of a session. `<path>` is
loaded like `lousho dev` loads it (spec file, agent directory or `.ts`/`.js`
module, see [`lousho dev`](#lousho-dev)); a missing path or bad extension fails
with the same coded error (`LOUSHO_CONFIG_INVALID`,
`LOUSHO_SPEC_UNSUPPORTED_FORMAT`), and so does an invalid `--session` id
(`LOUSHO_SESSION_ID_INVALID`).

```text theme={null}
> look up cats
[lookup] {"q":"cats"}
  -> found cats
Cats are great.
[usage] 20 in / 6 out tokens, $0.0004
> email the report to sam
Approve send_email({"to":"sam@example.com"})? [y/N] y
  -> sent
Done, the report is on its way.
```

* Text is written as the model produces it. Each tool call is one dim line,
  `[tool_name] {args}`, followed by `  -> result` (or `  -> error: ...`).
* A tool call that needs approval asks `Approve <tool>(args)? [y/N]`: `y` or
  `yes` runs it, anything else rejects it and the model carries on. An
  `ask_question` call (`askQuestion: true`) prints the question with numbered
  options; answer with the number or with free text.
* After each turn `[usage]` shows the tokens and, when every model used has
  known pricing, the cost (`~` marks estimated tokens).
* Errors from the SDK print with their `[LOUSHO_...]` code and fix, and the
  session continues.

| Command | What it does |
| - | - |
| `/new` | Start a new session (the old one is kept in the store). |
| `/model <provider/model>` | Rebuild the agent on another model; the session continues. A failure keeps the current model. |
| `/compact` | Compact the session's transcript now (old tool results are pruned) and print the before/after size. |
| `/clear` | Empty the session's transcript; the session id stays. |
| `/history` | Print the session's transcript. |
| `/quit` | Leave (Ctrl-D works too). |

| Option | Meaning |
| - | - |
| `--model provider/model` | Use this model instead of the one the target names. Applies to spec files, agent directories and `createAgent()` options exports; a module that exports an already built agent keeps its model. |
| `--session id` | Open this session (1-128 characters of `A-Za-z0-9_-`); default is a new `chat-<id>`. |
| `--store sqlite:<file>` | Keep sessions in a SQLite file ([`SqliteStore`](/durable-execution)), so `--session id` continues a conversation after a restart. Default: in memory. Pending approvals are not restored after a restart. |

The REPL itself is `runChatRepl()` in `src/cli/chatRepl.ts`; it takes the
input lines, an output stream and an agent factory, so it can be tested with
scripted lines and a `mockModel` agent and no terminal.

## `lousho build`

```bash theme={null}
npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
```

Writes the artifact to `--out` (default `.lousho/build/<target>`) and prints
the command to run or deploy it. Building needs `tsup`
(`npm install --save-dev tsup`). Targets, the HTTP API they serve and the
Workers limits are in [Deployment](/deployment).

## `lousho studio`

```bash theme={null}
npx lousho studio            # http://127.0.0.1:4750
npx lousho studio --port 5000
```

Starts one local server for the Agent Forge API and UI. Agents and run state
are stored under `.lousho/` in the current directory. See
[Agent Forge](/agent-forge) for the walkthrough.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.