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

# CLI Reference

> Every silo command, its flags, and what it writes

Every authoring command is non-interactive, takes `--env <name>`, and accepts `--json` for machine-readable output. All of them exit non-zero on failure.

```bash theme={null}
npx @burn0/silo <command>
```

<Warning>
  Invoke it as `npx @burn0/silo`. An unrelated package named `silo` exists on the public registry, so `npx silo` can fetch and run that instead.
</Warning>

## Environments

| Command                                                  | Purpose                                 |
| -------------------------------------------------------- | --------------------------------------- |
| `init`                                                   | Interactive wizard                      |
| `init <name> [--template blank\|erp\|crm] [--tools a,b]` | Scaffold an environment                 |
| `env validate --env <env>`                               | Check an environment without running it |

```bash theme={null}
npx @burn0/silo init demo --template crm
```

```
Created environment "demo" from CRM at ./.silo/environments/demo
```

`init` also writes `.silo/tsconfig.json` if you do not already have one. It never overwrites an existing config.

See [Templates](/silo/reference/templates) for what each one contains, and [Validation](/silo/environments/validation) for reading validate's findings.

## Data

Raw facts, stored as `data/<name>.json`.

| Command                                                           | Purpose                  |
| ----------------------------------------------------------------- | ------------------------ |
| `data list --env <env>`                                           | Every dataset, with size |
| `data show <name> --env <env>`                                    | Print one dataset        |
| `data add <name> --env <env> (--file <path> \| --data <json>)`    | Create one               |
| `data update <name> --env <env> (--file <path> \| --data <json>)` | Replace one              |
| `data remove <name> --env <env>`                                  | Delete one               |

```bash theme={null}
npx @burn0/silo data add tickets --env demo --file ./seed/tickets.json
npx @burn0/silo data add regions --env demo --data '[{"id":"EU","name":"Europe"}]'
```

More in [Data](/silo/environments/data).

## Tasks

Objectives, stored as `tasks/<id>.json`.

| Command                                                                                                              | Purpose        |
| -------------------------------------------------------------------------------------------------------------------- | -------------- |
| `task list --env <env>`                                                                                              | Every task     |
| `task show <id> --env <env>`                                                                                         | Print one task |
| `task add --env <env> --id <id> --title <t> --instruction <i> --verifier <VER-ID> [--difficulty easy\|medium\|hard]` | Create one     |
| `task update --env <env> --id <id> [--title ...] [--instruction ...]`                                                | Change one     |
| `task remove <id> --env <env>`                                                                                       | Delete one     |

```bash theme={null}
npx @burn0/silo task add --env demo --id TASK-007 \
  --title "Report Priya's open pipeline" \
  --instruction "..." \
  --verifier VER-007 --difficulty easy
```

More in [Tasks](/silo/environments/tasks).

## Tools

TypeScript the agent can call.

| Command                                                                | Purpose                                     |
| ---------------------------------------------------------------------- | ------------------------------------------- |
| `tool list --env <env>`                                                | Every registered tool, with its description |
| `tool add <name> --env <env> [--description <d>] [--state <TypeName>]` | Scaffold and register one                   |

```bash theme={null}
npx @burn0/silo tool add assign_ticket --env demo \
  --description "Assign an open ticket to an available agent."
```

```
Created tools/assign-ticket.ts
Registered assignTicket in tools/index.ts
Next: implement run() in tools/assign-ticket.ts (look for TODO).
```

A snake\_case tool name becomes a kebab-case file and a camelCase export. `--state` overrides the detected state type name, which is only needed if you did not keep it as `State`.

More in [Tools](/silo/environments/tools).

## Verifiers

TypeScript that decides success.

| Command                                                                                | Purpose                       |
| -------------------------------------------------------------------------------------- | ----------------------------- |
| `verifier list --env <env>`                                                            | Every verifier, with its task |
| `verifier add <VER-ID> --env <env> --task <TASK-ID> [--name <n>] [--state <TypeName>]` | Scaffold and register one     |

```bash theme={null}
npx @burn0/silo verifier add VER-007 --env demo --task TASK-007 \
  --name "Priya's open pipeline reported correctly"
```

More in [Verifiers](/silo/environments/verifiers).

## Running

```bash theme={null}
npx @burn0/silo run --env <env> --task <id> [--agent ./silo.agent.ts]
                    [--runs 5] [--max-tool-calls 100] [--timeout-ms 120000]
```

| Flag                   | Default           | Purpose                     |
| ---------------------- | ----------------- | --------------------------- |
| `--env <name>`         | required          | Which environment           |
| `--task <id>`          | required          | Which task                  |
| `--agent <path>`       | `./silo.agent.ts` | Your agent module           |
| `--runs <n>`           | `1`               | Repeat from a fresh world   |
| `--max-tool-calls <n>` | `100`             | Abort after this many calls |
| `--timeout-ms <n>`     | `120000`          | Abort after this long       |

`--runs` repeats the same task from a fresh world each time and reports the pass rate, which is the only honest way to read a non-deterministic agent.

More in [Running a Simulation](/silo/running/simulation).

## Scaffolding never writes logic

`tool add` and `verifier add` generate a **compiling stub** and register it in the barrel. They never write business logic — the stub throws or fails on purpose, so an unimplemented resource can never look like a working one.

Implement the `TODO` they leave behind, then run `env validate`.

## Exit codes and `--json`

Every command exits non-zero on failure and prints a stable error code alongside its message:

```
error: verifier_already_exists: "verifiers/VER-007.ts" already exists in environment "demo".
```

`--json` works on all authoring commands, which is what makes the CLI drivable by a script or a coding agent:

```bash theme={null}
npx @burn0/silo env validate --env demo --json
```

```json theme={null}
{
  "environment": "demo",
  "ok": true,
  "findings": [],
  "counts": { "data": 9, "tasks": 6, "tools": 42, "verifiers": 6 }
}
```

See [Error Codes](/silo/reference/error-codes) for the full list.