orch is the command line tool for Orchard. It is a thin layer over the Orchard library: every command loads a .orch file through the same parser, checker, and runtime that a host program would use when it embeds Orchard directly. That means whatever orch run does on your machine is exactly what an embedded session does, with no separate code path to drift out of sync.
The commands fall into a few groups: static analysis (check), compilation to the JSON IR (compile), running an agent (run), formatting (fmt), scaffolding and inspection (new, info, memory, trace), the environment self-check (doctor), and the long-lived trigger server (serve). Every command accepts the global flags -h / --help and -V / --version.
check
Runs static analysis only: it parses the file, type-checks it, and runs the lints, without executing anything. This is the fast feedback loop you run as you write. It reports the same error classes the embedded checker reports, with caret diagnostics that point at the offending span, including the concurrency checks (a future may not escape its scope, an await operand must be a future, and so on).
Usage: orch check <FILE>orch check agent.orchcompile
Lowers the source to the stable, diffable JSON IR. By default it writes the IR to standard output; pass -o to write it to a file. The interpreter runs this same IR, so a compiled artifact behaves identically to running the source directly. Committing the IR alongside the source lets you diff exactly how a source change moves the program.
Usage: orch compile [-o <OUT>] <FILE>The flag:
- -o <OUT>
- Write the IR to
<OUT>instead of standard output.
orch compile -o ir.json agent.orchrun
Runs the agent. With no other flag it opens the agent terminal: an interactive session against the agent's on message handler that streams the model's reply token by token and shows the full pipeline as the agent works, every model call, every tool call and its result, with token counts and a live spinner. Type /to see the agent's skills and tools. Piping the command falls back to clean line output for scripts and CI. Pass -t to run a single one-shot task and print the result, or --skill with a name and key=value arguments to invoke a named skill directly. Runs are offline by default with the mock provider; the same program reaches a real model when its model block names a real provider.
Usage: orch run [-t <TASK>] [--skill <NAME k=v...>] <FILE>The flags:
- -t <TASK>
- Run a single one-shot task instead of opening a chat.
- --skill <NAME k=v...>
- Invoke the named skill with the given key=value arguments.
orch run agent.orch
orch run -t "Summarize my inbox" agent.orch
orch run --skill triage report="disk is full" agent.orchfmt
Rewrites the file in the canonical style, the one true style. There are no options to argue over: orch fmt produces a single, stable layout, so formatting never shows up as noise in a diff. Run it before you commit, or wire it into your editor on save.
Usage: orch fmt <FILE>orch fmt agent.orchnew
Scaffolds a starter agent. It writes a small, runnable .orch file with a model block and a handler, ready to orch run offline. This is the fastest way to go from nothing to a working agent you can edit.
Usage: orch new <NAME>orch new assistantinfo
Shows what an agent can do, read straight from the file: its model, the tools and skills it exposes, its handlers, and the shape of its policy. Use it to get your bearings on an agent you did not write, or to confirm what a delegate loop will have available to it.
Usage: orch info <FILE>orch info agent.orchmemory
Inspects the persistent store for an agent: the durable facts, the state values, and the semantic memory it has accumulated across runs. It is the window into what the agent remembers, which is useful when an agent's behavior depends on something it learned in an earlier turn.
Usage: orch memory <FILE>orch memory agent.orchtrace
Prints a step-by-step log of the last run: the model steps with their token usage and spend, the tool calls with their arguments and results, and the span boundaries of gen and delegate. When a run does not do what you expected, this is where you look first.
Usage: orch trace <FILE>orch trace agent.orchdoctor
Runs an environment self-check: it confirms the toolchain is healthy and reports on the things a run depends on, so you can tell a configuration problem apart from a problem in your agent. It takes no file argument.
Usage: orch doctororch doctorserve
Runs the schedule and file triggers for an agent as a long-lived process. Where orch run handles one task or one chat, orch serve stays up and fires the agent's on schedule and on file handlers as their triggers occur. This is the mode you use for an agent that should react to time or to the filesystem rather than to a person typing.
Usage: orch serve <FILE>orch serve agent.orchTypical workflow
A normal session with Orchard moves through these commands in roughly this order.
orch new assistant # scaffold a starter agent
# edit assistant.orch
orch check assistant.orch # parse, type-check, lint as you write
orch run -t "Say hello" assistant.orch
orch fmt assistant.orch # canonicalize before committing
orch compile -o ir.json assistant.orch
orch serve assistant.orch # run its schedule and file triggersmodel block to a real provider, name, and key; nothing else about the agent or the commands changes. For the constructs these commands operate on, see the language reference.