π«π· Version franΓ§aise
orkeon CLI reference
The orkeon command-line tool is the main entry point of the framework: it runs YAML crews and TypeScript scripts (.ork.ts), turns a need in plain words into a crew (the Atelier), scaffolds a configuration, probes LLM providers, drives the RAG subsystem, searches the example use cases, signs e-mail accounts in, lists and signs drive accounts in, writes the editor typings of the scripting DSL, serves its tools to an MCP client, diagnoses an installation, and lists every setting a host reads. It is built from src/scripting/Orkeon.Scripting.Cli and packs as the dotnet tool orkeon:
dotnet tool install --global Orkeon.Scripting.Cli
orkeon doctor
The release binaries and installers (Windows zip/MSI, Debian package, macOS tarballs) also ship the same CLI, self-contained β no .NET SDK required. See Three ways to run Orkeon.
Update the tool with dotnet tool update --global Orkeon.Scripting.Cli. How to update every other channel, and how to follow main between two releases: Update Orkeon.
Exit codes (stable): 0 OK Β· 1 script/config error (missing file, invalid script, validation failure, a setting the host refuses) Β· 2 the run failed β an unexpected runtime error, a service the host could not build at kickoff, or a crew that ran and did not succeed (a task without a final answer, a tripped circuit breaker, a consensus not reached) Β· 75 the run stopped on a question to a human and waits for the answer (EX_TEMPFAIL; neither a success nor a failure: resume it with --resume <id> --input "...", durable human input) Β· 130 cancelled with Ctrl+C. A help asked for (--help, -h, help) exits 0 and prints on stdout (orkeon mcp: on stderr); a usage error β an unknown option, an option without its value, a word too many β exits 1, writes its line on stderr and nothing on stdout. On exit 2 the last stderr line is ERROR: <reason> β the sentence that says why; the exception type and its stack trace are logged only at --verbose 2 (or ORKEON_DEBUG=1). A setting the host refuses β a value it cannot convert or that a rule of its section refuses, a key no section carries, a section or a component's name it does not know (a memory provider, a reranker, a RAG profile, a log level), an LLM profile it cannot build, a settings file it cannot read (named, with the line and the position), an address that is no address (RaggableTree:Embedding:BaseUrl, Telemetry:OtlpEndpoint) β exits 1 with one line naming it, the last on stderr, before the crew loads and before any model is called. Every setting the host reads is judged at its start, whether the run uses it or not β Logging included β, except the e-mail accounts: an account that cannot be read is set aside and reported when it is named (when a setting is refused). The line is ERROR: <reason> for orkeon run on a YAML crew, a crew directory or a declarative .ork.ts, --validate, --list-tools and orkeon mcp serve (an --events jsonl run still closes its stream on run.finished, exitCode 1), orkeon run: <reason> for a procedural script, orkeon forge: <reason> for the forge; ORKEON_DEBUG=1 prints the exception and its stack before it.
The command line. orkeon, orkeon --help, orkeon -h and orkeon help print the command list and exit 0; orkeon <command> --help prints the options of one command. orkeon --version (or orkeon version) prints orkeon <version> β -v is not the version, it is --verbose. orkeon --version --verbose keeps that line and adds a second one, channel: <channel>: the channel this build was installed through, as orkeon doctor names it, for a program to read. The commands are run, quickstart, init, doctor, settings, llm, rag, eval, forge, usecases, email, drive, typings, mcp and runs, matched before anything else β so orkeon settings is the command even in a folder that holds a settings/ directory. The listing ends on two addresses: the documentation site, and the configuration reference that orkeon settings gives offline. The run verb is optional: a first token that starts with -, or that reads as a crew β it holds a / or a \, ends with .ork.ts, .ork.js, .ts, .js, .yaml or .yml, or names an existing file or folder β is handed to orkeon run. Any other word is refused with orkeon: unknown command '<word>' and exit 1.
The argument rule (every command). An option's value is written --option value or --option=value. Attached to a long name, the value is read as written: cut at the first =, a leading -, a leading space and a line break kept; only an empty value (--option=) is refused. Separated, a value starting with - is read as the next option and refused. -- ends the options: every word after it is positional, whatever it looks like. A word no option or value takes is refused before any work, with orkeon <command>: unexpected argument '<word>' and exit 1.
orkeon run
orkeon run <crew.ork.ts | crew.yaml | crew-directory/> [options]
Runs a crew definition and prints its result on stdout. Dispatch is by target type: .yaml/.yml β or a directory holding a multi-file YAML crew (config.yaml + agents/ + tasks/, or the flat crew.yaml/agents.yaml/tasks.yaml triplet), at its root or under its crew/ sub-folder β the team folder forge promote writes, whose crew/ is the definition whatever the root holds: a mount point named agents/ or a scripting entry point (*.ork.ts) beside it is set aside, never read as a crew; one step down, never crew/crew/ β goes to the shared one-shot runner, which prints the crew output under a === Crew Output === banner. Any other file is a script (.ork.ts, .ts, .js), bundled by esbuild and run by Jint, and its source decides the engine (the two shapes): a script that assigns globalThis.crew is a declarative crew definition and goes to the same shared runner as YAML (tasks, process and manager honoured); any other script is procedural β the scripting host runs it and prints its result as JSON. --validate and --list-tools always use the shared runner.
| Option | Description |
|---|---|
-s, --settings <path> |
Path to appsettings.json. Without it, a fallback chain applies (below). |
-m, --mount <spec> |
VFS mount, Docker-style <physical>:<virtual>:<rights>[;sub:rights]. Several mounts go space-separated after one flag (--mount a:/x:ro b:/y:rw) β the parser rejects a repeated --mount. A Windows drive letter needs nothing special (C:\src:/workspace:ro); a path the bare form cannot carry β one containing a : or a ;, or ending with a backslash β is quoted: "/data/odd:name":/data:ro, "C:\src\":/workspace:ro. Those double quotes belong to the mount grammar, so your shell must not eat them: write the whole spec inside single quotes in bash/zsh (--mount '"/data/odd:name":/data:ro') and double the quotes in PowerShell (--mount '""/data/odd:name"":/data:ro'). Backslashes are never escape characters; a " inside a quoted path is doubled ("/data/a""b":/data:ro). The virtual path is always a name starting with / β never a disk path (ADR-008), and /crew (a crew) or /script (a script), /llm-logs, /llm-mock, /llm-cassette, /sandbox, /state, /runs and /credentials are reserved by the runner: a mount claiming one is refused with exit 1, and refused the same way whether it was written here or declared in the settings β in the file, or by a variable, ORKEON_-prefixed or not: the guards read the layers the host reads (where settings are read from), and this one names the roots this command reserves rather than a fixed list. /credentials is reserved by every command: the runner keeps the OAuth tokens of the e-mail and drive accounts there (orkeon email, orkeon drive). orkeon forge reserves only /sandbox: it takes no --mount, mounts /workspace, /forge and /output itself, and places those three against the settings exactly as a --mount is placed (next sentence) β a settings entry on one of them is replaced for the trial, so a settings file naming /output, an ordinary mount for a normal run and the usual name of a team's write folder, forges unchanged. Against the settings, a --mount is placed by virtual root: on a root Orkeon:FileSystem:Mounts already declares (settings file, or environment, prefixed or not β the layers the guards read), the --mount replaces every settings entry of that root for this run β it is written at the first entry's own index, the others are withdrawn, and the log says mount /x: --mount replaces the settings entry; on a new root it is appended after every declared entry. Settings entries no --mount names stay in force. A root is a duplicate only when one source claims it twice and nothing can tell the claims apart: two --mount on the same root (--mount a:/x:ro b:/x:rw), or a settings file declaring one root twice with an entry that carries no id (next row), are refused with exit 1 and one line (ERROR: '/x' is mounted twice on the command line: β¦ Keep one. / β¦ declared twice in <settings> (β¦) and '<entry>' has no id. Give every entry an id β¦) before any host is built. |
--mount-id <ulid> |
Selects, among several settings entries declaring one virtual root, the entry this run keeps. A settings entry may carry an id β the 26-character ULID before its |, 01J9Z3K4M5N6P7Q8R9S0T1V2W3|C:\data:/output:rw; a client may write one on every save β and two entries may share a root only when both carry one. Several ids go space-separated after one flag, like --mount. The entry named is kept as declared (folder, rights); the other entries of its root are withdrawn for the run β not mounted, not whitelisted, their folder not probed. Without the option, the crew's mounts: block (<ulid>|/output, see the YAML schema) selects the same way; with neither, a root declared several times is refused with exit 1 and one line naming every id (ERROR: '/output' is declared twice in <settings> (<idA>: <folderA>, <idB>: <folderB>) and nothing selects one. Pass --mount-id <id>, list '<id>|/output' under mounts: in the crew, or pass --mount <folder>:/output:rw to replace them all.). That line is a crew YAML's: it names only what the command offers to choose with β --mount-id and --mount for a script and --list-tools (Pass --mount-id <id> or pass --mount <folder>:/output:rw to replace them all.), --mount alone for orkeon rag and orkeon-repl, for orkeon forge and orkeon mcp serve, which offer nothing to choose with, no error: the root is withdrawn β no entry of it is mounted for the run β with a warning ('/x' is claimed by <ids> in <settings> and nothing selects one: no entry of it is mounted for this run.), and mcp serve left with no mount at all mounts the working directory at /crew:ro. An id no entry carries, or a malformed one, is refused the same way; a --mount on the same root wins over the option, with a WARNING: line; a root the crew requires that nothing provides is refused too (the crew requires '/output' β¦ pass --mount <folder>:/output:rw). Agents never see an id: list_mounts and the access-denied messages name virtual paths only. |
--allow-external-mounts |
Allow --mount arguments outside the working directory (or ORKEON_ALLOW_EXTERNAL_MOUNTS=1): each such --mount base path is added to the PathSecurity:AdditionalAllowedDirectories whitelist PathValidator checks resolved paths against, after whatever the settings already list there. Without it, a --mount outside the working directory is refused at start, before any model is called: exit 1 for orkeon run and the REPL, one line The mount <root> (<physical>) is outside the directories this run may read: pass --allow-external-mounts (or set ORKEON_ALLOW_EXTERNAL_MOUNTS=1), or mount a folder under the working directory. Nothing implies the flag β not a crew, not rag, not the forge. A mount asks no flag when it is one of the command's inputs: every entry the settings declare and force (one chosen by id with --mount-id included), the folder of a script, the root of a rag corpus. A folder that is itself a symbolic link is whitelisted together with its target, for each base path above and each input. The same flag is asked of a YAML <config> and of an --llm-log-path folder outside the working directory: without it, exit 1 and one ERROR: --allow-external-mounts is required β¦ line naming the path. |
--llm-profile <id> |
Runs on the host LLM profile <id> β Llm:Profiles:<id> in the settings or the ORKEON_ environment (configuration) β as this run's default: the Llm section becomes that profile, whole, for the run. Every field it pins is taken, a field it leaves unset stays unset, and its key comes from the profile (ApiKey, or the variable its ApiKeyEnvVar names), never from the default. Every agent, task and manager that names no profile of its own runs on it, and so does whatever runs on the default β the planner, the RAG when Orkeon:Rag:LlmProfile names none, llm.default_ in a script. The profiles stay offered by name; default elects nothing; the id is matched without regard to case. An id the configuration does not define is refused with exit 1 before any host is built, as a crew naming an unknown profile fails its load: ERROR: --llm-profile names the LLM profile 'x', which this host does not offer. Known profiles: default, deepseek, z-ai. β¦. The startup log says LLM profile <id> elected as the run's default (--llm-profile) and where its key comes from. A client may write it into a team's launchers for the team's model setting. |
--no-decision |
Switches the decision circuit off for this run: decision tasks answer from their fallback. It wins over Orkeon:Decision:Enabled=true in the settings; see Decision models. |
-v, --verbose <0-2> |
0 quiet, 1 agent and tool activity β plus one summary line per LLM exchange (provider, model, status, duration) when --llm-log is on β, 2 full debug; a model answer is a one-line preview (300 characters) at 1 and whole at 2, the run's final answer being printed whole under === Crew Output ===; a value outside 0-2 is clamped to it. The bodies of the exchanges are only in the --llm-log files. Without -v, verbose agents speak (Orkeon.Verbose, Information); a Logging:LogLevel rule naming Orkeon.Verbose or Default wins. |
--llm-log / --llm-log-path <dir> |
Log full LLM exchanges (request and response, headers and payload) as JSONL (default directory ./llm-logs, created if missing); --llm-log-path implies --llm-log. A folder outside the working directory needs --allow-external-mounts. What the files keep is tuned by LlmLogging; no setting chooses the folder. Recipe: follow the run and keep the LLM exchanges. |
--llm-mock <file> |
Answers every LLM call from a JSONL file instead of a model: offline, no network call, the same output on every run. One {"match", "regex"?, "content", "toolCalls"?} object per line; match is looked for, case ignored, in the prompt (the last user message), as a regular expression when "regex": true, and the first line that fits wins. With "regex": true, $1 or ${name} in content are replaced by what the pattern captured ($$ writes a dollar): a manager's answer can name the agent its prompt lists. A line with toolCalls ([{"name", "arguments"}]) answers with those tool calls. The lines that fit one prompt are its script, one line per round: the first answers the prompt, and each round of tool results in the conversation moves on to the next, so two successive tool calls and a final answer are three lines that fit the same prompt; past the last line, a last content line keeps answering and a last toolCalls line fails the call, so a mock never asks for a tool forever. A prompt no line fits, a pattern that times out, or a malformed line (its number is named) fails the call, in a streamed call too; streaming is one chunk. The host logs one warning per mock provider it builds, naming the profile. Every LLM profile of the run β the Llm section and each Llm:Profiles:<name> β becomes Provider: mock reading the file (configuration); the file's folder is mounted read-only at /llm-mock, and may hold neither the crew nor the script (exit 1, one line). The pre-run probe of the endpoint is skipped. |
--llm-record <file> |
Records every LLM call of the run, with its answer, in a JSONL cassette: one line per call, filed under a key (the SHA-256 of the profile, the messages, the system message, the tools and the tool mode, the response format, the model and the sampling options, with timestamps and generated identifiers left out) and an occurrence number for a call repeated. A streamed call is kept as its list of deltas. API keys and authorization headers are redacted. The file is written through the VFS: its folder is mounted read-write at /llm-cassette, may hold neither the crew nor the script (exit 1, one line), and outside the working directory needs --allow-external-mounts. Exclusive with --llm-replay and --llm-mock (exit 1, one line). See Record and replay LLM calls. |
--llm-replay <file> |
Answers every LLM call of the run from a cassette --llm-record wrote, with no network call and no model: the same output as the recorded run. A call the cassette does not hold fails with a ReplayMissException naming the profile, the call number and the prompt, never a fallback on the network; a cassette that does not exist is refused (exit 1). The file's folder is mounted read-only at /llm-cassette. Exclusive with --llm-record and --llm-mock. See Record and replay LLM calls. |
--test |
For a procedural script: binds the global test β test.mockLlm, test.mockTool, test.assertLlmCalled, test.assertToolCalled (scripting DSL). An expectation of test.mockLlm is served before the configured model (or the --llm-mock file); any other prompt goes to it. Without --test the script has no test. A YAML crew, a crew directory, a declarative script and --validate have no such script engine: --test there is refused (exit 1, one line). |
--inputs <json> / --inputs-file <path> |
Structured inputs for a procedural script (the global inputs). A declarative script or a YAML crew ignores them β a declarative script says so on stderr. |
-V, --var KEY=VALUE |
Variable for a YAML crew's CrewInput (task templates {KEY}). Several variables go space-separated after one -V (a repeated flag is rejected). |
--initial-context <text> |
Initial context string for a YAML crew's CrewInput. A text starting with - β a bullet list β is written --initial-context=<text> (the argument rule, above). The team launchers write every single-value option that way. |
--memory-limit-mb <n> |
Jint memory limit for a procedural script (0 disables it). Default: Orkeon:Scripting:Limits:MemoryLimitBytes, 100 MB. |
--validate |
Dry run: resolve settings, build the host, load the crew with strict tool resolution β no LLM call, no kickoff. Prints VALIDATION OK/FAILED: β¦. On a .ork.ts it first type-checks the script with tsc against the typings this build ships (Orkeon:Scripting:Toolchain:TypeCheck, scripting): a type error prints VALIDATION FAILED: type errors, then one <virtual path>:line:col TSxxxx message per error, and exits 1. A procedural .ork.ts (its source never assigns globalThis.crew) is not loaded as a crew: it is type-checked and bundled, never run, and prints VALIDATION OK: <config> (procedural script: bundled, not run). A crew that loads, YAML or .ork.ts, whose task declares a deliverable with source: tool_call (the default) that no agent able to run the task can write prints one line per such task on stderr β WARNING: Task '<name>' declares the deliverable '<path>' (source tool_call), but its agent '<role>' has no tool that writes it (file_write): the file may not be written. Give the agent file_write, or set deliverable.source: final_message., naming every agent the process may pick when there are several; for a binary file it names the format's tool (docx_writer) and proposes a text format instead of final_message, and a decision task that declares a deliverable prints WARNING: Task '<name>' is a decision task: its deliverable '<path>' is never written, β¦ β and the exit code stays 0 (deliverables checked at load). |
--input <answer> |
The answer to the question the resumed run stopped on (exit 75); only with --resume, refused without it (exit 1). The task that asked is replayed and gets the answer, the tasks already done are not run again; the run is refused when it waits for no answer. Without --input, a resumed run that meets the same question stops again with 75. |
--resume <id\|latest> |
Resume a failed or killed run of this crew instead of starting another (checkpoint per task): the tasks it had completed are answered from the checkpoint, the others run, and the run keeps its id. A failed run prints that id (Run <id> did not complete. Resume it, its finished tasks kept, with: orkeon run <crew> --resume <id>); latest is the crew file's most recent run that is not completed; a run still marked Running is refused (it may be alive in another process): name its id to take it over. A task edited since is run again, with every task after it. Needs Orkeon:Checkpointing:Enabled=true (refused otherwise, exit 1); refused with --validate, --list-tools and a procedural .ork.ts; with --events it needs the explicit id, not latest. Manager decisions of a Hierarchical or Autonomous crew are replayed live. |
--list-tools |
Build the host, print the sorted runtime tool registry, exit. No crew path needed. |
--events jsonl |
Emit the versioned event protocol on stdout instead of the plain rendering, and read commands on stdin. jsonl is the only value; any other is refused with exit 1. This is how a client watches a run. See The run event bus. |
--stream |
With --events, also emit llm.delta events token by token (the text, and the fragments of the tool calls the model builds). Verbose by nature: off unless asked for. |
--client <name> |
With --events, the name the watching process answers to on the run's hub (client://<name>, default client). Agents can post and send to that address; a crew's links: block authorizes it. A name that is empty or holds a / is refused with exit 1; without --events the option has no effect, and a warning says so when the name is not the default client. |
orkeon run examples/01-enterprise/01-research-assistant/config.yaml \
--settings examples/appsettings/appsettings.deepseek.local.json \
--mount ./out:/output:rw -v 1
Settings resolution β when --settings is omitted, the CLI walks a fallback chain: appsettings.json next to the crew file, then an appsettings/appsettings.json found by walking up the parent directories, then the global per-user file written by orkeon init, then ORKEON_* environment variables alone. An explicit --settings naming a file that does not exist ends the chain there β a WARNING: line, then environment variables alone β rather than falling through to the next location. Details and the ready-made profile matrix: Run your first example.
orkeon quickstart
orkeon quickstart # write the two-minute crew into ./orkeon-quickstart/
orkeon quickstart --to demo
Writes the crew of the README's Try it in two minutes into a new folder: crew.yaml (one agent, the file_write tool, one task that writes /output/hello.md), its appsettings.json (Ollama on localhost:11434, qwen2.5:1.5b) and an empty out/. Both files are embedded in the tool, byte for byte from examples/quickstart/, so a dotnet tool install is enough β no clone. --to <dir> (or --to=<dir>) picks the folder (default ./orkeon-quickstart, created when missing). The verb never overwrites: a file, or a folder that is not empty, at that place is refused and nothing is written. It then prints the two runs to make from that folder β orkeon run crew.yaml --mount ./out:/output:rw, which writes out/hello.md, and the same with :ro, which the file-system service refuses (required Write, effective ReadOnly). Offline. Exit codes: 0 written, 1 a file or a non-empty folder at the target, an unknown option or a word too many, or --to without a folder (--to= included).
orkeon forge
orkeon forge "summarize my supplier's new offers every morning" # start from a need
orkeon forge "sort my emails by urgency" --reference 03-email-pipeline # start from a need, modelled on a use case
orkeon forge # start with the interview
orkeon forge list # list the workspace's sessions
orkeon forge rephrase "<request>" # rewrite the request as a clear brief, then exit
orkeon forge resume <slug> # pick a session up exactly where it stopped
orkeon forge resume <slug> --read <dir> # try it on the documents in <dir>
orkeon forge resume <slug> --adopt # keep the team as generated, without a trial
orkeon forge promote <slug> --to <dir> --name <team> # ship a ready session as an ordinary folder, under the team's name
orkeon forge reopen <team-folder> # find β or rebuild from crew/ β the session linked to a promoted team
orkeon forge schedule <team-folder> # install the team's schedule with the system's own scheduler
orkeon forge schedule <team-folder> --check # say whether it is installed, absent or to reinstall
orkeon forge unschedule <team-folder> # remove it, with schedule/ and the forge.json record
orkeon forge rename <team-folder> --name <name> # rename the team: folder, session, titles, schedule β all or nothing
The Atelier: a guided path from a need in plain words to a deployable crew. An assistant interviews you and captures a structured brief β goal, inputs, acceptance criteria, a sample input β then proposes a team plan, renders it, validates it, tries it in a sandbox on your sample, and judges the result against your own criteria. Not conforming? The diagnosis feeds a refine loop, bounded by a hard budget (iterations, tokens, wall time). Every session lives under .orkeon/forge/<slug>/ β resumable, diffable between attempts, auditable.
forge rephrase <request> asks the assistant's LLM to rewrite the request as a clear brief β what comes in, what comes out and in which shape, every rule stated, in the request's language, adding nothing β and exits: no session, nothing written. The request is the words after the verb; --events jsonl answers with one need.rephrased line (text, original), the terminal prints the text; --settings is honoured, every other option refused. No LLM is FORGE-LLM-UNAVAILABLE, an empty answer FORGE-REPHRASE-EMPTY, both exit 1.
The embedding fingerprint. orkeon forge records the embedding fingerprint (the provider, model and dimensions the stored vectors came from) at /forge/embedding-fingerprint.json, a mount it can always write, so a read-only /workspace no longer makes it warn; Orkeon:Embeddings:FingerprintPath overrides that default. The mount lives for one session, so the guard protects a session and nothing across sessions.
The forge's command line. The argument rule above holds, with the forge's own sentences. -- ends the options and what follows is the need (a client writes every option first and the need last, after --). --option=value is read for the long names, cut at the first =; an empty value is refused with the option's own sentence. --events attached takes only jsonl: --events takes only the value jsonl. A flag written with a value is refused: <flag> takes no value. (--auto=true: --auto takes no value.). list takes no argument. and promote and resume take the session slug only: no other word. are the verbs' sentences; every refusal exits 1, an unknown option included.
The folders step. Between the brief and the plan, the forge settles the team's folders. The assistant lists in the brief (folders: path, role input|output, purpose, and examples when the contents change) every folder the need names β Β« β¦PDFs in /inpdf, the Markdown in /outmd Β» β or describes without naming, each then named from what it holds (Β« a folder of PDFs with the instructions, another with the documents to attach Β» β /instructions, /documents), plus one output folder with a purpose that means something for the team (the record of the mails sent, when the result is no file); when the need names or describes none at all the forge proposes /workspace to read β only when the team reads files or documents from a folder, which the brief's readsFiles says; when the assistant did not say, when something comes in β and /output to write, each purpose in the brief's language. A folder is one absolute segment of letters, digits, -, _ or .; /forge and the runner's own roots are refused. A list with no output folder, or no folder at all, is valid: a team that sends mails from what it reads writes no file, no task of its plan has a deliverable, and its result is the run's own output. A folder's purpose is the user's note on what it holds and how the team must use it β a client can let the user edit it before confirming β and the plan prompt tells the assistant to follow it. A folder's examples (a boolean, on an input folder only; true on an output is refused) says that what the folder holds changes from run to run β an inbox the user refills β so the files found in it at the fill step are examples of what will come: the assistant sets it from the need, a client can set it at the confirmation, and absent means fixed material, the plan being made for the very files that are there. The forge then emits folders.proposed (folders, and defaults β true when the request named no folder) and waits for folders.confirmed on stdin ({"kind":"folders.confirmed","folders":[{"path","role","purpose","dir","examples"}]} β the proposal as it is or amended, dir the real directory bound behind a folder, absent for a folder kept inside the team; examples true or false decides, and an input folder sent without it keeps the value the proposal gave the same path, letter case aside, so a renamed folder says it again). A list that breaks the rules, or binds a directory that is not there, is a recoverable FORGE-FOLDERS-INVALID and the folders are proposed again. So is, when the run tries the team in this same process (no --dry), an input bound to a directory the run's file tools do not allow β one outside the working directory: those tools keep the directories they started with, so the folder would be mounted for the try and refused on every read. The message says the way that works: confirm the folders in a run that stops before its try (orkeon forge resume <slug> --dry), then orkeon forge resume <slug>, whose host mounts and allows them from its start. In the terminal, and with --auto, the proposal is taken as it is and printed, a folder whose contents change marked as such. The confirmed list is kept in the session's folders.json (with the directories) and in the brief (without them β a physical path never reaches a prompt), announced by brief.ready β whose heldFolders (path, role, dir) are the folders kept inside the team, each created now under the session's folders/<name> so files can be dropped in it before the try; the terminal prints them β and used everywhere after: the plan's deliverables must land in a confirmed output folder (FORGE-BLUEPRINT-INVALID / repair otherwise), and a task that names a path under an output folder a deliverable lands in, in its description or expected output, must name its own deliverable, the deliverable of one of its dependencies (transitively), or a file already present under an output folder β every file found recursively under a folder the team holds or that is bound to a user dir, up to 10 000 per folder, with no 40-entry cap; being listed earlier is not enough, whatever the process, a reader lists its writer (the hand-off rule) β otherwise the plan is refused with an error naming the task and the path, which the assistant gets back to fix (the same check runs on a verdict edit and at the Blueprint stage; reopen reads a crew promoted before the rule without it, and the next validation enforces it) β the same rule reads each agent's goal and backstory: a path under a deliverable root named there must be a deliverable of one of the agent's tasks, of a task they depend on, or an existing file, and an agent with no task (a manager, an arbiter) may name any task's deliverable, as may any agent of a hierarchical, consensual or autonomous crew (sequential, parallel, graph and an unset process keep the per-agent rule; a path that no task delivers and no existing file holds is refused in every mode); a path that is a folder is accepted when an allowed deliverable or an existing file lies under it, for tasks and agents alike; the refusal names agents[i] ('key'), the field (goal or backstory) and the path, and the remedy is to remove the path from the goal or the backstory, to give the agent the task that writes it, or a dependency on that task; reopen does not apply the rule β, the crew's mounts: block names the list, the try mounts it, and the promotion carries it. A session stopped at the question asks it again on resume, without a new interview.
The fill step. When the confirmed list holds folders kept inside the team, the forge waits after brief.ready for folders.filled on stdin ({"kind":"folders.filled"}: the files are in place, or there is nothing to drop) and designs nothing before it β the terminal asks for Enter, --auto does not wait. It then reads what each held folder holds and adds it to the brief as the folder's contents (names relative to the folder, a sub-folder ending with /, at most 40, the last one counting the rest; never a physical path), which the plan prompt names so the tasks are made for those files. For a folder whose examples is true the prompt presents the same names as examples that will be replaced: the tasks are designed for whatever the folder holds when the team runs, no task, goal or backstory names one of them, and the brief sent with the prompt leaves that folder's contents and large out (advice in the prompt: no validation refuses a plan that names an example). A file of 128 KiB or more (any depth, largest first, within the same cap), in a held folder or in a folder bound to a user dir, is named with its size (report.md (750 KB)), and the plan prompt adds the rules for reading one: search first (grep), then read by range, and give the agent that reads it a maxIterations of at least 30 β said as a rule for any large file to come, and for no file by name, when the folder holds examples; a folder of examples that shows no large file still gets the reading rule (search first, read by range), without the maxIterations floor, since the examples say nothing of the sizes to come (advice in the prompt, not validated: the forge only raises a planned cap below 6 to 6). The forge then emits folders.filled (folders: path, entries). folders.json records the step as settled (filled); a session stopped at the wait announces the folders again on resume and waits again, without a new interview.
Starting or resuming a cycle requires a configured LLM (orkeon init): the forge refuses to open the interview without one (FORGE-LLM-UNAVAILABLE) rather than degrade silently. list, promote, reopen, schedule, unschedule and rename are fully offline.
reopen <team-folder> makes a promoted team modifiable again, whatever became of its session. One rule decides which session a folder is linked to (rule R): every session carries a stable id β announced on session.started β that its promotion copies into the folder's forge.json, and the session carrying that id is linked when its promotedTo names the folder, or when the folder it names is gone or no longer carries the id: the team was moved or renamed, and the session is pointed at its new place. When promotedTo names another existing folder carrying the same id, this folder is a copy, linked to nothing; a folder without an id, or with one no session carries, is linked to nothing either. A linked session is only named: resume it. Otherwise β the session deleted, the folder forged on another machine or imported, a copy, a folder without an id β a session is rebuilt from the folder itself: the plan is read back from crew/ (per-entity config.yaml + agents/ + tasks/, or a single crew.yaml), the brief comes from the forge.json every promotion writes next to FORGE.md β or is derived from the plan, and the command says so β and the crew is copied verbatim. The rebuilt session gets a new id, written into the folder's forge.json (created without a brief when the folder had none; a copy's is rewritten, so it can never reach its original's session, and its session is named after the copy's own folder), and lands at the --dry pause, pointing back at the folder: the next reopen finds it, resume --edit --dry, resume, resume --adopt follow as usual, and a promote --to onto the same folder updates it in place. A folder with no YAML crew (a script crew, a foreign layout, files that do not describe a valid plan) is refused with FORGE-TEAM-UNREADABLE and the reasons; the verb takes no option but --events. This is how a client's Β« Modify Β» works, on every team.
| Option | Description |
|---|---|
--format yaml\|script |
Rendered format (default yaml). script renders an editable crew.ork.ts and needs esbuild β absent, a new session falls back to YAML with FORGE-ESBUILD-MISSING. A session's format never changes on resume. |
--events jsonl |
Emit the versioned event protocol on stdout instead of the terminal rendering; answers go down stdin (this is how a client drives the forge). The value is optional: the next argument is taken as it only when it is jsonl, so any other word stays part of the need (orkeon forge --events sort my mails forges "sort my mails"). |
--auto |
Arbitrate non-conforming verdicts without a human, within the budget. |
--dry |
Stop after validation β generate and validate, never execute. Resume without --dry to try it. |
--edit |
(resume) Amend the blueprint of a session paused before its trial: the amended JSON goes down the channel (blueprint.edited on stdin in --events mode, one pasted line in the terminal), is validated in full, then re-rendered deterministically β zero LLM tokens, same iteration, though a configured LLM is still required (FORGE-LLM-UNAVAILABLE otherwise). With --dry, the session pauses again at the same boundary. On a session not paused before its trial it exits 1 with a message, and no event. At the arbitration, use the edit decision instead. |
--adopt |
(resume) Take the team as generated, without running a trial: a session paused by --dry goes straight to Ready. Fully offline β no host, no LLM, no run directory, zero tokens. It skips the evidence a trial produces, never a check: the crew is rendered and validated at that pause, and promotion never consumed a trial artefact (verdict.json is optional and FORGE.md says Β«no verdict recordedΒ»). resume --adopt on a session that is not at that pause is refused with FORGE-INVALID-STATE; --adopt outside resume, or with --edit, is a usage error (exit 1). The cycle options (--read, --auto, --dry, --pack, --max-*, --settings) have no effect on an adoption. |
--max-iterations <n> / --max-tokens <n> / --max-seconds <n> |
The budget (default 3 iterations, at least 1; tokens and seconds default to 0 = unlimited, a negative value is refused). Resuming may raise it; consumption always carries over. |
--settings <path> |
Same semantics as orkeon run, anchored at the working directory β long form only: the forge parser is bespoke and defines no short aliases, and no --help either (an unknown option, --help included, is refused with exit 1). |
--read <dir> |
(new session, resume) The folder the trial reads behind the first input folder the confirmed list binds to no directory (/workspace when the need named no folder), in place of the working directory. The working directory keeps every other role β the session still lives under its .orkeon/forge/<slug>/, the settings still resolve next to it: --read moves the documents, not the atelier. A folder that does not exist is refused with exit 1 before any session is created (--read names no directory); promote refuses the option, since it mounts nothing. A read folder outside the working directory is whitelisted for the file tools automatically, the way orkeon run whitelists its script directory β the forge's mounts are its own, so there is no --allow-external-mounts here β and the same goes for a directory bound behind a folder the session had confirmed when the run started (a resume; see the folders step for one confirmed during the run). This is how a client retries a reopened team on its own input folder. |
--reference <id> |
(new session) The use case the team is modelled on: an id of orkeon usecases, whose crew β agents, tasks, process, each agent's tools β is shown to the assistant that designs the team as a model of structure, not content to copy: the brief alone decides what the team does. Shown when the team is designed, never during the interview; the tools the sandbox catalogue does not offer are removed from it, and it is bounded β each text cut at 200 characters, the whole at 4,000 (about 1,150 tokens), past which the rest of a larger team is cut, and said to be. Measured on 2026-09-24 against the real tool catalogue: a reference adds 2,100 to 4,500 characters to each call that designs the team β +590 to +1,290 estimated tokens, +800 for the median use case, on a call of about 3,000 without one. The session records it (reference in session.json: id and title) and announces it on session.started; a resume or a reopen composes with it again, and the option is refused anywhere but on a new session. The promotion traces it: Β« Inspired by: <title> (<id>) Β» in FORGE.md, next to the provenance line (Β« InspirΓ© de : Β» when the brief is French), and reference in forge.json. An unknown id is refused with exit 1 and USECASES-UNKNOWN-ID before any session is created or any model called β an error line, then session.finished Β«failedΒ», in --events mode. This is how a client passes the use case chosen in a gallery. |
--lang <code> |
(new session, resume) The language the assistant converses in, and writes the team's name, agents and tasks in: fr, en, es, de or zh β English without the option. The user overrides it by writing in another language or asking for one; the brief then records that language (language), and the team is designed in it. Refused on any other verb, and for any other code. This is how a client passes its interface language (English, the default, is not sent). |
--pack <dir> |
Override the embedded prompt pack. |
--to <dir> |
(promote) Destination folder; must not exist or be empty β unless it is the folder the session is linked to (where it promoted to, or that folder moved or renamed since; never a copy of it, which is refused with the reason), which is then updated in place. |
--name <team> |
(promote, rename) The team's name: it titles FORGE.md, forge.json and the session itself β without it they keep the brief's goal; for rename, the new name, which names the folder too (below). Taken as written, a leading dash included: the value of --name is never read as the next option. A client always passes it. |
--schedule daily@HH:mm\|hourly |
(promote) Generate the schedule artifacts under schedule/ β Windows task XML, systemd timer, cron line β and record the schedule in forge.json. The promotion itself installs nothing: forge schedule does (below). |
--check |
(schedule) Say where the schedule stands β installed, absent or stale β and change nothing. |
--with-settings |
(promote) Copy the resolved settings file into the folder. Off by default β a settings file usually carries API keys and the folder is made to be shared. |
The deliverable source. A plan task's deliverable keeps source: tool_call when every agent that may run the task writes it itself β the agent the task names in a sequential, parallel or graph crew; every agent but the manager in a hierarchical or consensual crew; every agent in an autonomous crew β, with a built-in tool that writes that path (the writers), among its own tools or the ones the task grants (tools: on the task), as the engine counts them. Otherwise the forge writes source: final_message, and the framework saves the agent's final answer to the path: no tool is granted for it. A binary deliverable (.docx, .xlsx, .pdf, an imageβ¦) is never an answer's text: plan validation refuses the plan when an agent that may run its task lacks the tool that writes its format, naming the task, the agents and the tool to give (docx_writer, xlsx_writer, image_generation), or a text format to deliver instead when no built-in tool writes it; file_write writes text files only and never counts for one. reopen reads a task's tools: back and applies this refusal too, though it skips the hand-off rule: a crew file whose binary deliverable no agent that may run its task can write is refused, the error naming that file. The YAML crew writes source: final_message and leaves the default implicit; crew.ork.ts always writes the source (.deliverable({ path, source: "tool_call" }), which the typings require). reopen does not read the source back: it derives it again from the plan, so a source edited by hand in the crew files is replaced by the one the plan gives.
The sandbox: the try runs in-process with the confirmed folders mounted and nothing else of the team's β /workspace and /output only when the list holds them. Writes are confined to the session's own directory: each output folder lands in folders/<name> and is snapshotted into runs/<n>/folders/<name> after the run, where the deliverable check looks; /forge holds its working files. An input folder reads the directory bound behind it, else --read, else the working directory for /workspace, else the session's folders/<name> β a folder kept inside the team, readable before the team exists. shell_command/code_interpreter are removed from the tool catalogue β the team plan can only name tools the validation will accept.
The promoted folder is ordinary: crew/ (or crew/crew.ork.ts), one folder per confirmed folder (/workspace reads input/) β what the session kept in its folders/<name> moves in β run.sh/run.cmd composed against the orkeon run grammar with those folders mounted and your sample inputs pre-filled, FORGE.md β the crew's identity card (goal, acceptance criteria, verdict, version), written in French when the brief is French and in English for every other language β and forge.json, its machine-readable twin (the session's id, slug, title, format, promotion instant, brief, and the use case it was modelled on) that forge reopen reads β the id is what links the folder back to its session wherever the folder goes. Neither file names anything of the machine β no path, no command: the schedule section of FORGE.md points at orkeon forge schedule ., and what a machine's scheduler registered stays in schedule/. orkeon run <dir>/crew launches it β from inside <dir>, and without the --mount arguments run.sh supplies, so a team that writes deliverables writes nothing that way; a client that drives the CLI can detect the folder and lay the mounts itself. A client adopting a team may write run.sh/run.cmd again from its team.json β the team's model setting as --llm-profile, every folder bound to the team as a launch passes it. Both write the launchers through one composer (TeamLauncherScript): run.cmd is UTF-8, sets chcp 65001 and gives the caller's code page back before orkeon starts; every value reaches the run as written whatever the team's path holds (&, ^, %, !, accents); a line break is a space in run.cmd β the file says so β and kept in run.sh; a single-value option is written --option=value. Beyond the 8 191 characters a cmd command holds once expanded, run.cmd launches nothing β it prints the length, the bound and the longest option, and exits 1 β while run.sh stays complete: the promotion says so with a warning (FORGE-LAUNCHER-TOO-LONG, also on stderr with --events) and succeeds.
Once the promotion is written, the session follows its team: its folder under .orkeon/forge/ takes the destination folder's name, as it is β suffixed -2, -3β¦ when another session already has that name, which is never overwritten β and session.json and forge.json take the new slug, so forge list shows each adopted session under the name of the team it made rather than the need it was opened with. --events announces it: session.renamed carries from, to, the new dir and suffixed. A rename the disk refuses (a handle held open on Windows, an antivirus) leaves the promotion successful β exit 0 β with a warning event (FORGE-SESSION-NOT-RENAMED): the team stays linked to its session by the id either way. The generated artifacts carry the team folder's name too, never the session's: schedule/orkeon-<team>.service and .timer with their descriptions, the scheduled task Orkeon <team>, the install command, the launchers' header. <team> is the folder's name as the folder rule spells it β lowercase ASCII and dashes, what a unit name can carry β which is the name itself for every folder a client creates.
The schedule. Orkeon has no scheduler of its own: the operating system runs a scheduled team, and the CLI β which owns the artifacts β installs and removes it there. promote --schedule generates schedule/ (the three families, whatever the machine) and records the declared schedule in forge.json; it never touches the system's scheduler. forge schedule <team-folder> registers it for the current user, without elevation and without a password:
- Windows β
schtasks /Create /TN "Orkeon <team>" /XML schedule/windows-task.xml /F. The task runs while the user is logged on; a run missed while the machine was off or on battery happens when it next can. Its action runs%SystemRoot%\System32\cmd.exe /d /v:off /s /c ""<team>\run.cmd"":/sremoves the first and the last quote and they alone, so the launcher starts whatever its path holds β&,(,^,!,%, spaces, accents β;/dskips the registry's AutoRun commands,/v:offkeeps a!. - Linux β the two units are copied into
~/.config/systemd/user/($XDG_CONFIG_HOMEhonoured), thensystemctl --user daemon-reloadandenable --now orkeon-<team>.timer.ExecStartcarries the launcher's path escaped for systemd:\\and\"as in C,%%for a%,$$for a$. A user timer runs while the user's systemd instance does β from login to logout, or always onceloginctl enable-lingeris set. - macOS and other systems β one line of the user's crontab, marked
# orkeon:<team>, read withcrontab -land written back whole withcrontab -: every other line stays exactly as it was, and nothing is ever written over a crontab that could not be read. The launcher's path is between single quotes for the shell cron hands the line to, every%β cron's line separator β written\%. launchd is not used.
Every command is a program and its list of arguments, never a shell. Installing again reinstalls. Artifacts that describe another folder β a copy, a team moved or renamed since its promotion β are regenerated first, and a registration this folder made under a former name is removed. What was installed is recorded in schedule/installed.json (expression, family, names, folder, date), beside the artifacts it describes β what this machine's scheduler knows of the team; forge.json keeps the declared schedule alone. The check and the removal act on those recorded names, never on names they would compute. --check changes nothing and answers installed, absent (never installed, removed outside Orkeon, made on another system β or the folder is a copy, and the recorded registration is its original's) or stale, to reinstall (it runs another path, carries another name, fires on another schedule than the declared one, or is disabled β or it is a Windows task whose command is run.cmd itself: reason outdated). forge unschedule <team-folder> removes this folder's registration, schedule/ with its record, and the schedule forge.json declares; nothing to remove is a success, and a copy never removes its original's registration. A name another team folder already holds is never replaced (FORGE-SCHEDULE-NAME-TAKEN); a folder that declares no schedule has nothing to install (FORGE-SCHEDULE-NONE). When the system refuses β a policy, no user session bus, no crontab β the verb exits 1 with FORGE-SCHEDULE-REFUSED, and the error event carries command: what to run by hand instead. With --events the outcome is one schedule.state event (path, state, reason, expression, family, names, and removed for a removal). A re-adoption regenerates schedule/ and keeps installed.json β the recorded names are the only way back to the registration β; one that drops the schedule leaves the registration running and says so with a warning (FORGE-SCHEDULE-STILL-INSTALLED): only unschedule removes it. Both verbs take no option but --events (and --check for schedule). The launchers call orkeon by name, and cron and systemd give a scheduled run a minimal PATH: a CLI installed with dotnet tool install (under ~/.dotnet/tools) is not found there, the .deb package's /usr/bin/orkeon is. The key follows the same contract: a scheduled run reads neither the PATH nor the exports of the shell profile, so the variable the settings file names for a key (ApiKeyEnvVar, e.g. ZAI_API_KEY β see configuration) goes where the scheduler reads: a ZAI_API_KEY=β¦ line in ~/.config/environment.d/*.conf for the systemd user manager, a variable line at the top of the crontab for cron β files the user owns and writes; Orkeon writes none. On Windows the task runs as the user, and a run reads the user scope where a client may remember keys, whatever the environment the Task Scheduler builds. This is how a client installs, checks and stops a team's schedule. The registration runs the launcher by its path and passes it nothing β the task's arguments to cmd.exe, the unit's ExecStart, the cron line β: a launcher written again later is what the next scheduled run executes, and nothing has to be reinstalled. Artifacts whose task command is run.cmd, or whose ExecStart or cron line is unescaped, are written again before an install.
Renaming a team. forge rename <team-folder> --name <name> renames a promoted team, all of it or nothing. The folder takes the name's folder, next to where it is β the folder rule, equipe when nothing usable is left; the session rule R links to the folder follows it, as after a promotion (suffixed -2β¦ past another session's name, never over it); the titles follow β session.json (and its promotedTo), forge.json, the team sidecar team.json (its name alone: every other field is kept, known to this version or not), the title line of FORGE.md, the launchers' header; schedule/ is regenerated for the new path and name, and a registration the system runs is reinstalled under the new name, the former one removed. A name whose folder is the team's own only retitles. Every step is journaled first: when one fails β the disk refuses, the system refuses the new registration β everything done before it is put back, the former registration last, and the verb exits 1 saying the team was not renamed: FORGE-RENAME-FAILED, or the system's own FORGE-SCHEDULE-REFUSED. A folder already there under the new name β another team, a folder, a file β is refused with FORGE-RENAME-TAKEN, saying what is there; a registration that still runs a team declaring no schedule any more refuses the rename as well (FORGE-SCHEDULE-STILL-INSTALLED: unschedule it first), since it would be left running a folder that no longer exists. A copy is renamed without its original's session ever being touched, and a folder that holds no team β no forge.json, no team.json, no crew β is never moved (FORGE-TEAM-UNREADABLE). With --events: the warnings, session.renamed when the session's folder moved, schedule.state when the schedule was reinstalled, then team.renamed (from, path, name); a refusal is one error, after which nothing changed. The verb takes no option but --name and --events. This is a client's Β« Rename Β».
Exit codes and error codes. 0 done (a session paused by --dry included), 1 a usage error or a refusal β a setting the engine host refuses included (orkeon forge: <reason>) β, 2 an unexpected error, 130 Ctrl+C β the session is saved and resumable. A refusal names its code on stderr, and in --events mode on an error event (code, message, recoverable). Besides the codes above, a cycle can report FORGE-BRIEF-INCOMPLETE (the interview produced no valid brief), FORGE-FOLDERS-INVALID (the confirmed folders break the rules, or bind an input the in-process try could not read β recoverable, they are proposed again), FORGE-BLUEPRINT-INVALID (no valid team plan), FORGE-TOOL-UNKNOWN (the plan names a tool the sandbox catalogue does not offer), FORGE-VALIDATION-FAILED (the rendered crew still fails validation after the repair attempts), FORGE-BUDGET-EXHAUSTED (a budget dimension ran out β the session stays resumable), FORGE-SESSION-CORRUPT (a session file missing or unreadable), FORGE-PROMOTE-FAILED (the folder could not be written β the session stays Ready) and FORGE-STAGE-FAILED / FORGE-ENGINE-CRASHED (a stage failed), FORGE-ENGINE-INCOMPLETE (a stage has no runner in this build) and FORGE-ENGINE-INVALID-TRANSITION (a runner returned a trigger the machine refuses from the current stage); FORGE-MOUNT-AMBIGUOUS is a warning event, not an error (the settings declare a virtual root twice and the forge has no selector, so no entry of it is mounted). The schedule verbs add three warning codes: FORGE-SCHEDULE-NOT-OWNED (the recorded registration belongs to the folder this one was copied from, and is left alone), FORGE-SCHEDULE-OTHER-SYSTEM (it was made on another operating system) and FORGE-SCHEDULE-FILES-KEPT (the registration is gone but some of its files could not be deleted); forge rename a fourth, FORGE-RENAME-SIDECAR-UNREADABLE (the team's team.json could not be read, so the name it records was left as it was); forge promote a fifth, FORGE-LAUNCHER-TOO-LONG (the team's run.cmd launches nothing: its command is longer than the 8 191 characters a cmd command holds β the promotion succeeds, run.sh is complete).
orkeon usecases
orkeon usecases search "summarize my emails every morning" # the closest use cases
orkeon usecases search "je veux un rΓ©sumΓ© de mes mails chaque matin" --top 3
orkeon usecases list --category finance-trading --process parallel # the catalogue, filtered
orkeon usecases show 03-email-pipeline --crew # one sheet, and its crew file
orkeon usecases export 01-research-assistant --to ./research --lang fr # one use case, as a team folder
The catalogue of the example use cases: the 104 numbered examples of examples/, each described by a sheet written in five languages (usecases.json). The tool carries the catalogue itself β the manifest, each example's crew file and its data/ folder β so every subcommand works offline, reads nothing from disk, and calls no LLM; only export writes. The finance examples are reference only: searchable and readable, not importable, since their crews depend on a shared _tools/ folder the tool does not carry.
search <text> ranks the catalogue against a need written in plain words, in French, English, Spanish, German or Simplified Chinese.
- By terms: BM25 over each sheet's title and problem in the five languages, its tags, its tools and its category. The query and the sheets are normalized alike β lowercase, accents folded (
resumefindsrΓ©sumΓ©), Chinese cut into character bigrams β so a query matches whatever language it is typed in. - By meaning: the local embedding model (BGE-micro-v2, on-device) compares the query with each sheet's English text, and its ranking is fused with the terms' by RRF. The model reads English only (see Known limitations), so meaning is fused in only for the languages where the golden set (usecases.golden.yaml) measured a gain: English today (measured 2026-09-24 on the five-language texts β terms alone reach recall@5 1.00 in every language, and meaning helps the ranking in English only); French, Spanish, German and Chinese are searched by terms. The model loads at the first search that needs it β about a second β and each later search takes a few milliseconds.
- Without the model (its files belong in
LocalEmbeddingsModel/default/next to the binary;orkeon doctorchecks them), the search runs by terms and every answer says so. It never degrades silently. A host of your own built withExcludeAssets="build"has no local model at all: it starts, and its first local embedding fails with a message that says so (limitations).
| Option | Description |
|---|---|
--top <n> |
Number of use cases to answer with (default 5). |
--lang fr\|en\|es\|de\|zh-Hans |
The query's language (zh is accepted for zh-Hans). Omitted, it is read from the text β function words, accented letters, Chinese characters β and keywords that give nothing away count as English. It picks the search mode and the titles shown. |
--events jsonl |
Answer with one usecases.results line on stdout instead of the text rendering (jsonl is the only value; any other exits 1). Without a text, session mode: one query per stdin line, one answer per query, the model loaded once for all of them, and the end of stdin ends the process with exit 0. |
Each result carries the use case's id, its rank, its score (BM25 by terms, RRF in hybrid mode β comparable within one answer only), the reason it matched (terms, meaning or terms+meaning), the terms it matched on, its similarity to the query in hybrid mode, and its title in the query's language. The answer carries the mode it ran in (bm25 or hybrid), the language and how it was settled (langSource: option, detected or default), and degraded, the reason, when meaning was given up.
Session mode is how a client suggests use cases while you type: the process opens with a usecases.ready line (catalogue size, languages, the mode of each), then answers every query with the query's correlationId in the envelope.
β {"kind":"usecases.query","correlationId":"q1","text":"relancer les factures impayΓ©es","lang":"fr","top":5}
β {"v":2,"seq":2,"ts":"β¦","kind":"usecases.results","correlationId":"q1","query":"relancer les factures impayΓ©es","lang":"fr","langSource":"option","mode":"bm25","results":[{"rank":1,"id":"40-invoice-processing","score":7.8412,"reason":"terms","terms":["factures"],"title":"β¦"}]}
A query without top or lang takes the command line's --top and --lang. A line that is not a query is skipped. A query that cannot run β no text, a lang outside the five, a top below 1 β is answered by an error line carrying its correlationId and the code USECASES-QUERY-INVALID, and the session goes on. The event kinds are declared once, in Orkeon.Constants.Protocol.UseCaseEventKinds.
list prints the catalogue: id, process, title, and the flags data (sample data), web (needs the network), keys (needs a third-party key) and reference only. The filters combine: --category (03-finance-trading, or finance-trading), --process (sequential, hierarchical, parallel, consensual, graph, autonomous), --tag. An unknown category or process is refused with the list of valid ones. --lang picks the titles (default en). --events jsonl emits one usecases.catalog line holding every sheet in full, under the manifest's field names.
show <id> prints one sheet: its category, process, agents and tasks, tools, tags, what it needs (network, keys), its mounts, whether it is importable, the files the tool carries for it, and its title and problem in every language written (--lang for one). --crew appends the crew file. --events jsonl emits a usecases.sheet line, with crew when asked. An unknown id exits 1 with USECASES-UNKNOWN-ID (an error line in --events mode).
export <id> --to <folder> writes one use case as a team folder a client can import as it is: crew/config.yaml β the example's crew, byte for byte β its data/ folder when it has one, a folder behind each of its mounts (output/ for every crew that writes files), and team.json, the team sidecar that names the team after the use case's title, describes it with its problem β both in --lang, default en β and records the manifest's mounts relative to the folder (./data:/data:ro, ./output:/output:rw). There is no forge.json: no workshop session made the team, and forge reopen rebuilds one from crew/ the first time the team is modified. Only the manifest's mounts are recorded β no input folder is invented. --to is created when absent; a folder that holds anything, or a file, is refused with USECASES-DESTINATION-NOT-EMPTY β an export never merges β and a reference-only use case with USECASES-NOT-IMPORTABLE. --events jsonl answers with one usecases.exported line: id, path, name, lang, files (every file written, relative) and mounts. The folder runs from inside it β orkeon run crew/config.yaml --mount ./data:/data:ro ./output:/output:rw, as the command prints it β or from a client once imported, which lays the mounts itself.
Exit codes: 0 answered (an empty answer included β an unknown --tag just matches nothing), 1 refused (an unknown id, an invalid option, a reference-only use case or a destination that is not empty to export), 2 unexpected error, 130 Ctrl+C. The codes: USECASES-UNKNOWN-ID, USECASES-OPTION-INVALID (a --lang outside the five, a --top below 1, a search without a text and without --events, an unknown category or process), USECASES-NOT-IMPORTABLE, USECASES-DESTINATION-NOT-EMPTY, and in session mode USECASES-QUERY-INVALID and USECASES-SEARCH-FAILED (one query failed; the session goes on); USECASES-FAILED is the unexpected error. A missing argument or an unknown option is answered by the option help instead, with exit 1 and no code.
orkeon init
Configuration assistant. Generates a valid appsettings.json at the global per-user path (%APPDATA%\Orkeon\appsettings.json on Windows, $XDG_CONFIG_HOME/Orkeon/appsettings.json β else ~/.config/Orkeon/appsettings.json β on Linux and macOS, which deliberately does not use ~/Library/Application Support) from an interactive 5-choice wizard β ollama, docker-model-runner, openai, custom, none β or non-interactively via flags, then probes the endpoint (unless --no-probe).
| Option | Description |
|---|---|
-p, --provider <preset> |
ollama | docker-model-runner | openai | custom | none (case-insensitive). Without it, the wizard asks β and a non-interactive stdin is refused with exit 1. |
-u, --base-url <url> / -m, --model <id> |
Endpoint and model. Required for custom; presets have defaults (below). |
-k, --api-key-env <name> / --api-key <value> |
The variable that holds the API key β written into the file as Llm:ApiKeyEnvVar, which every run reads, unless it is ORKEON_Llm__ApiKey (the default), which the runtime reads natively; init's probe reads the key as a run does (below) β or a key stored inline in clear text (discouraged). See the variable per provider. |
--path <file> |
Write somewhere other than the global per-user path. A folder gets an appsettings.json inside it. |
-f, --force |
Overwrite an existing file. |
--no-probe |
Skip the endpoint probe. |
| Preset | Base URL | Model | API key |
|---|---|---|---|
ollama |
http://localhost:11434 |
llama3.2 |
none β --api-key and -k are ignored |
docker-model-runner |
http://localhost:12434/engines/llama.cpp/v1 |
ai/granite-4.0-h-tiny |
the placeholder not-needed, written inline (--api-key replaces it) |
openai |
https://api.openai.com/v1 |
gpt-5.6-sol |
read from ORKEON_Llm__ApiKey, or from the variable -k names (Llm:ApiKeyEnvVar), never written β unless --api-key |
custom |
required | required | as openai |
none |
β | β | β |
The file holds only an Llm section (Model, BaseUrl, then ApiKeyEnvVar when -k names another variable than ORKEON_Llm__ApiKey, or ApiKey when one is inline); none writes no Llm section, only a _comment saying that runs fall back to the <undefined-llm> echo provider. The probe reads the file it has just written as a run reads it β the environment variables without a prefix, the file, then the ORKEON_ ones, the composition of orkeon doctor β and presents the key a run would present: the one the configuration resolves (ORKEON_Llm__ApiKey wins over the file's ApiKey), else the variable Llm:ApiKeyEnvVar names, in the process environment then, on Windows, in the user's, where a client may remember a key. It says where that key comes from β Probing <endpoint> β API key from the variable named by Llm:ApiKeyEnvVar (user environment) β, never the key, and a reference to a variable set nowhere is warned about first, in the runners' words. It then lists the endpoint's models (Ollama's catalogue for ollama, the OpenAI one otherwise) with a 5-second timeout; a failed probe is a warning β the file is written anyway, and the exit code stays 0. An Llm section a run would refuse to start on β a reference that is no variable's name, an ApiKey written ${NAME}, a BaseUrl that is no address β fails the probe with the reader's message and exit 1: the file is written, and a run refuses it until it is fixed. Exit codes: 0 written, 1 a flag error, a file already there without --force, an interrupted wizard, a written section a run refuses, 2 an unexpected error, 130 Ctrl+C.
init reads the address as a run does. An address read as Ollama (port 11434) accepts the ollama and custom presets only. Two rules apply: an address the reading refuses is written, then refused by the probe; a preset the reading contradicts is refused before anything is written, with the preset to use instead (exit 1). An address with no path is written all the same, with the silent-address warning on stderr and exit code 0. The probe lists the catalogue the reading names (Ollama's for an Ollama address, OpenAI's otherwise).
orkeon init --provider ollama --model llama3.2 --no-probe
orkeon init writes the settings file only. To start a project β a host, a plugin or a tool β use the
dotnet new templates of the Orkeon.Templates package: Starting from a template.
orkeon llm
Two verbs against a live provider endpoint.
orkeon llm probe β exercises the LLM test protocol against a provider and optionally archives the campaign trace. Key options: -p, --provider (required: openai | anthropic | ollama | azure | together | qwen | deepseek | kimi | mistral | huggingface | zai | gemini | grok | minimax | openrouter | mammouth, or a decision provider typesafe | liquid | kev), -m, --model, -u, --base-url (required for Azure), --api-version (Azure deployment mode), --workspace-id (for workspace-scoped keys β Anthropic identity-linked keys require it), -k, --api-key-env (default ORKEON_LLM_API_KEY β the key itself is never accepted on the command line), --modes (comma-separated, e.g. M1,M2,M8, D1βD8 for a decision provider; default every mode of the provider's family, except D8 and its 100k input tokens), --archive <dir> (where the campaign report is written; nothing is archived without it), --format md|json (default md), --commit <sha> (the short commit of the tree under test, recorded in the report), --timeout (seconds per request, default 180), --temperature (default 0), --thinking-effort (base reasoning-effort hint, e.g. none β some models refuse function tools while reasoning), --m7-effort (effort the M7 thinking probe uses, default low β for models whose supported set excludes it), --sweep-efforts (comma-separated effort values the M16 sweep tries, default low,medium,high,xhigh,max, then every value of an effort:* fragment of --raw-reasoning; may hold vendor values such as none or minimal). M15 (thinking toggle: on then off), M16 (effort sweep) and M17 (a 1024-token budget) are part of the default set; each reports, per step, whether the reasoning field really reached the wire (sent, lowered, omitted, rejected) in a reasoning array of the JSON report and a Reasoning table of the Markdown one. --raw-reasoning <file> feeds M18, the raw reasoning matrix: the file is a JSON array [{"label":"effort:xhigh","body":{"reasoning_effort":"xhigh"}}, ...], and for each item the provider still builds the request (auth, URL, headers, dialect) while its reasoning fields are replaced by body just before the request leaves, so the vendor's own acceptance is measured, not Orkeon's capability judgement. Each step is accepted or refused (with the vendor's error); the mode passes when at least one step is accepted, and is not applicable without the option.
orkeon llm models β lists the models a provider currently serves. Options: -p, --provider (required), -u, --base-url, -k, --api-key-env, -f, --filter (shell-style glob), --json.
ORKEON_LLM_API_KEY=... orkeon llm probe -p deepseek --modes M1,M2 --format json
orkeon llm models -p ollama --filter 'llama*'
orkeon rag
Two verbs over the RAG subsystem (ingest, search); its evaluation is orkeon eval rag. All share the host options of run: -s/--settings, -m/--mount, --allow-external-mounts, -v/--verbose <0-2> (default 0). Relative sources resolve against an automatic {cwd} β /workspace:ro mount; state lands in {cwd}/.orkeon β /output:rw.
orkeon rag ingest β incremental ingestion (unchanged sources are skipped): -c, --collection (required), --source <path|glob|url> (required; several sources space-separated after one flag, globs resolved through the virtual file system, an http(s):// address handed to the web loader as written β its ? or * are no pattern), --chunking recursive|sentence|structural|semantic (the pipeline default when omitted), --reindex (full reindex β the only way past an embedding model/dimension change).
orkeon rag search β asks a question, prints the grounded answer with citations and scores: positional <question>, -c, --collection (required), --top-n (default 5).
The embedding model. orkeon rag uses no host fingerprint (its default Orkeon:Embeddings:FingerprintPath is empty). The manifest of each collection records the provider, model and dimensions it was indexed with and refuses a change: ingest without --reindex, every search, orkeon eval rag --no-ingest -c and orkeon eval rag -c with its ingest pre-pass and no --reindex exit 1 with one line that names the collection, both models and orkeon rag ingest --reindex. --reindex rebuilds the collection and passes. eval rag without -c has no check of its own: the harness resolves the collection.
orkeon eval
The evaluation framework as a command: four verbs. The scoring verbs share the host options of run (-s/--settings, -m/--mount, --allow-external-mounts, -v/--verbose <0-2>), read the Evaluation section of the settings, and read the dataset through the virtual file system (a relative path resolves against the automatic {cwd} -> /workspace:ro mount). One suite, Default; --evaluators picks evaluators of it by name, there is no --suite.
orkeon eval run β scores a JSON dataset (an array of cases: task_description, expected_output, output, context, expected_format, metadata) and writes <output>/<dataset>-eval.json: the EvaluationReport (snake_case) plus the dataset name and a cases array with the output that was scored. -d, --dataset (required), --evaluators format,schema,text-quality,similarity,tool-accuracy (default: every registered evaluator; coherence,fluency,groundedness too with --llm-judge; an unknown name is refused, exit 1), --llm-judge (sets Evaluation:EnableLlmJudge for the run; needs an LLM), --offline (zero network: the judges stay off, refused with --llm-judge, and a --crew is refused, exit 1, when any of its agents or its manager would answer through a provider other than the mock - the agent and its profile are named), --output (default /output/eval, that is ./.orkeon/eval), --min-score <0-1> (exit 1 when the overall score is under it). Without --crew every case needs its output. With --crew <file> (a YAML crew, an .ork.ts or a crew directory, loaded with the guards of orkeon run) the crew runs once per case before scoring: the case's task_description is its prompt (the initial context and the {input} variable), its final output replaces output in the report, and the dataset file is never modified; one host serves every case, so the memory the crew keeps carries from one case to the next (cases are not isolated from each other: order them, or give each case a crew without memory, when that matters); --llm-mock <file>, --llm-record <file>, --llm-replay <file> and --llm-profile <id> are those of orkeon run (a replay counts as offline: --offline --llm-replay runs on any profile). A crew that fails on a case exits 2, stops the run and writes no report: a report of part of the dataset would read as the whole. Every string of the report - the produced outputs, the scores' reasoning - goes through the redaction of the run history (secret-shaped values become ***REDACTED***). A report that already exists is overwritten, and the command says so.
orkeon eval bench β scores the dataset's recorded outputs --runs N times per case (default 3) and writes <dataset>-bench.json and -bench.md (mean and standard deviation per evaluator). --baseline <report> compares the run with a report written by eval bench or eval run and exits 1 on a regression (--threshold, a number from 0 to 1, default 0.05). The baseline is read before the run writes anything; a baseline that is the report the run writes (.orkeon/eval/<dataset>-bench.json with the default --output) is refused, exit 1: keep the baseline elsewhere, under version control for instance. A baseline of another dataset, or scored by other evaluators, is refused too, before any report is written. --dataset, --evaluators, --llm-judge, --offline, --output and --min-score are those of eval run. It takes no --crew.
orkeon eval compare <baseline> <current> β compares two reports written by eval run or eval bench, prints the markdown comparison (--json for JSON) and exits 1 on a regression (--threshold, a number from 0 to 1, default 0.05). The two reports must be different files of the same dataset (the name eval run and eval bench record) scored by the same evaluators: otherwise the comparison is refused, exit 1, since an evaluator scored on one side alone has nothing to compare with.
orkeon eval rag β evaluates a collection against a golden dataset (recall@k, MRR, groundedness) and writes markdown/JSON reports; the dataset's corpus folder is ingested first, incrementally: -d, --dataset (required), -c, --collection (default: the dataset's collection, else rag-eval-<dataset name>), --profile fast|balanced|quality|adaptive|corrective|default (default default = the configured Orkeon:Rag:Profile) or --compare fast,balanced,β¦, -k (default 5), --llm-judge, --offline (zero-network: deterministic extractive stub, no LLM key needed β it answers in place of every model, Orkeon:Rag:LlmProfile included), --no-ingest, --reindex, --min-recall / --min-mrr (anti-regression gates, exit 1 below threshold), --output (default /output/rag/eval, that is ./.orkeon/rag/eval).
orkeon eval rag --dataset examples/rag/eval/golden.yaml \
--compare fast,balanced,quality,corrective,adaptive --offline
orkeon eval run --dataset qa.json --crew crew.yaml --llm-mock answers.jsonl --offline --min-score 0.7
cp .orkeon/eval/qa-bench.json baselines/qa-bench.json # once, from a run you accept
orkeon eval bench --dataset qa.json --runs 5 --baseline baselines/qa-bench.json
orkeon eval compare baselines/qa-bench.json .orkeon/eval/qa-bench.json
orkeon email
orkeon email accounts [--settings <file>] [--json] # the declared accounts, their rights, whether each is ready
orkeon email login <account> [--settings <file>] [--events jsonl] # sign an OAuth2 account in and store its tokens
orkeon email logout <account> [--settings <file>] # forget the stored tokens of an OAuth account
orkeon email check <account> [--settings <file>] [--events jsonl] # connect, authenticate, list the folders
The operator's side of the e-mail tools (guide): what is declared under
Orkeon:Tools:Email, the one interactive step an OAuth2 account needs, and a connection check.
Agents never run these β a tool that finds no usable token answers
"run orkeon email login <account>".
accountslists every declared account β its preset, how it reads and sends, how it signs in, its rights, whether it is the default β and saysready, or what to fix: an invalid declaration, a password or client-secret variable that is not set, a sign-in still to do. It opens no connection and prints no secret;--jsonwrites the same list as JSON, under the namesemail_accountsuses (name,address,provider,reads,sends,rights,auth,default,ready,problem), plusconfiguration_problems(a list, empty when the account resolves),credential_problemand the values a blank field resolves to:incoming_host,incoming_port,incoming_security,outgoing_host,outgoing_port,outgoing_security,username,save_sent_copy,token_endpoint. The text listing shows the servers, login name and token endpoint of a resolved account on one line (e-mail guide).loginsigns an OAuth2 account in. A Microsoft account uses the device-code flow: the command prints the verification address Microsoft returns and a code, and waits while you sign in from any browser. A Google account uses the authorization code with PKCE: the command prints Google's authorization address and listens on a free port of127.0.0.1; when the browser cannot reach this machine (WSL, a container, an SSH session), paste the address the browser ends on into the terminal. A pasted line that is not that address β cut short, the address to open, plain text β is answered by a sentence that says why, without repeating it, and the command goes on waiting; an empty line is ignored. The tokens go to the runner's internal/credentialsroot (where the tokens live). A password account has nothing to log in to and is refused. With--events jsonla program drives the sign-in instead of a person reading it β the way a client runs it. Standard output then carries one JSON event per line and nothing else, in the envelope of the run event stream, under the kinds declared once inOrkeon.Constants.Protocol.EmailEventKinds:email.login.device_code(verification_uri,user_code,expires_inin seconds),email.login.authorization_url(authorization_uri),email.login.redirect_rejected(message),email.login.completed(account), anderror(codeβ the e-mail error code, such asCredentialMissingorLoginRequiredβ,message,recoverable), which replaces the line on stderr; the exit code is the one the verb has without the option. Standard input is the driver's hold on the verb: a line written to it is the address the browser ended on β a line that is not getsemail.login.redirect_rejected, whosemessagesays why without repeating the line, and the verb goes on waiting: a rejected line ends nothing and changes no exit code β, and closing it aborts the sign-in with exit code130β the Google flow waits without a deadline, so a driver that goes away never leaves the verb listening on its port. Without the option the verb prints for a person: the address, the code, the outcome.logoutdeletes the stored tokens of an OAuth account, and says so when there were none; a password account has none and is refused.checkconnects, authenticates and lists the folders, then prints how many there are and the inbox counts. With--events jsonlthe verdict is one event line on standard output instead:email.check.completed(account,folders,inbox_total,inbox_unread, andsummary, the sentence printed without the option), orerrorwith itscodeβ which is how a client knows that a refused test wants a sign-in or a password, and points at its own button or field rather than at a terminal. The exit code is the one the verb has without the option.
-s, --settings <path> resolves like orkeon run, anchored at the current directory: the
explicit file, else appsettings.json in the current directory, else an
appsettings/appsettings.json found walking up, else the per-user file of orkeon init,
else ORKEON_* environment variables alone β which is also what an explicit path that does
not exist leaves, with a warning. The file used is named on stderr (Using settings: β¦).
Exit codes: 0 success, 1 usage, configuration or refusal (an unknown account, a variable
that is not set, a sign-in to do β a provider that issued no refresh token included β, a
missing right or capability), 2 what the network or the server did (a connection failure,
credentials or an authorization the provider refused) or an unexpected error (ORKEON_DEBUG=1
prints its stack trace), 130 Ctrl+C. The verb is
matched before crew-path detection, like every verb: a crew folder named email runs as
orkeon run email.
orkeon drive
orkeon drive accounts [--settings <file>] [--json] # the declared accounts, their rights, root folder, whether each is ready
orkeon drive login <account> [--settings <file>] [--events jsonl] # sign the account in (device code for OneDrive, browser for Google) and store its tokens
orkeon drive logout <account> [--settings <file>] # forget the stored tokens
orkeon drive check <account> [--settings <file>] [--events jsonl] # connect, find the root folder, list its first items
The operator's side of the drive tools (guide): what is declared under
Orkeon:Tools:Drive, the one interactive step every account needs, and a connection check.
Agents never run these β a tool that finds no usable token answers
"run orkeon drive login <account>".
accountslists every declared account β its provider, root folder and rights, whether it is the default β and saysready, or what to fix: an invalid declaration, a client-secret variable that is not set, a sign-in still to do. No network.--jsonwrites one object per account (name,provider,rights,root,default,ready,problem,configuration_problems,credential_problem,token_endpoint) (drive guide).loginruns the OAuth sign-in: Microsoft's device code for OneDrive, Google's consent page with a loopback redirect (or the pasted address it ends on) for Google Drive. The tokens land in thedrivesubdirectory of the credentials directory, where every run looks for them. With--events jsonla program drives the sign-in β the way a client runs it β, on the protocol oforkeon email loginunder the kinds ofOrkeon.Constants.Protocol.DriveEventKinds:drive.login.device_code(verification_uri,user_code,expires_in),drive.login.authorization_url(authorization_uri),drive.login.redirect_rejected(message),drive.login.completed(account), anderror(code,message,recoverable). A line on standard input is the address the browser ended on; closing standard input aborts the sign-in with exit code130.checkfinds the account's root folder and lists its first page:Drive account 'pro' is reachable: root folder /Orkeon ('Orkeon') holds 3 item(s).With--events jsonlthe verdict is one event line instead:drive.check.completed(account,root_path,root_name,items,more, andsummary, the sentence printed without the option), orerrorwith itscode(LoginRequired,CredentialMissing, β¦). The exit code is the one the verb has without the option.- Exit codes: 0 done; 1 what the operator fixes (configuration, unknown account, missing variable, sign-in needed, a right or a capability missing); 2 what the provider or the network did; 130 Ctrl+C.
orkeon typings
orkeon typings # write orkeon.d.ts and orkeon-cli.d.ts into ./.orkeon/
orkeon typings --out crews/.orkeon
Writes the TypeScript typings this build of the tool carries, for your editor: orkeon.d.ts (the .ork.ts scripting DSL) and orkeon-cli.d.ts (the REPL's *.cmd.ts commands). Both are embedded in the tool, so a dotnet tool install is enough β no clone, no build. -o/--out <dir> (or --out=<dir>) picks the folder (default ./.orkeon, created when missing); existing files are overwritten, so run the verb again after updating the tool. A script then opens with /// <reference path="./.orkeon/orkeon.d.ts" />, the path relative to the script. Offline. Exit codes: 0 written, 1 an unknown argument or --out without a folder (--out= included).
The same two files are attached to every GitHub Release as orkeon-typings-<version>.tar.gz (a folder of that name holding orkeon.d.ts and orkeon-cli.d.ts), produced by this verb from the release's own build, listed in SHA256SUMS and attested. A project that pins the typings of a release, or diffs two of them, downloads that archive instead of running whichever tool is installed: see Editor setup.
orkeon runs
orkeon runs list [--crew <key>] [--limit <n>] [--settings <file>]
orkeon runs show <run-id> [--settings <file>]
orkeon runs tail <run-id> [--follow] [--from <seq>] [--settings <file>]
Reads back the runs the run history recorded (Orkeon:RunHistory:Enabled; the orkeon init template and orkeon-host turn it on). list prints one JSON summary per run, newest first (run_id, crew_key, status running, succeeded, failed or orphaned, started_at, finished_at, error, and the pid, host and process_started_at of the process that ran it), --crew keeps one crew and --limit (default 50) bounds the list. show prints every event of a run, from run.started to run.finished, and tail prints from --from <seq> on (--follow waits for a run still in flight and stops at its end). Both write the very lines orkeon run --events jsonl wrote, so one reader serves the stream and the history. The history is read from the settings of the current directory (-s, --settings <path> names the file) and the ./.orkeon/runs folder; reading never changes it (the purge belongs to the side that writes). A run recorded as running whose process no longer exists on the same host was killed: it is reported orphaned, counts as finished for the purge and for MaxRuns, and ends tail --follow. A run recorded on another host stays running: only its own host can tell. What it holds: every event of the run except llm.delta (unless IncludeDeltas) β task results, tool names and the names of their arguments, model-call sizes, error messages β and, with each run, the pid and the host name. Secrets are masked before they are written, with the masking the logs use (the keys of the vendors Orkeon ships a client for, bearer tokens, password=, token=, api_key= pairs, and the value of any property named like a credential); the --events stream on stdout is not masked. orkeon init adds .orkeon/ to the .gitignore of the current folder, because the folder holds what runs said and did. Offline. Exit codes: 0 printed, 1 an unknown subcommand, a malformed argument, a run absent from the history, or the history not enabled, 130 interrupted.
orkeon mcp
orkeon mcp serve [--settings <file>] [--tools a,b,β¦] [--max-concurrency <n>] [--expose-output] [--crew <a.yaml> [<b.yaml> β¦]] [--allow-external-mounts]
orkeon mcp serve serves the tools of an Orkeon host to an MCP client over stdio β the way Claude Desktop or an editor starts a local MCP server: the client launches the command, writes JSON-RPC messages on its stdin, one per line, and reads the answers on its stdout; closing stdin ends the server. The host is the one orkeon run builds β the settings, resolved like orkeon run's from the current directory (-s, --settings <path> names the file), their mounts, the built-in tools and the MCP servers they declare β, and what is served is what orkeon run --list-tools prints for the same settings, human_input aside. --crew <a.yaml> [<b.yaml> β¦] serves each crew as the tool run_crew_<name> (its input the {placeholders} of its tasks, its result the final output, notifications/progress per task when the client sends a progressToken) and its tasks as prompts, under the budget, guardian and permission gate of orkeon run β several crews go space-separated after one flag, a crew outside the working directory needs --allow-external-mounts, and only the crews named are served; --tools a,b,β¦ serves the named tools only; a name the host does not have refuses the start. --max-concurrency <n> (at least 1, default 4) bounds how many requests run at once, the others wait their turn; notifications/cancelled cancels the request it names. --expose-output serves /output as read-only MCP resources (orkeon:///output/<path>, through the virtual file system; /workspace is never served). Every tools/call crosses the invocation point of a crew agent's calls β guardian, truncation, result sanitizer, audit β under the caller mcp. Stdout carries the protocol and nothing else: logs, warnings, --help and usage errors go to stderr. Exit codes: 0 the client closed the stream (or --help, or Ctrl+C or SIGTERM), 1 a usage error, a refused setting, a --tools name the host does not have, a --crew refused at start (a crew that does not load, a name given twice, a run_crew_* name a tool already holds), or a serve started by another serve, 2 an unexpected error. A serve sets ORKEON_MCP_SERVE in its environment before it connects the MCP servers of its settings β every process it starts inherits it β and a serve that finds it set refuses to start, with one line on stderr: settings declaring orkeon mcp serve under their own MCP:Servers would make each server start another before answering. A client configuration and the details: MCP integration.
orkeon doctor
Installation diagnostic: says in under 15 seconds what works and what is missing, as a β
/β οΈ/β table or --json (stable {check, status, detail} schema for CI). The checks, in this order: dotnet-runtime, install-channel, appsettings, llm-config, llm-profiles, runner-settings, llm-reachability, esbuild, tsc, local-embeddings, onnx-reranker, tree-sitter, workspace-write β plus, after llm-profiles, one llm-profile-key row (warn) per profile whose ApiKeyEnvVar names a variable set nowhere; each status is ok, warn or fail. install-channel names the channel this build was installed through, the version that runs and the command that updates that channel (zip β orkeon <version>; to update: extract the new orkeon-cli-<version>-win-x64.zip and run its install.cmd). The channel is zip, msi, msi-host, tarball, deb, homebrew, source or dotnet-tool: it is read from the INSTALL-CHANNEL file each packaging writes at the root of what it installs, never guessed β except the dotnet tool, which carries no such file and is known by its path. A Debian package answers deb whether apt fetched it from the repository or it was downloaded: nothing inside it tells the two apart, and the check gives both commands. An installation older than the marker, or a build run from its tree, answers unknown and stays ok; only a marker that exists and names no channel is a warn. The check never fails. A scripted command reads the same version and channel through ctx.services.get("runtime") (scripted commands). runner-settings judges the file as orkeon run judges it at its start, by the same construction: the guards a run applies to the mounts the file declares (a root orkeon run keeps for itself, entries of one root told apart by their ids, folders that exist), then the host orkeon run builds β no crew, no command-line mount, no MCP connection, the ONNX reranker the CLI adds included β and its start validation. One fail row per refusal, each naming its key, all at once; one ok row otherwise (the settings pass the start validation of orkeon run) β and one warn row per section the file writes that no shipped binary reads, in the words the run writes on stderr (when a setting is only reported); with such a row and no refusal there is no ok row, and the exit code stays 0; a refusal the build itself raises β a file it cannot read, a log level β is the only row, as the run reports it. It says skipped (the Llm section is refused β see llm-config) when llm-config or llm-profiles already failed. It leaves the working directory as it was: its host creates its sandbox directory under the temporary directory and deletes it β and, when an e-mail account signs in with OAuth, the token directory a run creates. A file a run refuses makes doctor exit 1. llm-config ends with where the default's key comes from (API key from the variable named by Llm:ApiKeyEnvVar (user environment) β never the key nor the variable's name), warns when that reference resolves nothing, and fails when the section cannot be read β an ApiKey written ${NAME}, a reference that is no variable name, an invalid BaseUrl β as a runner would refuse to start; llm-profiles lists each profile with where its key comes from; llm-reachability queries the catalogue with the key a run would use. --json is the only option: the settings are read as a run reads them β the file the chain of orkeon run finds, anchored at the current directory, between the environment variables without a prefix, below it, and the ORKEON_* ones, above it; nothing else β which is also where the esbuild check reads Orkeon:Scripting:Toolchain:EsbuildPath. The dotnet tool does not ship esbuild: a β οΈ on that check says how to get it (npm install -g esbuild, ORKEON_ESBUILD_PATH or EsbuildPath), and both of its details name orkeon typings for the editor typings. The tsc check follows the type-check mode (Orkeon:Scripting:Toolchain:TypeCheck): a tsc found nowhere is ok under Off and Validate, its detail saying it is optional, and fail under Always; a configured TscPath that does not exist is ok under Off (unused while the type check is off), warn under Validate and fail under Always; a tsc that does not answer --version is ok under Off and warn under Validate and Always. Under Always the detail gives the reason, then the installed remedy (npm install -g typescript, Orkeon:Scripting:Toolchain:TscPath, TypeCheck: off), and the checkout bootstrap only when orkeon runs from a checkout. A fail makes orkeon doctor exit 1. Exit codes: 0 all green or warnings only, 1 at least one failing check (or an invalid option), 2 an unexpected error, 130 Ctrl+C.
doctor names the provider the run builds from the Llm section β OpenAI-compatible (custom) for an address read as a generic server, Docker Model Runner for that one β and reports an address with no path (one that says nothing of its provider) as a warn: on llm-config for the default, and one llm-profiles row per profile.
orkeon doctor --json
orkeon settings
orkeon settings # the eleven categories, and the sections of each
orkeon settings rate-and-budgets # a category: its sections, and who reads each
orkeon settings RateLimiting # a section: every key with its type, default and meaning
orkeon settings RateLimiting:QueueLimit # one key
orkeon settings rate # a word: whatever is named or described with it
orkeon settings env # the environment variables Orkeon reads
orkeon settings --all # every section and every key, by category
orkeon settings --json # the same inventory, for a program
orkeon settings --host host # only what orkeon-host reads
Lists the settings a host reads β what a settings file may hold β in the terminal, offline: the inventory of the configuration reference, from the tool itself. It answers from the catalogue the tool carries, which is produced from the code that reads the settings: it opens no settings file, builds no host and reaches no network. So it answers the same in a folder whose appsettings.json a run refuses, it works in a folder it cannot write to, and it writes nothing. What it shows is what a key is worth when nothing sets it, not what this machine has set: orkeon doctor is the verb that judges a file. A key that holds a secret is marked secret and has no default β no output of the verb carries a key's value.
$ orkeon settings RateLimiting
RateLimiting β Rate and budgets (rate-and-budgets)
Read by: orkeon, orkeon-host, orkeon-repl
The host's caps on model requests β the `RateLimiting` section. Every model call of the host
counts, once, at the entrance of its provider: β¦
RateLimiting:AgentRequestsPerMinute integer default: 20
Maximum model requests per minute of each agent β β¦
RateLimiting:GlobalRequestsPerMinute integer default: 60
Maximum model requests per minute across all providers and agents. β¦
RateLimiting:MaxConcurrentRequests integer default: 0
Maximum number of concurrent (in-flight) model requests. 0 means no concurrency limit (rate
limiting only).
RateLimiting:ProviderRequestsPerMinute integer default: 30
Maximum model requests per minute per provider, held and refused like the global cap.
RateLimiting:QueueLimit integer default: 5
Maximum number of requests the global, per-provider and concurrency caps hold in a queue when
they are reached; a request beyond it is refused, then retried.
What a name designates, tried in this order, whatever its case:
- a category, by its id or its title β
models,rate-and-budgets,memory-and-vectors,rag,files-and-sandbox,security,tools,orchestration-and-persistence,scripts-and-console,service-host-and-a2a,observability: its sections, each with its number of keys, who reads it and the first sentence of what it configures; - a section, by its path (
RateLimiting,Orkeon:Rag:WebFallback): who reads it, what it configures, then every key β path, type, default, the values a closed list accepts, and its meaning; - a key, by its path. A name or an index of yours stands where the catalogue writes
<name>or<i>:orkeon settings Llm:Profiles:fast:ModelfindsLlm:Profiles:<name>:Model(written with the brackets, the path needs quotes in a shell); - a word: what is named with it, then what is only described with it β sections with who reads them, keys one line each. The word is looked for where a word starts, in the paths and in the descriptions:
ratefindsRateLimitingandToolRateLimiting, notFallbackStrategy.
A name that designates nothing exits 1 and names the closest one there is. The listing never exceeds 100 columns.
Who reads a section is said for each: Read by: orkeon, orkeon-host, orkeon-repl, or Read by: a C# host only β AddOrkeonToolRateLimiting() for a section no shipped binary reads β written in the settings file of orkeon run, such a section has no effect; the list of categories marks it with a *.
| Option | Description |
|---|---|
--all |
Every section and every key, by category. Takes no name. |
--json |
The catalogue instead of the listing (below). Follows a name and --host. |
--host <run\|host\|repl> |
Only what one binary reads: run is orkeon (every verb that builds the runner host), host is orkeon-host, repl is orkeon-repl; the name of the binary is accepted too. Without it, everything Orkeon reads, each section saying who reads it. A name the chosen binary does not read exits 1 and says who reads it. |
--json is a contract, like doctor --json: one object with two arrays, written on stdout and nothing else.
{
"sections": [
{ "path": "RateLimiting", "category": "rate-and-budgets",
"hosts": ["orkeon", "orkeon-host", "orkeon-repl"],
"registration": "AddOrkeonInfrastructure", "description": "β¦" }
],
"settings": [
{ "path": "RateLimiting:QueueLimit", "section": "RateLimiting", "type": "integer",
"default": 5, "description": "β¦" },
{ "path": "MCP:Servers:<name>:Transport", "section": "MCP", "type": "enum",
"default": "Stdio", "values": ["Stdio", "Sse"], "description": "β¦" },
{ "path": "Llm:ApiKey", "section": "Llm", "type": "string", "secret": true, "description": "β¦" }
]
}
| Field | In | Meaning |
|---|---|---|
path |
both | The configuration path. A name the operator chooses is written <name>, an index <i>. |
category |
section | One of the eleven category ids above. |
hosts |
section | The shipped binaries that read it, among orkeon, orkeon-host and orkeon-repl. Always present; empty when none does. |
registration |
section | The public registration a host written in C# reads the section through. Absent when only a shipped binary's own composition reads it. |
section |
key | The path of the section the key belongs to. |
type |
key | string, integer, number, boolean, duration, uri, date-time, enum, any, or list of one of these. |
default |
key | The value when nothing sets the key, as a JSON value. Absent when there is none, or none that can be written β a secret, a value that depends on the moment. |
defaultNote |
key | What the value cannot say, in words: what stands for a default that is no constant, the entries a dictionary starts with, what the default depends on. Absent otherwise. |
values |
key | The values an enum accepts. Absent otherwise. |
secret |
key | true when the value is a secret; such a key has neither default nor defaultNote. Absent otherwise. |
description |
both | What the section configures, what the key means. |
Sections come by category, in the order of the listing, then by path; keys in the order of their sections, then by path. The same build writes the same bytes on every machine: no date, no path, line feeds. With a name or --host the shape is the same and the content narrower β a category or a section gives its sections and their keys, a key its section and itself, a word what it found. A field may be added later: read the ones you know.
orkeon settings env lists the environment variables Orkeon reads, the three kinds the configuration reference tables: the ones that carry a setting (ORKEON_<Section>__<Key>, the same without the prefix, ORKEON_<NAME> for a secret), the ones a binary reads by their name β each with the value it takes, the binaries that read it and what it does: ORKEON_DEBUG, ORKEON_ALLOW_EXTERNAL_MOUNTS, ORKEON_ESBUILD_PATH, TUI_DRIVER, XDG_CONFIG_HOME, β¦ β and the settings keys that name a variable (Llm:ApiKeyEnvVar, β¦), taken from the catalogue. It reads the same list as the reference page, which a test holds to it, and no variable of the machine: it says what Orkeon would read, not what is set. env is that list and not the word: what the word names or describes among the settings β MCP:Servers:<name>:Env:<name> β follows it. It takes --json and no other option:
{
"settingsPrefix": "ORKEON_",
"variables": [
{ "name": "ORKEON_DEBUG", "readBy": ["orkeon"], "value": "`1`, `true` or `yes`", "effect": "β¦" }
],
"namedBySettings": ["Llm:ApiKeyEnvVar", "Llm:Profiles:<name>:ApiKeyEnvVar"]
}
readBy names shipped binaries; value and effect are sentences for a reader, in Markdown; namedBySettings are paths of the catalogue above. A contract like the catalogue's: a field may be added, none changes its meaning.
Exit codes: 0 listed; 1 a name that designates nothing or that the --host binary does not read, an unknown option, a --host that is none of the three, env with another option than --json.
orkeon-repl β the separate interactive console
orkeon-repl is a different tool built from src/apps/Orkeon.ConsoleApp (dotnet tool command orkeon-repl): a full interactive REPL that drives agents, crews and tools from a Terminal.Gui split-pane console (logs + REPL), with the full framework stack wired in β built-in tools, RAG, code analysis, local embeddings β and TypeScript-scripted commands. It deliberately does not share the orkeon assembly name.
It reaches you as a dotnet tool, in the multi-app release archives, in the ghcr.io/orkeon/orkeon image, and in the Debian and Ubuntu package (/usr/bin/orkeon-repl, self-contained, so apt install orkeon needs no .NET). From a clone, see Install the REPL from source. It has no --help or --version: it opens its console, and with stdin closed and --ui plain it prints its banner and leaves at the end of input.
| Option | Description |
|---|---|
--ui tui\|plain\|auto |
The console: the split-pane TUI, or a plain line console. auto (the default) picks the TUI on an interactive terminal, and the plain console when CI=true, when stdin or stdout is redirected, or when TERM is unset on Linux. An unknown value exits 2. |
--repl-wrap on\|off |
Word-wrap in the REPL pane (default on; true/false/1/0 are accepted). An unknown value exits 2. |
--llm-log / --llm-log-path <dir> |
The LLM exchange log of orkeon run: every request and response as JSONL under ./llm-logs, or <dir>, which implies --llm-log; tuned by LlmLogging. A folder outside the working directory needs --allow-external-mounts; without it, the REPL refuses to start (exit code 1) with orkeon run's line. |
--replay <file> |
Feeds the lines of <file> to the REPL as if typed, then exits: the plain console (no TUI, no line editor), each line echoed, the logs on stderr. Exit code 0 when every line passed, 1 when the replay stopped on an error or the REPL itself failed (one line on stderr), 2 when the file is missing or unreadable. See Replay below. |
--interactive |
With --replay: the usual console (TUI or plain), the file replayed, then the keyboard handed back. Without --replay it is a usage error (exit 2). |
--log-level <level> |
The minimum level of the logs (Trace, Debug, Information β the default β, Warning, Error, Critical, None). An unknown level exits 2. Under --replay alone it filters the logs written to stderr; in the TUI it is the starting level of the logs pane (F2 / Shift+F2 still change it). |
--runner=scripted-commands |
Start in the scripted-commands REPL instead of the main menu. |
--commands-dir <path> / --no-script-commands / --strict-commands |
Where the *.cmd.ts commands are found, or none at all, or fail fast on a broken one. |
--crews-dir <path> |
Where script-host resolves a crew by name. |
--settings <path> / --mount <spec> |
The settings files, in place of the global one (later ones win), and VFS mounts β placed and guarded as for orkeon run: a --mount on a root the settings declare replaces its entries for the session (the log says mount /x: --mount replaces the settings entry), one on a new root is appended. Before the console opens, orkeon run's lines refuse, with exit code 1, a mount on /sandbox, on /credentials or on a root the REPL mounts itself (/cli-commandsβ¦ with --commands-dir, /crewsβ¦ with --crews-dir), a root mounted twice on the command line β the same spec twice included β, a root declared twice with nothing to choose one (the line names --mount, the REPL having no --mount-id), a folder that is not there β --commands-dir and --crews-dir included β, wherever the mount was declared: --settings, the global file, a variable, --Orkeon:FileSystem:Mounts:<n>=β¦. |
--allow-external-mounts |
A --mount outside the working directory is readable, as for orkeon run (or ORKEON_ALLOW_EXTERNAL_MOUNTS=1); without it, the REPL refuses to start (exit code 1) with the same line. Every settings entry in force (one chosen by id included), and the --commands-dir and --crews-dir folders β entries of the REPL, like the script of orkeon run β are readable wherever they are, without it. |
The last five are detailed in CLI TypeScript commands; every value option accepts --x value and --x=value. --commands-dir, --crews-dir, --settings and --mount add up when repeated; --llm-log-path keeps the last one; --ui and --repl-wrap keep the first one and always take the next word as their value (--repl-wrap --ui plain exits 2), and --ui= is auto. --replay and --log-level refuse a value that starts with -- (--replay --interactive names no file: exit 2). The standard .NET host switches (--Key=Value configuration overrides) apply as well.
Settings. The REPL reads the settings the runners read, in their order: the environment variables without a prefix, the --settings files β else the global file orkeon init writes; a file named on the command line replaces it, as for orkeon run β, then the ORKEON_ environment variables, prefix removed (ORKEON_Llm__ApiKey is Llm:ApiKey here as in every runner); the command line stays last. Nothing else: neither the appsettings.json of the current directory nor user secrets (where settings are read from). Its Llm section and profiles are read by the runners' reader, ApiKeyEnvVar included, and the log pane says once where each key comes from, with one warning per reference to a variable set nowhere.
A refused setting. The REPL judges its settings at its start as orkeon run does: a value, a key, a name it refuses, a log level that is none, an Orkeon:Rag:LlmProfile it does not offer, a --settings file it cannot read (named, with the line and the position) β one line, orkeon-repl: <reason>, on stderr, and exit code 1, before the console opens. An invalid flag keeps its exit code 2.
Tool-call approvals. With the permission gate on (Orkeon:Security:PermissionGate:Enabled = true), a tool call the session's mode asks about β anything but a read in default, a command in acceptEdits β is put to you instead of being refused. A crew running in the background writes the question in the console, named after its task (? [t1] dev-batches: tool 'shell_command' requires approval (mode 'default')., then the tool and its arguments), and the prompt becomes approve <tool> for [t1]? [y] once / [s] session / [n] no > . In the split-pane console the question shows on the displayed screen and is recorded once in the asking task's screen, whichever screen is displayed; the plain console prints the question in the flow of its lines. In the TUI the question opens a selection panel in place of the prompt, on Yes: Enter confirms the option selected, so Enter straight allows the call once (y, s and n select one, none answers alone), Esc denies, and / hands it to the prompt. Once handed over, the status line shows the question while it waits, whatever runs (? [t1] dev-batches asks to run shell_commandβ¦ ({"command":"npm test"} Β· answer y once Β· s session Β· n no), the call cut at 60 characters), the task's row reads ? waits for approval of shell_command, and its detail (Enter on the row) gives the whole call. Your next line answers it: y runs the call, s runs it and allows the tool without asking until the REPL exits, n refuses it, and the model reads DENIED: β¦ The operator denied the call. as the tool's result (yes, session, no, o, oui and non are accepted too). A line starting with / still runs its command, the question waiting meanwhile (/cancel --ticket=<id> cancels the crew and withdraws its question); any other line asks the whole question again, so free text never reaches the assistant while a question waits. Several questions are shown one at a time. The wait does not count in the crew's time limit. A question is read between two commands, or, for a crew launched with runCrew (synchronous), by the waiting call itself, and the time taken to answer does not count in RunCrewTimeout (limitations). Rules a command sets for the session (ctx.services.get("permissions"), scripted commands) decide a call before the mode: a call a rule allows runs without a question, except in plan, and a call a rule denies is refused in every mode. ctx.services.get("permissions").enabled says whether the gate is on: false, the rules and the modes check nothing.
human_input questions. A question the human_input tool asks is read by the next line, like an approval: the prompt becomes answer> , a numbered option or its value answers a choice, and an empty line takes the recommended option or the default. A question a background task asks names that task: [t8] dev-spec asks: <question>, then its options. In the split-pane console it shows on the displayed screen and in the task's own screen, the prompt reads answer [t8]> , and the answer is typed in the main field or in the task's thread (select the task in the tasks list, then Enter on the line); sent to a task that waits for no answer, the line stays in the field (@<task> waits for no answer: nothing was sent, the text stays in the field.). The plain console prints the question in the flow of its lines, tagged the same way. Once the answer is taken, [t8] answer taken: <answer> closes the question, so the next line is a new turn. Several questions are asked one at a time: the next one is announced ([t9] <task> has a question: asked once the one waiting is answered.) and written once the one waiting is answered. A question withdrawn before its answer says [t8] question withdrawn. While a tool approval waits, the main field answers the approval first, and the prompt does not read answer [t8]> . A line starting with / still runs its command while the question waits.
Session usage. A scripted command reads the session's LLM usage through ctx.services.get("usage").report() (scripted commands): the prompt, completion, cache-hit, cache-write and reasoning tokens of the session, then one row per model and one per command instance (a crew launched with runCrewAsync included), each with its cost β the vendor's charge, else the registry's price for the model (Orkeon:CostTracking), null when neither is known. The token_budget tool splits the tokens the session buffer holds by kind of entry (used_tokens_by_kind: system, user, assistant, tool, and other for a note), so a /context command can say what fills the window.
Replay. --replay <file> replays a session: each line of the file is fed exactly as if typed β a command, free text for the assistant, or the answer to a question. The file is read through the VFS, a relative path against the working directory (/workspace on a project); lines end with LF or CRLF; a blank line and a line whose first non-space character is # are skipped. Before each line the replay waits until no command instance runs, background crews included (/tasks), and stops waiting as soon as a question asks for the line: a tool-call approval, or a human_input question, is answered by the next line of the file, as you would answer it. The replay stops at the first error β a command that fails or is cancelled, an unknown command, a background task the replay launched that ends failed or whose completed() callback throws ([t1] <command> completed() failed: <error>, charged to the line that launched it; a completed() that only runs long is waited for, not an error), a question still waiting when the file ends (replay ended with an approval waiting: <tool>), a command that reads a line the file does not have (the read gets the end of the input, under --interactive too: the keyboard comes back only after the stop line), Ctrl-C (which also cancels the running command; in the TUI, the interrupt key Esc Esc) β with replay stopped at line N: <cause>, on a line of its own. One line answers one approval, whether the read loop or a waiting runCrew reads it; a session-wide answer (s) also settles every queued approval of the same tool at once, so the file carries no line for those. The replay concludes only once the command in flight, the background work it launched and their completed() callbacks (with whatever those launch) have ended, so a failure after the last line still counts. A second Ctrl-C while the replay is still stopping (a command that ignores its cancellation), or a Ctrl-C with no replay running, ends the process as usual (exit code 130 on Linux and macOS). Alone, --replay then exits with code 1; with --interactive it hands the keyboard back, as it does at the end of the file (replay finished: N line(s)). Inside a session, /replay <file> replays a file the same way and always hands the keyboard back; it is refused while a replay runs.
# smoke.replay β run with: orkeon-repl --runner=scripted-commands --replay smoke.replay
/help
/dev-batches plan.md
# the crew asks to run shell_command: allow it for the session
s
/tasks
MCP servers and plugins. The REPL connects the servers its settings declare under MCP:Servers before it loads its commands, as orkeon run does before a crew loads, and loads the plugins of a Plugins section. Their tools reach a command's tools namespace and the crews it runs (.tools([...]), act) like the built-in ones; a server that fails costs one error line and the REPL starts. See MCP integration and Plugins.
The other shipped binaries
The release archives carry more launchers than the two documented here: orkeon-slim
(the same CLI, framework-dependent) and orkeon-host (the long-running service daemon β
see the service host). That is the whole list. The
publication matrix and
Three ways to run Orkeon list exactly
which archive carries what.
See also: Three ways to run Orkeon Β· Run your first example Β· Back to index