What it is
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. Every command below was RUN, and the output quoted is what came back. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
Orcyx's control surface is an MCP server, which means an agent that cannot speak MCP — a shell script, a CI job, a tool that was never taught the protocol — cannot drive the app at all. The orcyx command closes that gap: it speaks MCP so the caller does not have to.
Help is generated from the same command table the parser uses, so it cannot document a command the parser would reject. That is worth knowing because it makes the output below self-checking rather than transcribed.
$ orcyx --help
The commands
| Command | What it does | Served by |
|---|---|---|
| orcyx status | Is an Orcyx app running, which version, which workspace. | The descriptor and the pane board, then a probe of the server |
| orcyx pane list | Panes in the workspace, their agent and their state. | The pane activity board on disk |
| orcyx pane read | Read a pane's recent output. | MCP tool pane.read |
| orcyx pane send | Type text into a pane. | MCP tool pane.send |
| orcyx memory search | Search the workspace memory vault. | MCP tool memory.search |
| orcyx ledger log | Record a new requirement in the workspace ledger. | MCP tool requirement.log |
| orcyx ledger event | Append an outcome event to a ledger requirement. | MCP tool requirement.event |
Every command takes --json, because the caller this exists for is a program.
status calls no tool, but it does not stop at the descriptor either: once the descriptor looks live it dials the URL and spends the token, because a live process id is not a live listener. Proving the port answers and the token is accepted is the point — that is HOW status can report a rejected token, not something it avoids in order to.
Exit codes
Seven codes. Four of them — 3, 4, 5 and 6 — are the distinct ways the CLI can fail to reach or be served by an app, and they are kept apart because each has a different fix. Collapsing them into one "connection failed" is how an agent retries forever against a problem retrying cannot solve.
| Code | Meaning | What to do |
|---|---|---|
| 0 | ok | — |
| 1 | failed | The app answered and the operation itself failed; read the message. |
| 2 | bad usage | A typo or a missing argument. The CLI suggests the nearest command. |
| 3 | no running app | Start Orcyx — or, as below, its descriptor could not be trusted. |
| 4 | token rejected | The descriptor was found but its token was refused. Re-read it. |
| 5 | version mismatch | The CLI and the app disagree about the tool surface. |
| 6 | unsupported by the running build | The command needs a tool this build does not have. Upgrade. |
What this build could not do
This is the part written from running the thing rather than from its design. On the machine that wrote this page, with Orcyx running, every command that needs the app exited 3 — including status:
orcyx: The MCP endpoint descriptor at <app data>\orcyx\mcp-endpoint.json cannot be trusted: it has no "pid", so it was written by an older Orcyx build and a dead app cannot be told from a live one. Restart the Orcyx app to rewrite it in the current format.
Nothing is broken. The app that was running predates the descriptor format, so the file on disk has no pid in it — and without a pid a descriptor left behind by a dead app is indistinguishable from one written by a live app one second ago. The CLI refuses to guess, names the file, names the missing field, says why it matters and says what to do about it. That refusal is the feature.
Restart Orcyx and the descriptor is rewritten in the current format. Until you do, expect exit 3 from everything that needs the app, and do not read it as "the CLI is broken".
pane send and pane read do not work yet
Separately from the descriptor: these two commands are wired, documented and parsed, and the tools that would serve them do not exist. The running build registers 86 MCP tools and 0 of them are pane tools.
Against a descriptor it can trust, the CLI probes the server's tool list before calling, and refuses by name — "the running Orcyx does not offer the pane.send tool", exit 6 — instead of passing you an opaque protocol error from a method that does not exist. That extra round trip is the difference between a message you can act on and a JSON-RPC code you have to look up.
Exit 6 for these two commands has been reproduced verbatim against a trustworthy descriptor. It could not be reproduced on the machine that wrote this page, because the descriptor check runs first and returns exit 3 before any tool probe happens — which is itself worth knowing: on an older app you will see 3, not 6, and the fix is the app, not the tools.
Treat pane send and pane read as announced but unavailable. A script that depends on them should check for exit 6 and degrade, not assume the commands exist because they appear in --help.
What works with no app at all
- orcyx --help, and --help on any command or group — exit 0. It is rendered from the command table, so it needs nothing running.
- A misspelled command — "orcyx panne list" answers «Unknown command "panne". Did you mean "pane"?» and exits 2.
- An unknown subcommand — "orcyx pane delete x" answers «Unknown subcommand "delete" for "orcyx pane"» and exits 2, pointing at that group's help.
One deliberate omission in that suggester: a command that changes something irreversible is never offered as a did-you-mean. Guessing that a typo meant a destructive command is how an agent destroys something while appearing helpful. Those you type deliberately or not at all.