CLI reference

The maiden binary operates on an agent folder. new creates one; run, serve and eval drive it; tool authors the sandboxed components it can call.

maiden --version prints the version, and maiden help <command> prints usage for one command.

maiden new

Write an agent folder that already works — a sandboxed tool and a passing eval included.

maiden new <dir>

Argument	Default	Description
<dir>	—	Folder to create. Fails rather than overwriting an existing one.

my-agent/
  .gitignore         thread state and tool build output
  agent.toml         model and per-tool policy
  instructions.md    the system prompt
  skills/tone.md     extra guidance appended to it
  tools/greet.wasm   a sandboxed tool, already built
  tools/src/greet/   its source — edit, then `maiden tool build`
  evals/greet.toml   a check that passes with or without a key

Both of these work immediately, with no API key, no network and no toolchain:

maiden new my-agent
maiden run my-agent "greet the world" --mock
maiden eval my-agent --mock

tools/greet.wasm ships prebuilt inside the maiden binary, because compiling it needs cargo-component and a scaffold you can’t run until you install a toolchain isn’t a scaffold. Its source is written alongside it, so maiden tool build greet --dir my-agent reproduces it.

maiden run

Run one agent loop against a message and print the final answer.

maiden run <dir> <message> [options]

Argument / option	Default	Description
<dir>	—	Path to the agent folder.
<message>	—	The user message to send.
--thread <id>	default	Thread to run on. Reusing a thread resumes its durable history.
--mock	off	Use the scripted offline provider — no API key, fully deterministic.
--model <m>	—	Override the model from agent.toml (top agent only; subagents keep their own).
--state <dir>	<dir>/.maiden/state	Where thread snapshots are stored.

The answer is printed to stdout; run metadata (agent name, tool list, turn count) goes to stderr, so you can pipe the answer cleanly.

maiden run examples/echo-agent "echo the phrase hello" --mock

maiden serve

Serve the agent over HTTP with durable per-thread resume. Also starts the agent’s schedules and channels.

maiden serve <dir> [options]

Option	Default	Description
--port <n>	8080	TCP port to bind.
--bind <addr>	127.0.0.1	Bind address. Also settable via the MAIDEN_BIND environment variable.
--mock	off	Scripted offline provider.
--model <m>	—	Override the model from agent.toml.
--state <dir>	<dir>/.maiden/state	Thread snapshot directory.

The server accepts a JSON body and returns either a single JSON response or a stream of Server-Sent Events. See Serve over HTTP and stream for the request and response shapes.

maiden serve examples/echo-agent --port 8080
curl -s localhost:8080 -d '{"thread":"t1","message":"echo hello"}'

maiden eval

Run the agent’s evals (evals/*.toml) and report pass/fail. Exits non-zero if any case fails, so it drops straight into CI. An agent with no evals/ directory is also an error — nothing to check is not the same as checks passed.

maiden eval <dir> [options]

Option	Default	Description
--mock	off	Scripted offline provider — the usual mode for deterministic evals.
--model <m>	—	Override the model from agent.toml.

Evals run against ephemeral state (a fresh temp directory per invocation), so a case never resumes a previous run — every invocation is reproducible.

maiden eval examples/echo-agent --mock
#   ok   echo
# [maiden] 1/1 eval(s) passed

See Write and run evals for the case format.

maiden tool new

Write a complete, buildable tool source under <dir>/tools/src/<name>/, including the tool.wit contract this binary implements.

maiden tool new <name> [options]

Argument / option	Default	Description
<name>	—	Tool name. Lowercase letters, digits, - and _; becomes the tool’s model-facing name.
--dir <dir>	.	The agent folder to create the source in.
--lang <rust|js>	rust	Author in Rust (cargo-component) or JavaScript (jco).

Refuses to overwrite an existing source.

maiden tool new triage-rank --dir my-agent --lang rust

maiden tool build

Compile tool sources into <dir>/tools/*.wasm, where the runtime discovers them.

maiden tool build [name] [options]

Argument / option	Default	Description
[name]	all	Build only this source. Omit to build every source under tools/src/.
--dir <dir>	.	The agent folder.

Requires cargo-component for Rust tools (cargo install cargo-component) and Node.js for JavaScript tools — jco is invoked through npx, so there is nothing to install globally. A missing toolchain is reported as such rather than as a compiler error.

maiden tool build --dir my-agent

See Add a sandboxed tool for the authoring flow.