Table of Contents

🇫🇷 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), scaffolds a configuration, probes LLM providers, drives the RAG subsystem, and diagnoses an installation. It is built from src/scripting/Orkeon.Scripting.Cli and packs as the dotnet tool orkeon:

dotnet tool install --global Orkeon.Scripting.Cli --prerelease
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.

Exit codes (stable): 0 OK · 1 script/config error (missing file, invalid script, validation failure) · 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) · 130 cancelled with Ctrl+C. 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).

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: .ork.ts/.js goes to the scripting host (esbuild transpile + Jint), .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) — goes to the shared one-shot YAML 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. The virtual path is always a name starting with / — never a disk path (ADR-008), and /crew, /script, /llm-logs and /sandbox are reserved by the runner (RunnerVirtualRoots.All): a mount claiming one is refused with exit 1, and refused the same way whether it was written here or declared in the settings file — the guard reads both, and names the roots this command reserves rather than a fixed list. 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 name Studio gives a team's write folder, forges unchanged. Against the settings file, a --mount is placed by virtual root: on a root Orkeon:FileSystem:Mounts already declares (settings file or ORKEON_ environment), 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 (VFS-90). A settings entry may carry an id — the 26-character ULID before its |, 01J9Z3K4M5N6P7Q8R9S0T1V2W3|C:\data:/output:rw; Orkeon Studio writes 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.). 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 --mount base path is added to the PathSecurity:AdditionalAllowedDirectories whitelist PathValidator checks resolved paths against, after whatever the settings already list there. A mount declared in the settings file (or through ORKEON_ variables) needs no flag: its base path is always whitelisted, because a declared folder is the machine owner's explicit intent — until then such a folder was mounted and every access to it refused as "outside the allowed workspace directory", and no flag could rescue it.
-v, --verbose <0-2> 0 quiet, 1 LLM & tool exchanges, 2 full debug.
--llm-log / --llm-log-path <dir> Log full LLM exchanges as JSONL (default directory ./llm-logs).
--inputs <json> / --inputs-file <path> Structured inputs for scripts (global inputs variable).
-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.
--memory-limit-mb <n> Jint memory limit override for this run (0 disables it).
--validate Dry run: resolve settings, build the host, load the crew with strict tool resolution — no LLM call, no kickoff. Prints VALIDATION OK/FAILED: ….
--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. This is how Orkeon Studio watches a run. See The run event bus.
--stream With --events, also emit llm.delta events token by token. 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 studio). Agents can post and send to that address; a crew's links: block authorizes it. 
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. Details and the ready-made profile matrix: Run your first example.

orkeon forge

orkeon forge "summarize my supplier's new offers every morning"   # start from a need
orkeon forge                                   # start with the interview
orkeon forge list                              # list the workspace's sessions
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>         # ship a ready session as an ordinary folder
orkeon forge reopen <team-folder>              # find — or rebuild from crew/ — the session of a promoted team

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.

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 and reopen are fully offline.

reopen <team-folder> makes a promoted team modifiable again when its session is gone — deleted, or the folder was forged on another machine or imported. When a session still points at the folder (promotedTo), it is only named: resume it. Otherwise 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 now 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 lands at the --dry pause, pointing back at the folder: 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 Orkeon Studio's « Modify » works on a team no session points at.

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 Orkeon Studio drives the forge).
--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. With --dry, the session pauses again at the same boundary. 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»). Refused anywhere else, with FORGE-INVALID-STATE.
--max-iterations <n> / --max-tokens <n> / --max-seconds <n> The budget (default 3 iterations; 0 = unlimited tokens/time). Resuming may raise it; consumption always carries over.
--settings <path> Same semantics as orkeon run — long form only: the forge parser is bespoke and defines no short aliases.
--read <dir> (new session, resume) The folder the trial reads as /workspace, 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 three roots, so there is no --allow-external-mounts here. This is how Orkeon Studio tries a team on the folder chosen at its first step.
--pack <dir> Override the embedded prompt pack.
--to <dir> (promote) Destination folder; must not exist or be empty.
--schedule daily@HH:mm\|hourly (promote) Generate schedule artifacts under schedule/ — Windows task XML, systemd timer, cron line. The install command is displayed, never executed: Orkeon has no scheduler.
--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 sandbox: the try runs in-process with writes confined to the session's own directory (/output for deliverables, /forge for its working files), the working directory — or the --read folder — mounted read-only as /workspace, and shell_command/code_interpreter 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), run.sh/run.cmd composed against the orkeon run grammar with your sample inputs pre-filled, FORGE.md — the crew's identity card (goal, acceptance criteria, verdict, version), written in the interview's language — and forge.json, its machine-readable twin (slug, title, format, promotion instant, brief) that forge reopen reads. 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; the Studio launcher detects the folder and lays the mounts itself.

orkeon init

Configuration assistant. Generates a valid appsettings.json at the global per-user path (%APPDATA%\Orkeon\appsettings.json on Windows, ~/.config/Orkeon/appsettings.json on Linux/macOS) 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.
-u, --base-url <url> / -m, --model <id> Endpoint and model. Required for custom; presets have defaults.
-k, --api-key-env <name> / --api-key <value> Env var holding the key, or a key to store.
--path <file> Write somewhere other than the global per-user path.
-f, --force Overwrite an existing file.
--no-probe Skip the endpoint probe. 
orkeon init --provider ollama --model llama3.2 --no-probe

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), -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; default all), --archive <dir>, --format md|json, --commit, --timeout (seconds, 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).

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

Three verbs over the RAG subsystem (ingest, search, eval). All share the host options of run: -s/--settings, -m/--mount, --allow-external-mounts, -v/--verbose. 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> (required; several sources space-separated after one flag), --chunking recursive|sentence|structural|semantic, --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).

orkeon rag eval — evaluates a collection against a golden dataset (recall@k, MRR, groundedness) and writes markdown/JSON reports: -d, --dataset (required), -c, --collection, --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), --no-ingest, --reindex, --min-recall / --min-mrr (anti-regression gates, exit 1 below threshold), --output (default /output/rag/eval).

orkeon rag eval --dataset examples/rag/eval/golden.yaml \
  --compare fast,balanced,quality,corrective,adaptive --offline

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). Nine checks: dotnet-runtime, appsettings, llm-config, llm-reachability, esbuild, local-embeddings, onnx-reranker, tree-sitter, workspace-write. Exit codes: 0 all green or warnings only, 1 at least one failing check.

orkeon doctor --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. See CLI TypeScript commands.

The other shipped binaries

The release archives carry more launchers than the two documented here: orkeon-slim (the same CLI, framework-dependent), orkeon-host (the long-running service daemon — see the service host), the two Studio TUIs (orkeon-studio-config, orkeon-studio-run) and the Windows desktop app (orkeon-studio) — see Orkeon Studio. 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

Edit this page