CLI

The dsrs binary is the .dsrs toolchain: check, fmt, serve. It ships as the dsrs-cli crate; every subcommand is a plain library function (dsrs_cli::check, dsrs_cli::fmt, dsrs_cli::serve), and the binary itself is argument parsing plus process exit codes. All subcommands exit 0 on success and non-zero on failure.

dsrs check qa.dsrs               # parse, validate, print the program summary
dsrs fmt qa.dsrs --write         # rewrite the file in canonical form
dsrs serve qa.dsrs --port 8080   # serve it over HTTP

The toolchain covers the whole journey of a program file: printed from your code, checked, served on another host, and embeddable back into a Rust build.

`dsrs check <program>`

Parses and validates a .dsrs artifact via Program::load_dsrs, running the full pipeline: lex and parse with positions, lowering, Program::validate, hash sealing. This is exactly what Interpreter::load would accept, which makes check a pre-commit gate for a human and a regeneration signal for a model loop. On success it prints one line to stdout: ok: program with the program name, its 16-hex hash, the node, signature, model, and tool counts, and the caps set when non-empty. On failure the parser’s error goes to stderr with the artifact path and a line N, column M: expected ... position, and the exit code is non-zero.

`dsrs fmt <program> [--write]`

Prints (or rewrites) the canonical form of an artifact. The canonical form is Program::to_dsrs, the same text that seals program_hash and that bake writes. Formatting is parse then print, never token shuffling, so an artifact that does not parse does not format.

Flag	Effect
(none)	Prints the canonical text to stdout.
`--write`	Rewrites the file in place, only when the bytes differ. Reports formatted `<path>` or `<path>` already canonical on stderr.

`dsrs serve <program> [flags]`

Serves a .dsrs program over HTTP. Startup is fail-fast, before the port binds: parse, apply the optional overlay (named form, verified against the program’s hash and slot kinds), then Interpreter::load with the grants from --allow. Models are constructed from the artifact configs with secrets from provider environment variables; a QuickJS sandbox is added when none was supplied. Once bound, the address is printed on stderr.

Flag	Default	Meaning
`--host <addr>`	`127.0.0.1`	Bind address.
`--port <n>`	`8080`	Bind port (0 binds an ephemeral port).
`--overlay <path>`	none	Overlay JSON in the named form (`{"<param path>": <value>, ...}`), applied read-through on every run.
`--allow <CAP>`	none	Capability grant, repeatable: `--allow net:search --allow fs:read`. Load is refused (with the missing set printed) when the program’s caps exceed the grants.

Host tools cannot be served: a program declaring a host tool needs an embedding host that supplies the binding (include_program! plus your own code, or a sandboxed js tool instead). The load surfaces that refusal with a hint rather than a bare unbound-tool error.

HTTP endpoints

Endpoint	What it returns
`POST /run`	Body is a JSON object of input fields; the response is `{"output": ...}`. With `?trace=1` (or `?trace=true`) the run executes inside a capture scope and the response adds `"trace_jsonl"`, the exact trace artifact text with `param_ids` attached.
`GET /schema`	The program’s external interface: `{"program", "program_hash", "signature", "types"}`, the main signature and the type table in their serde forms.
`GET /program`	The canonical `.dsrs` text, as `text/plain; charset=utf-8`.
`GET /healthz`	`{"status": "ok"}` plus the program name and hash.

Error responses are always {"error": ...} with the interpreter’s own message: a non-object request body and input-surface rejections are 400, everything else (LM failures, parse failures, budget, routing) is 500.

From code to endpoint

The full workflow: print a program out of your code, check it, format it, serve it.

1. Print the program

Every #[module] exposes program(). Call to_dsrs() on it to get the canonical text, then save it:

let text = qa::program().to_dsrs();
std::fs::write("qa.dsrs", text)?;

One note before serving: a file printed from a #[module] holds a placeholder model line like model default = "unbound:default", because the real model was bound in your code. Open the file and point each model line at a real model, for example:

model default = "openai:gpt-4o-mini"

2. Check it

Errors come with line and column positions, so check works as a pre-commit gate:

dsrs check qa.dsrs
# ok: program `qa` (3f9c...) - 4 nodes, 4 sigs, 1 models, 0 tools

3. Format it

dsrs fmt qa.dsrs           # print the canonical form to stdout
dsrs fmt qa.dsrs --write   # rewrite the file in place

A file that does not parse does not format; fix check errors first.

4. Serve it

dsrs serve qa.dsrs --port 8080

Model API keys come from the usual provider environment variables (for example OPENAI_API_KEY). The flag table above lists --host, --port, --overlay, and --allow.

5. Call it

curl -s localhost:8080/run \
  -H 'content-type: application/json' \
  -d '{"question": "What is DSRs?"}'
# {"output": {"answer": "...", "upper": "..."}}

Add ?trace=1 to POST /run to also get a full trace of the run; the endpoint table above lists /schema, /program, and /healthz.

Capabilities: needs versus allows

The program states what it needs in its caps { ... } block. The host states what it allows with --allow. Serving refuses to start when the program asks for more than the host allows, and it prints the missing set. This is on purpose: a program can never quietly get more access than you granted. Two more refusals to know about:

A program with host holes cannot be served by dsrs serve, because the Rust code lives in the binary that defined it. Embed the program with include_program! instead; see Runtime.
Same story for host tools: the server has no implementation to bind. Sandboxed JavaScript tools serve fine, because their code travels inside the file.

Common mistakes

Serving a file with an unbound placeholder model. Edit the model lines to real models first. Forgetting --allow. If the file declares caps { net:search }, serving without --allow net:search refuses at startup. That is the design working, not a bug. Editing the file by hand and skipping dsrs check. Always check after hand edits. The parser’s error messages carry positions and are meant to be followed.

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

`dsrs check <program>`

`dsrs fmt <program> [--write]`

`dsrs serve <program> [flags]`

HTTP endpoints

From code to endpoint

1. Print the program

2. Check it

3. Format it

4. Serve it

5. Call it

Capabilities: needs versus allows

Common mistakes

See also

​dsrs check <program>

​dsrs fmt <program> [--write]

​dsrs serve <program> [flags]

​HTTP endpoints

​From code to endpoint

​1. Print the program

​2. Check it

​3. Format it

​4. Serve it

​5. Call it

​Capabilities: needs versus allows

​Common mistakes

​See also

`dsrs check <program>`

`dsrs fmt <program> [--write]`

`dsrs serve <program> [flags]`

HTTP endpoints

From code to endpoint

1. Print the program

2. Check it

3. Format it

4. Serve it

5. Call it

Capabilities: needs versus allows

Common mistakes

See also