Référence du CLI orkeon
L'outil en ligne de commande orkeon est le point d'entrée principal du framework : il exécute les crews YAML et les scripts TypeScript (.ork.ts), transforme un besoin en langage courant en crew (l'Atelier), génère une configuration, sonde les fournisseurs LLM, pilote le sous-système RAG, cherche dans les cas d'usage d'exemple, connecte des comptes e-mail, liste et connecte des comptes drive, écrit les typings d'éditeur du DSL de scripting, sert ses outils à un client MCP, diagnostique une installation et liste chaque réglage qu'un hôte lit. Il est construit depuis src/scripting/Orkeon.Scripting.Cli et se packe comme dotnet tool orkeon :
dotnet tool install --global Orkeon.Scripting.Cli
orkeon doctor
Les binaires de release et les installeurs (zip/MSI Windows, paquet Debian, tarballs macOS) embarquent le même CLI, autonome — aucun SDK .NET requis. Voir Trois façons d'exécuter Orkeon.
Mettez le tool à jour avec dotnet tool update --global Orkeon.Scripting.Cli. La mise à jour de tous les autres canaux, et le suivi de main entre deux releases : Mettre à jour Orkeon.
Codes de sortie (stables) : 0 OK · 1 erreur de script/config (fichier manquant, script invalide, échec de validation, réglage refusé par le host) · 2 le run a échoué — une erreur runtime inattendue, un service que le host n'a pas pu construire au démarrage, ou une équipe qui a tourné sans réussir (une tâche sans réponse finale, un disjoncteur déclenché, un consensus non atteint) · 75 le run s'est arrêté sur une question à un humain et attend la réponse (EX_TEMPFAIL ; ni un succès ni un échec : le reprendre avec --resume <id> --input "...", entrée humaine durable) · 130 annulé par Ctrl+C. Une aide demandée (--help, -h, help) sort en 0 et s'imprime sur stdout (orkeon mcp : sur stderr) ; une erreur d'usage — une option inconnue, une option sans sa valeur, un mot de trop — sort en 1, écrit sa ligne sur stderr et rien sur stdout. Sur un code 2, la dernière ligne de stderr est ERROR: <raison> — la phrase qui dit pourquoi ; le type de l'exception et sa trace de pile ne sont journalisés qu'en --verbose 2 (ou ORKEON_DEBUG=1). Un réglage que le host refuse — une valeur qu'il ne convertit pas ou qu'une règle de sa section refuse, une clé qu'aucune section ne porte, un nom de section ou de composant qu'il ne connaît pas (un fournisseur de mémoire, un reranker, un profil RAG, un niveau de journal), un profil LLM qu'il ne sait pas construire, un fichier de réglages qu'il ne peut pas lire (nommé, avec la ligne et la position), une adresse qui n'en est pas une (RaggableTree:Embedding:BaseUrl, Telemetry:OtlpEndpoint) — sort en 1 sur une ligne qui le nomme, la dernière de stderr, avant le chargement de l'équipe et avant tout appel au modèle. Tout réglage que le host lit est jugé à son démarrage, que le run s'en serve ou non — Logging compris —, hors comptes e-mail : un compte illisible est mis de côté et signalé quand on le nomme (quand un réglage est refusé). La ligne est ERROR: <raison> pour orkeon run sur une équipe YAML, un dossier d'équipe ou un .ork.ts déclaratif, --validate, --list-tools et orkeon mcp serve (un run --events jsonl ferme toujours son flux sur run.finished, exitCode 1), orkeon run: <raison> pour un script procédural, orkeon forge: <raison> pour la forge ; ORKEON_DEBUG=1 imprime l'exception et sa pile avant elle.
La ligne de commande. orkeon, orkeon --help, orkeon -h et orkeon help impriment la liste des commandes et sortent avec 0 ; orkeon <commande> --help imprime les options d'une commande. orkeon --version (ou orkeon version) imprime orkeon <version> — -v n'est pas la version, c'est --verbose. orkeon --version --verbose garde cette ligne et en ajoute une seconde, channel: <canal> : le canal par lequel ce build a été installé, tel que orkeon doctor le nomme, pour qu'un programme le lise. Les commandes sont run, quickstart, init, doctor, settings, llm, rag, eval, forge, usecases, email, drive, typings, mcp et runs, reconnues avant toute autre chose — orkeon settings reste donc la commande même dans un dossier qui contient un répertoire settings/. La liste se termine par deux adresses : le site de documentation, et la référence de configuration que orkeon settings donne hors ligne. Le verbe run est facultatif : un premier argument qui commence par -, ou qui se lit comme une crew — il contient un / ou un \, se termine par .ork.ts, .ork.js, .ts, .js, .yaml ou .yml, ou nomme un fichier ou un dossier existant — est confié à orkeon run. Tout autre mot est refusé avec orkeon: unknown command '<mot>' et le code 1.
La règle des arguments (toutes les commandes). La valeur d'une option s'écrit --option valeur ou --option=valeur. Attachée à un nom long, la valeur est lue telle qu'elle est : coupée au premier =, un - de tête, une espace de tête et un saut de ligne conservés ; seule une valeur vide (--option=) est refusée. Séparée, une valeur qui commence par - est lue comme l'option suivante, et refusée. -- termine les options : tout mot qui le suit est positionnel, quelle que soit sa forme. Un mot qu'aucune option ni valeur ne prend est refusé avant tout travail, par orkeon <commande>: unexpected argument '<mot>' et le code 1.
orkeon run
orkeon run <crew.ork.ts | crew.yaml | répertoire-crew/> [options]
Exécute une définition de crew et imprime son résultat sur stdout. Le dispatch dépend de la cible : .yaml/.yml — ou un répertoire contenant un crew YAML multi-fichiers (config.yaml + agents/ + tasks/, ou le triplet plat crew.yaml/agents.yaml/tasks.yaml), à sa racine ou sous son sous-dossier crew/ — le dossier d'équipe qu'écrit forge promote, dont crew/ est la définition quoi que porte la racine : un point de montage nommé agents/ ou un point d'entrée de script (*.ork.ts) à côté est mis de côté, jamais lu comme une crew ; une marche, jamais crew/crew/ — part vers le runner one-shot partagé, qui imprime la sortie de la crew sous une bannière === Crew Output ===. Tout autre fichier est un script (.ork.ts, .ts, .js), assemblé par esbuild et exécuté par Jint, et c'est sa source qui choisit le moteur (les deux formes) : un script qui affecte globalThis.crew est une définition de crew déclarative et part vers le même runner partagé que le YAML (tâches, process et manager honorés) ; tout autre script est procédural — l'hôte de scripting l'exécute et imprime son résultat en JSON. --validate et --list-tools passent toujours par le runner partagé.
| Option | Description |
|---|---|
-s, --settings <chemin> |
Chemin vers appsettings.json. Sans elle, une chaîne de repli s'applique (ci-dessous). |
-m, --mount <spec> |
Montage VFS, format Docker <physique>:<virtuel>:<droits>[;sous-chemin:droits]. Plusieurs montages se passent séparés par des espaces derrière un seul flag (--mount a:/x:ro b:/y:rw) — le parseur rejette un --mount répété. Une lettre de lecteur Windows ne demande rien de particulier (C:\src:/workspace:ro) ; un chemin que la forme nue ne peut pas porter — contenant un : ou un ;, ou finissant par une barre oblique inverse — se met entre guillemets : "/data/odd:name":/data:ro, "C:\src\":/workspace:ro. Ces guillemets appartiennent à la grammaire des montages, donc votre shell ne doit pas les manger : en bash/zsh, entourez toute la spec de guillemets simples (--mount '"/data/odd:name":/data:ro') ; en PowerShell, doublez-les (--mount '""/data/odd:name"":/data:ro'). La barre oblique inverse n'est jamais un caractère d'échappement ; un " à l'intérieur d'un chemin entre guillemets se double ("/data/a""b":/data:ro). Le chemin virtuel est toujours un nom commençant par / — jamais un chemin disque (ADR-008), et /crew (une crew) ou /script (un script), /llm-logs, /llm-mock, /llm-cassette, /sandbox, /state, /runs et /credentials sont réservés par le runner : un mount qui en revendique un est refusé avec le code 1, et refusé de la même façon qu'il ait été écrit ici ou déclaré dans les settings — dans le fichier, ou par une variable, préfixée ORKEON_ ou non : les gardes lisent les couches que lit l'hôte (d'où viennent les réglages), et celle-ci nomme les racines que cette commande réserve plutôt qu'une liste figée. /credentials est réservée par toutes les commandes : le runner y garde les jetons OAuth des comptes e-mail et drive (orkeon email, orkeon drive). orkeon forge ne réserve que /sandbox : il n'accepte aucun --mount, monte lui-même /workspace, /forge et /output, et place ces trois racines face aux settings exactement comme un --mount l'est (phrase suivante) — une entrée des settings sur l'une d'elles est remplacée pour l'essai, si bien qu'un fichier de settings nommant /output, mount ordinaire d'un run normal et nom habituel du dossier d'écriture d'une équipe, forge sans rien changer. Face aux settings, un --mount est placé par racine virtuelle : sur une racine que Orkeon:FileSystem:Mounts déclare déjà (fichier de settings, ou environnement, préfixé ou non — les couches que lisent les gardes), le --mount remplace toutes les entrées des settings de cette racine pour ce run — il est écrit à l'index de la première entrée, les autres sont retirées, et le journal dit mount /x: --mount replaces the settings entry ; sur une racine neuve, il est ajouté après toutes les entrées déclarées. Les entrées des settings qu'aucun --mount ne nomme restent en vigueur. Une racine n'est en double que lorsqu'une même source la revendique deux fois sans que rien ne distingue les revendications : deux --mount sur la même racine (--mount a:/x:ro b:/x:rw), ou un fichier de settings qui déclare deux fois une racine avec une entrée sans identifiant (ligne suivante), sont refusés avec le code 1 et une seule ligne (ERROR: '/x' is mounted twice on the command line: … Keep one. / … declared twice in <settings> (…) and '<entrée>' has no id. Give every entry an id …), avant qu'aucun host ne soit construit. |
--mount-id <ulid> |
Sélectionne, parmi plusieurs entrées des settings déclarant une même racine virtuelle, celle que ce run garde. Une entrée des settings peut porter un identifiant — l'ULID de 26 caractères devant son |, 01J9Z3K4M5N6P7Q8R9S0T1V2W3|C:\data:/output:rw ; un client peut en écrire un à chaque enregistrement — et deux entrées ne partagent une racine que si toutes deux en portent un. Plusieurs identifiants se passent séparés par des espaces derrière un seul flag, comme --mount. L'entrée désignée est gardée telle que déclarée (dossier, droits) ; les autres entrées de sa racine sont retirées pour le run — pas montées, pas en liste blanche, leur dossier pas sondé. Sans l'option, le bloc mounts: de la crew (<ulid>|/output, voir le schéma YAML) sélectionne de la même façon ; sans l'un ni l'autre, une racine déclarée plusieurs fois est refusée avec le code 1 et une ligne qui nomme chaque identifiant (ERROR: '/output' is declared twice in <settings> (<idA>: <dossierA>, <idB>: <dossierB>) 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.). Cette ligne est celle d'une crew YAML : elle ne nomme que ce que la commande offre pour choisir — --mount-id et --mount pour un script et --list-tools (Pass --mount-id <id> or pass --mount <folder>:/output:rw to replace them all.), --mount seul pour orkeon rag et orkeon-repl, pour orkeon forge et orkeon mcp serve, qui n'offrent rien pour choisir, pas d'erreur : la racine est retirée — aucune de ses entrées n'est montée pour le run — avec un avertissement ('/x' is claimed by <ids> in <settings> and nothing selects one: no entry of it is mounted for this run.), et mcp serve, s'il ne lui reste aucun montage, monte le répertoire de travail en /crew:ro. Un identifiant qu'aucune entrée ne porte, ou mal formé, est refusé de même ; un --mount sur la même racine l'emporte sur l'option, avec une ligne WARNING: ; une racine que la crew exige et que rien ne fournit est refusée aussi (the crew requires '/output' … pass --mount <folder>:/output:rw). Les agents ne voient jamais un identifiant : list_mounts et les messages de refus d'accès ne nomment que des chemins virtuels. |
--allow-external-mounts |
Autorise les arguments --mount hors du répertoire de travail (ou ORKEON_ALLOW_EXTERNAL_MOUNTS=1) : le chemin de base de chaque --mount de ce genre est ajouté à la liste blanche PathSecurity:AdditionalAllowedDirectories contre laquelle PathValidator vérifie les chemins résolus, à la suite de ce que les settings y listent déjà. Sans lui, un --mount hors du répertoire de travail est refusé au démarrage, avant tout appel au modèle : code 1 pour orkeon run et le REPL, sur une ligne The mount <racine> (<physique>) 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. Rien n'implique le drapeau — ni une crew, ni rag, ni la forge. Un montage n'en demande aucun quand il est une entrée de la commande : toute entrée que les settings déclarent et qui est en vigueur (une entrée choisie par id avec --mount-id comprise), le dossier d'un script, la racine d'un corpus rag. Un dossier qui est lui-même un lien symbolique est ajouté à la liste blanche avec sa cible, pour chaque chemin de base ci-dessus et chaque entrée. Le même drapeau est demandé pour un <config> YAML et pour un dossier --llm-log-path hors du répertoire de travail : sans lui, code 1 et une ligne ERROR: --allow-external-mounts is required … qui nomme le chemin. |
--llm-profile <id> |
Lance le run sur le profil LLM d'hôte <id> — Llm:Profiles:<id> dans les réglages ou l'environnement ORKEON_ (configuration) — comme défaut du run : la section Llm devient ce profil, en entier, pour le run. Chaque champ qu'il épingle est pris, un champ qu'il laisse vide reste vide, et sa clé vient du profil (ApiKey, ou la variable que nomme son ApiKeyEnvVar), jamais du défaut. Chaque agent, tâche et manager qui ne nomme aucun profil à lui tourne dessus, comme tout ce qui tourne sur le défaut — le planificateur, le RAG quand Orkeon:Rag:LlmProfile n'en nomme aucun, llm.default_ dans un script. Les profils restent offerts par leur nom ; default n'élit rien ; l'identifiant se compare sans tenir compte de la casse. Un identifiant que la configuration ne définit pas est refusé avec le code 1 avant tout hôte, comme une crew qui nomme un profil inconnu échoue au chargement : ERROR: --llm-profile names the LLM profile 'x', which this host does not offer. Known profiles: default, deepseek, z-ai. …. Le journal de démarrage dit LLM profile <id> elected as the run's default (--llm-profile) et d'où vient sa clé. Un client peut l'écrire dans les lanceurs d'une équipe pour le réglage de modèle de l'équipe. |
--no-decision |
Désactive le circuit de décision pour ce run : les tâches de décision répondent par leur fallback. Il l'emporte sur Orkeon:Decision:Enabled=true dans les settings ; voir Modèles de décision. |
-v, --verbose <0-2> |
0 silencieux, 1 activité des agents et des outils — plus une ligne de résumé par échange LLM (fournisseur, modèle, statut, durée) quand --llm-log est actif —, 2 debug complet ; une réponse du modèle est un aperçu d'une ligne (300 caractères) en 1 et entière en 2, la réponse finale du run étant imprimée entière sous === Crew Output === ; une valeur hors de 0-2 y est ramenée. Le contenu des échanges n'est que dans les fichiers de --llm-log. Sans -v, les agents verbeux parlent (Orkeon.Verbose, Information) ; une règle Logging:LogLevel nommant Orkeon.Verbose ou Default l'emporte. |
--llm-log / --llm-log-path <rép> |
Journalise les échanges LLM complets (requête et réponse, en-têtes et payload) en JSONL (répertoire par défaut ./llm-logs, créé s'il manque) ; --llm-log-path implique --llm-log. Un dossier hors du répertoire de travail demande --allow-external-mounts. Ce que les fichiers gardent se règle dans LlmLogging ; aucun setting ne choisit le dossier. Recette : suivre le run et garder les échanges LLM. |
--llm-mock <fichier> |
Répond à chaque appel LLM depuis un fichier JSONL au lieu d'un modèle : hors ligne, sans appel réseau, avec la même sortie à chaque exécution. Un objet {"match", "regex"?, "content", "toolCalls"?} par ligne ; match est cherché, casse ignorée, dans le prompt (le dernier message utilisateur), comme expression régulière quand "regex": true, et la première ligne qui convient l'emporte. Avec "regex": true, $1 ou ${nom} dans content sont remplacés par ce que le motif a capturé ($$ écrit un dollar) : la réponse d'un manager peut nommer l'agent que son prompt liste. Une ligne avec toolCalls ([{"name", "arguments"}]) répond par ces appels d'outil. Les lignes qui conviennent à un prompt en forment le script, une ligne par tour : la première répond au prompt, et chaque tour de résultats d'outil que porte la conversation passe à la suivante ; deux appels d'outil successifs puis une réponse finale font donc trois lignes qui conviennent au même prompt ; au-delà de la dernière ligne, une dernière ligne content répond encore et une dernière ligne toolCalls fait échouer l'appel, de sorte qu'un mock ne réclame jamais un outil à l'infini. Un prompt qu'aucune ligne ne convient, un motif qui dépasse son délai ou une ligne mal formée (son numéro est nommé) fait échouer l'appel, y compris en flux ; le flux tient en un seul fragment. L'hôte journalise un avertissement par fournisseur mock construit, qui nomme le profil. Chaque profil LLM de l'exécution — la section Llm et chaque Llm:Profiles:<nom> — devient Provider: mock lisant le fichier (configuration) ; le dossier du fichier est monté en lecture seule sur /llm-mock, et ne peut contenir ni la crew ni le script (code 1, une ligne). La sonde du point d'accès avant l'exécution est sautée. |
--llm-record <fichier> |
Enregistre chaque appel LLM du run, avec sa réponse, dans une cassette JSONL : une ligne par appel, rangée sous une clé (le SHA-256 du profil, des messages, du message système, des outils et du mode d'outil, du format de réponse, du modèle et des options d'échantillonnage, horodatages et identifiants générés exclus) et un numéro d'occurrence pour un appel répété. Un appel en flux est gardé comme sa liste de deltas. Les clés d'API et les en-têtes d'autorisation sont masqués. Le fichier est écrit par le VFS : son dossier est monté en lecture-écriture sur /llm-cassette, ne peut contenir ni le crew ni le script (code 1, une ligne), et hors du répertoire de travail demande --allow-external-mounts. Exclusif avec --llm-replay et --llm-mock (code 1, une ligne). Voir Enregistrer et rejouer les appels LLM. |
--llm-replay <fichier> |
Répond à chaque appel LLM du run depuis une cassette écrite par --llm-record, sans appel réseau ni modèle : la même sortie que le run enregistré. Un appel que la cassette ne contient pas échoue par une ReplayMissException qui nomme le profil, le numéro d'appel et le prompt, jamais par un repli sur le réseau ; une cassette inexistante est refusée (code 1). Le dossier du fichier est monté en lecture seule sur /llm-cassette. Exclusif avec --llm-record et --llm-mock. Voir Enregistrer et rejouer les appels LLM. |
--test |
Pour un script procédural : lie le global test — test.mockLlm, test.mockTool, test.assertLlmCalled, test.assertToolCalled (DSL de script). Une attente de test.mockLlm est servie avant le modèle configuré (ou le fichier de --llm-mock) ; tout autre prompt va à celui-ci. Sans --test, le script n'a pas de test. Une crew YAML, un dossier de crew, un script déclaratif et --validate n'ont pas ce moteur de script : --test y est refusé (code 1, une ligne). |
--inputs <json> / --inputs-file <chemin> |
Entrées structurées pour un script procédural (la globale inputs). Un script déclaratif ou un crew YAML les ignore — un script déclaratif le signale sur stderr. |
-V, --var CLE=VALEUR |
Variable pour le CrewInput d'un crew YAML (gabarits de tâche {CLE}). Plusieurs variables séparées par des espaces derrière un seul -V (un flag répété est rejeté). |
--initial-context <texte> |
Contexte initial passé au CrewInput d'un crew YAML. Un texte qui commence par - — une liste à puces — s'écrit --initial-context=<texte> (la règle des arguments, ci-dessus). Les lanceurs d'équipe écrivent ainsi toute option à une seule valeur. |
--memory-limit-mb <n> |
Plafond mémoire Jint d'un script procédural (0 le désactive). Par défaut : Orkeon:Scripting:Limits:MemoryLimitBytes, 100 Mo. |
--validate |
Dry run : résout les settings, construit l'hôte, charge le crew avec résolution stricte des outils — aucun appel LLM, aucun kickoff. Imprime VALIDATION OK/FAILED: …. Sur un .ork.ts, vérifie d'abord les types du script avec tsc contre les typings que ce build livre (Orkeon:Scripting:Toolchain:TypeCheck, scripting) : une erreur de type imprime VALIDATION FAILED: type errors, puis une ligne <chemin virtuel>:ligne:col TSxxxx message par erreur, et sort en 1. Un .ork.ts procédural (sa source n'affecte jamais globalThis.crew) n'est pas chargé comme un crew : ses types sont vérifiés et il est bundlé, jamais exécuté, et la commande imprime VALIDATION OK: <config> (procedural script: bundled, not run). Une crew qui se charge, YAML ou .ork.ts, dont une tâche déclare un deliverable en source: tool_call (le défaut) qu'aucun agent capable d'exécuter la tâche ne peut écrire imprime une ligne par tâche concernée sur 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., qui nomme chaque agent que le processus peut choisir quand il y en a plusieurs ; pour un fichier binaire elle nomme l'outil du format (docx_writer) et propose un format texte au lieu de final_message, et une tâche de décision qui déclare un deliverable imprime WARNING: Task '<name>' is a decision task: its deliverable '<path>' is never written, … — et le code de sortie reste 0 (livrables vérifiés au chargement). |
--input <réponse> |
La réponse à la question sur laquelle le run repris s'est arrêté (sortie 75) ; seulement avec --resume, refusé sans lui (sortie 1). La tâche qui a posé la question est rejouée et reçoit la réponse, les tâches déjà faites ne sont pas rejouées ; le run est refusé s'il n'attend aucune réponse. Sans --input, un run repris qui retrouve la même question s'arrête de nouveau avec 75. |
--resume <id\|latest> |
Reprend un run échoué ou tué de cette crew au lieu d'en commencer un autre (checkpoint par tâche) : les tâches qu'il avait terminées répondent depuis le checkpoint, les autres s'exécutent, et le run garde son id. Un run échoué imprime cet id (Run <id> did not complete. Resume it, its finished tasks kept, with: orkeon run <crew> --resume <id>) ; latest est le run le plus récent du fichier de crew qui n'est pas terminé ; un run encore marqué Running est refusé (il peut être vivant dans un autre processus) : nommer son id pour le reprendre. Une tâche modifiée depuis est rejouée, avec chaque tâche qui la suit. Demande Orkeon:Checkpointing:Enabled=true (refusé sinon, exit 1) ; refusé avec --validate, --list-tools et un .ork.ts procédural ; avec --events il faut l'id explicite, pas latest. Les décisions du manager d'une crew Hierarchical ou Autonomous sont rejouées en direct. |
--list-tools |
Construit l'hôte, imprime le registre trié des outils runtime, puis sort. Aucun chemin de crew requis. |
--events jsonl |
Émet le protocole d'événements versionné sur stdout au lieu du rendu texte, et lit des commandes sur stdin. C'est ainsi qu'un client observe un run. Voir Le bus d'événements du run. jsonl est la seule valeur ; toute autre est refusée avec le code 1. |
--stream |
Avec --events, émet aussi les llm.delta jeton par jeton (le texte, et les fragments des appels d'outils que le modèle construit). Verbeux par nature : désactivé sauf demande. |
--client <nom> |
Avec --events, le nom auquel le processus observateur répond sur le hub du run (client://<nom>, défaut client). Les agents peuvent lui écrire à cette adresse ; le bloc links: d'une crew l'autorise. Un nom vide ou contenant un / est refusé avec le code 1 ; sans --events, l'option est sans effet, et un avertissement le dit quand le nom n'est pas le défaut client. |
orkeon run examples/01-enterprise/01-research-assistant/config.yaml \
--settings examples/appsettings/appsettings.deepseek.local.json \
--mount ./out:/output:rw -v 1
Résolution des settings — sans --settings, le CLI suit une chaîne de repli : appsettings.json à côté du fichier de crew, puis un appsettings/appsettings.json trouvé en remontant les répertoires parents, puis le fichier global par utilisateur écrit par orkeon init, puis les variables d'environnement ORKEON_* seules. Un --settings explicite qui nomme un fichier inexistant arrête la chaîne là — une ligne WARNING:, puis les variables d'environnement seules — au lieu de passer à l'emplacement suivant. Détails et matrice de profils prêts à l'emploi : Exécuter votre premier exemple.
orkeon quickstart
orkeon quickstart # écrit l'équipe de deux minutes dans ./orkeon-quickstart/
orkeon quickstart --to demo
Écrit l'équipe de la section Essayez-le en deux minutes du README dans un nouveau dossier : crew.yaml (un agent, l'outil file_write, une tâche qui écrit /output/hello.md), son appsettings.json (Ollama sur localhost:11434, qwen2.5:1.5b) et un out/ vide. Les deux fichiers sont embarqués dans l'outil, octet pour octet depuis examples/quickstart/ : un dotnet tool install suffit — pas de clone. --to <dossier> (ou --to=<dossier>) choisit le dossier (./orkeon-quickstart par défaut, créé s'il manque). La commande n'écrase jamais rien : un fichier, ou un dossier non vide, à cet endroit est refusé et rien n'est écrit. Elle imprime ensuite les deux exécutions à lancer depuis ce dossier — orkeon run crew.yaml --mount ./out:/output:rw, qui écrit out/hello.md, et la même avec :ro, que le service de fichiers refuse (required Write, effective ReadOnly). Hors ligne. Codes de sortie : 0 écrit, 1 un fichier ou un dossier non vide à la cible, une option inconnue ou un mot de trop, ou --to sans dossier (--to= compris).
orkeon forge
orkeon forge "résumer chaque matin les nouvelles offres de mon fournisseur" # partir d'un besoin
orkeon forge "trier mes e-mails par urgence" --reference 03-email-pipeline # partir d'un besoin, sur le modèle d'un cas d'usage
orkeon forge # ouvrir sur l'entretien
orkeon forge list # lister les sessions du workspace
orkeon forge rephrase "<demande>" # réécrit la demande en brief clair, puis sort
orkeon forge resume <slug> # reprendre une session exactement là où elle s'est arrêtée
orkeon forge resume <slug> --read <dir> # l'essayer sur les documents de <dir>
orkeon forge resume <slug> --adopt # garder l'équipe telle quelle, sans essai
orkeon forge promote <slug> --to <dir> --name <équipe> # sortir une session prête en dossier ordinaire, au nom de l'équipe
orkeon forge reopen <dossier-equipe> # retrouver — ou reconstruire depuis crew/ — la session liée à une équipe promue
orkeon forge schedule <dossier-equipe> # installer la planification de l'équipe dans le planificateur du système
orkeon forge schedule <dossier-equipe> --check # dire si elle est installée, absente ou à réinstaller
orkeon forge unschedule <dossier-equipe> # la retirer, avec schedule/ et l'enregistrement de forge.json
orkeon forge rename <dossier-equipe> --name <nom> # renommer l'équipe : dossier, session, titres, planification — tout ou rien
L'Atelier : un parcours guidé du besoin en langage naturel à l'équipe déployable. Un assistant vous interroge et capte un brief structuré — objectif, entrées, critères d'acceptation, un exemple d'entrée — puis propose un plan d'équipe, le rend, le valide, l'essaie en bac à sable sur votre exemple, et juge le résultat contre vos propres critères. Non conforme ? Le diagnostic alimente une boucle de correction, bornée par un budget dur (itérations, jetons, temps). Chaque session vit sous .orkeon/forge/<slug>/ — reprenable, diffable entre tentatives, auditable.
forge rephrase <demande> demande au LLM de l'assistant de réécrire la demande en un brief clair — ce qui entre, ce qui sort et sous quelle forme, chaque règle énoncée, dans la langue de la demande, sans rien inventer — puis s'arrête : aucune session, rien d'écrit. La demande est constituée des mots qui suivent le verbe ; --events jsonl répond par une ligne need.rephrased (text, original), le terminal affiche le texte ; --settings est honoré, toute autre option refusée. Sans LLM, FORGE-LLM-UNAVAILABLE ; réponse vide, FORGE-REPHRASE-EMPTY ; code 1 dans les deux cas.
L'empreinte d'embeddings. orkeon forge consigne l'empreinte d'embeddings (le fournisseur, le modèle et les dimensions dont viennent les vecteurs stockés) dans /forge/embedding-fingerprint.json, un montage qu'il peut toujours écrire : un /workspace en lecture seule ne produit plus d'avertissement ; Orkeon:Embeddings:FingerprintPath remplace ce défaut. Le montage vit le temps d'une session : le garde-fou protège une session, rien d'une session à l'autre.
La ligne de commande de la forge. La règle des arguments ci-dessus s'applique, avec les phrases propres à la forge. -- termine les options et ce qui suit est le besoin (un client écrit toutes les options d'abord et le besoin en dernier, après --). --option=valeur est lue pour les noms longs, coupée au premier = ; une valeur vide est refusée avec la phrase de l'option. --events attaché ne prend que jsonl : --events takes only the value jsonl. Un drapeau écrit avec une valeur est refusé : <flag> takes no value. (--auto=true : --auto takes no value.). list takes no argument. et promote and resume take the session slug only: no other word. sont les phrases des verbes ; tout refus sort en 1, une option inconnue comprise.
L'étape des dossiers. Entre le brief et le plan, la forge fixe les dossiers de l'équipe. L'assistant liste dans le brief (folders : path, role input|output, purpose, et examples quand le contenu change) chaque dossier que le besoin nomme — « …des PDF dans /inpdf, le Markdown dans /outmd » — ou décrit sans le nommer, alors nommé d'après ce qu'il contient (« un dossier de PDF avec les instructions, un autre avec les documents à joindre » → /instructions, /documents), plus un dossier de sortie dont le libellé a un sens pour l'équipe (le compte rendu des envois, quand le résultat n'est pas un fichier) ; s'il n'en nomme ni n'en décrit aucun, la forge propose /workspace à lire — seulement si l'équipe lit des fichiers ou des documents dans un dossier, ce que dit le readsFiles du brief ; si l'assistant ne l'a pas dit, si quelque chose entre — et /output où écrire, chaque libellé dans la langue du brief. Un dossier est un seul segment absolu de lettres, chiffres, -, _ ou . ; /forge et les racines propres au moteur sont refusés. Une liste sans dossier de sortie, ou sans aucun dossier, est valide : une équipe qui envoie des mails à partir de ce qu'elle lit n'écrit aucun fichier, aucune tâche de son plan n'a de deliverable, et son résultat est la sortie du run. Le purpose d'un dossier est la note de l'utilisateur sur ce qu'il contient et comment l'équipe doit s'en servir — un client peut la laisser modifier avant la confirmation — et le prompt du plan demande à l'assistant de la suivre. Le examples d'un dossier (un booléen, sur un dossier d'entrée seulement ; true sur une sortie est refusé) dit que ce que contient le dossier change d'un run à l'autre — une boîte de dépôt que l'utilisateur remplit à nouveau — si bien que les fichiers qui s'y trouvent à l'étape de remplissage sont des exemples de ce qui viendra : l'assistant le pose d'après le besoin, un client peut le poser à la confirmation, et son absence signifie un contenu fixe, le plan étant alors fait pour les fichiers mêmes qui sont là. La forge émet alors folders.proposed (folders, et defaults — vrai quand le besoin ne nommait aucun dossier) et attend folders.confirmed sur stdin ({"kind":"folders.confirmed","folders":[{"path","role","purpose","dir","examples"}]} — la proposition telle quelle ou modifiée, dir le dossier réel relié à un dossier, absent pour un dossier gardé dans l'équipe ; examples à true ou false décide, et un dossier d'entrée envoyé sans lui garde la valeur que la proposition donnait au même path, à la casse près, si bien qu'un dossier renommé le redit). Une liste qui enfreint les règles, ou relie un dossier qui n'existe pas, est un FORGE-FOLDERS-INVALID récupérable, et les dossiers sont proposés à nouveau. De même, quand le run essaie l'équipe dans ce même processus (sans --dry), d'un dossier d'entrée relié à un dossier réel que les outils fichiers du run n'autorisent pas — un dossier hors du répertoire de travail : ces outils gardent les dossiers avec lesquels ils ont démarré, si bien que le dossier serait monté pour l'essai puis refusé à chaque lecture. Le message dit le chemin qui marche : confirmer les dossiers dans un run qui s'arrête avant son essai (orkeon forge resume <slug> --dry), puis orkeon forge resume <slug>, dont l'hôte les monte et les autorise dès son démarrage. Dans le terminal, et avec --auto, la proposition est acceptée telle quelle et affichée, un dossier dont le contenu change étant signalé comme tel. La liste confirmée est gardée dans le folders.json de la session (avec les dossiers réels) et dans le brief (sans eux — un chemin physique n'atteint jamais un prompt), annoncée par brief.ready — dont les heldFolders (path, role, dir) sont les dossiers gardés dans l'équipe, chacun créé dès maintenant sous le folders/<nom> de la session pour qu'on puisse y déposer des fichiers avant l'essai ; le terminal les affiche — et sert partout ensuite : les livrables du plan doivent tomber dans un dossier de sortie confirmé (FORGE-BLUEPRINT-INVALID / réparation sinon), et une tâche qui nomme, dans sa description ou sa sortie attendue, un chemin sous un dossier de sortie où tombe un livrable doit nommer son propre livrable, le livrable d'une de ses dépendances (transitivement), ou un fichier déjà présent sous un dossier de sortie — tout fichier trouvé récursivement sous un dossier que l'équipe garde ou qui est lié à un dir de l'utilisateur, jusqu'à 10 000 par dossier, sans plafond de 40 entrées ; être listé avant ne suffit pas, quel que soit le processus, un lecteur liste son écrivain (la règle de passation) — sinon le plan est refusé avec une erreur qui nomme la tâche et le chemin, que l'assistant reçoit pour corriger (la même vérification s'applique à une édition de verdict et à l'étape Blueprint ; reopen lit sans elle une équipe promue avant la règle, et la validation suivante l'applique) — la même règle lit l'objectif et la backstory de chaque agent : un chemin sous une racine de livrable qui y est nommé doit être un livrable d'une des tâches de l'agent, d'une tâche dont elles dépendent, ou un fichier existant, et un agent sans tâche (un manager, un arbitre) peut nommer le livrable de n'importe quelle tâche, tout comme n'importe quel agent d'une équipe hierarchical, consensual ou autonomous (sequential, parallel, graph et un processus absent gardent la règle par agent ; un chemin qu'aucune tâche ne livre et qu'aucun fichier existant ne porte est refusé dans tous les modes) ; un chemin qui est un dossier est accepté quand un livrable autorisé ou un fichier existant s'y trouve, pour les tâches comme pour les agents ; le refus nomme agents[i] ('key'), le champ (goal ou backstory) et le chemin, et le remède est de retirer le chemin de l'objectif ou de la backstory, de donner à l'agent la tâche qui l'écrit, ou une dépendance vers cette tâche ; reopen n'applique pas la règle —, le bloc mounts: de l'équipe nomme la liste, l'essai la monte, la promotion la porte. Une session arrêtée à cette question la repose à la reprise, sans nouvel entretien.
L'étape de remplissage. Quand la liste confirmée contient des dossiers gardés dans l'équipe, la forge attend après brief.ready un folders.filled sur stdin ({"kind":"folders.filled"} : les fichiers sont en place, ou il n'y a rien à déposer) et ne conçoit rien avant — le terminal demande Entrée, --auto n'attend pas. Elle lit alors ce que contient chaque dossier gardé et l'ajoute au brief comme contents du dossier (noms relatifs au dossier, un sous-dossier terminé par /, 40 au plus, le dernier comptant le reste ; jamais un chemin physique), que le prompt du plan nomme pour que les tâches soient faites pour ces fichiers. Pour un dossier dont examples est vrai, le prompt présente les mêmes noms comme des exemples qui seront remplacés : les tâches sont conçues pour ce que le dossier contiendra quand l'équipe tournera, aucune tâche, aucun objectif ni aucune backstory n'en nomme un, et le brief envoyé avec le prompt omet les contents et large de ce dossier (un conseil du prompt : aucune validation ne refuse un plan qui nomme un exemple). Un fichier de 128 Kio ou plus (à toute profondeur, le plus gros d'abord, dans la même limite), dans un dossier gardé ou dans un dossier lié à un dir de l'utilisateur, est nommé avec sa taille (report.md (750 KB)), et le prompt du plan ajoute les règles pour en lire un : chercher d'abord (grep), puis lire par plages, et donner à l'agent qui le lit un maxIterations d'au moins 30 — dit comme une règle pour tout gros fichier à venir, et pour aucun fichier par son nom, quand le dossier contient des exemples ; un dossier d'exemples qui ne montre aucun gros fichier reçoit quand même la règle de lecture (chercher d'abord, lire par plage), sans le plancher de maxIterations, puisque les exemples ne disent rien des tailles à venir (un conseil du prompt, non validé : la forge relève seulement à 6 un plafond prévu en dessous). La forge émet ensuite folders.filled (folders : path, entries). folders.json note l'étape comme réglée (filled) ; une session arrêtée pendant l'attente annonce de nouveau les dossiers à la reprise et attend de nouveau, sans nouvel entretien.
Démarrer ou reprendre un cycle exige un LLM configuré (orkeon init) : la forge refuse d'ouvrir l'entretien sans lui (FORGE-LLM-UNAVAILABLE) plutôt que de dégrader en silence. list, promote, reopen, schedule, unschedule et rename sont entièrement hors ligne.
reopen <dossier-equipe> rend une équipe promue à nouveau modifiable, quoi qu'il soit advenu de sa session. Une seule règle décide de la session à laquelle un dossier est lié (la règle R) : chaque session porte un identifiant stable — annoncé par session.started — que sa promotion recopie dans le forge.json du dossier, et la session qui porte cet identifiant est liée quand son promotedTo nomme le dossier, ou quand le dossier qu'il nomme a disparu ou ne porte plus l'identifiant : l'équipe a été déplacée ou renommée, et la session est pointée vers sa nouvelle place. Quand promotedTo nomme un autre dossier existant qui porte le même identifiant, ce dossier-ci est une copie, liée à rien ; un dossier sans identifiant, ou avec un identifiant qu'aucune session ne porte, n'est lié à rien non plus. Une session liée est seulement nommée : reprenez-la. Sinon — session supprimée, dossier forgé sur une autre machine ou importé, copie, dossier sans identifiant — une session est reconstruite depuis le dossier lui-même : le plan est relu depuis crew/ (config.yaml + agents/ + tasks/ par entité, ou un seul crew.yaml), le brief vient du forge.json que chaque promotion écrit à côté de FORGE.md — ou est dérivé du plan, et la commande le dit — et le crew est copié tel quel. La session reconstruite reçoit un nouvel identifiant, écrit dans le forge.json du dossier (créé sans brief quand le dossier n'en avait pas ; celui d'une copie est réécrit, si bien qu'elle ne peut plus atteindre la session de l'original, et sa session porte le nom du dossier de la copie), et se pose à la pause --dry, en pointant vers le dossier : le reopen suivant la retrouve, resume --edit --dry, resume, resume --adopt suivent comme d'habitude, et un promote --to vers le même dossier le met à jour en place. Un dossier sans crew YAML (crew script, disposition étrangère, fichiers qui ne décrivent pas un plan valide) est refusé avec FORGE-TEAM-UNREADABLE et les raisons ; le verbe n'accepte aucune option sauf --events. C'est ainsi que fonctionne le « Modifier » d'un client, sur toute équipe.
| Option | Description |
|---|---|
--format yaml\|script |
Format rendu (défaut yaml). script rend un crew.ork.ts éditable et exige esbuild — absent, une nouvelle session retombe sur YAML avec FORGE-ESBUILD-MISSING. Le format d'une session ne change jamais en reprise. |
--events jsonl |
Émet le protocole d'événements versionné sur stdout au lieu du rendu terminal ; les réponses descendent sur stdin (c'est ainsi qu'un client pilote la forge). La valeur est facultative : l'argument suivant n'est pris pour elle que s'il vaut jsonl, tout autre mot reste dans le besoin (orkeon forge --events veille des prix forge « veille des prix »). |
--auto |
Arbitre les verdicts non conformes sans humain, dans les limites du budget. |
--dry |
S'arrête après la validation — génère et valide, n'exécute jamais. Reprenez sans --dry pour essayer. |
--edit |
(resume) Amende le blueprint d'une session en pause avant son essai : le JSON amendé passe par le canal (blueprint.edited sur stdin en mode --events, une ligne collée dans le terminal), est validé intégralement, puis re-rendu de façon déterministe — zéro token LLM, même itération, mais un LLM configuré reste exigé (FORGE-LLM-UNAVAILABLE sinon). Avec --dry, la session se remet en pause à la même frontière. Sur une session qui n'est pas en pause avant son essai, il sort en 1 avec un message, sans événement. À l'arbitrage, utilisez plutôt la décision edit. |
--adopt |
(resume) Garde l'équipe telle qu'elle a été générée, sans essai : une session mise en pause par --dry passe directement à Ready. Entièrement hors ligne — pas d'hôte, pas de LLM, pas de dossier d'exécution, zéro jeton. Ce qui est sauté, ce sont les preuves que produit un essai, jamais un contrôle : à cette pause le crew est rendu et validé, et la promotion n'a jamais consommé d'artefact d'essai (verdict.json est facultatif et FORGE.md écrit « aucun verdict enregistré »). resume --adopt sur une session qui n'est pas à cette pause est refusé avec FORGE-INVALID-STATE ; --adopt hors de resume, ou avec --edit, est une erreur d'usage (code 1). Les options de cycle (--read, --auto, --dry, --pack, --max-*, --settings) sont sans effet sur une adoption. |
--max-iterations <n> / --max-tokens <n> / --max-seconds <n> |
Le budget (défaut 3 itérations, au moins 1 ; jetons et secondes valent 0 par défaut = illimité, une valeur négative est refusée). Une reprise peut le relever ; la consommation est toujours reportée. |
--settings <chemin> |
Mêmes sémantiques qu'orkeon run, ancrées au répertoire de travail — forme longue uniquement : le parseur du forge est artisanal et ne définit aucun alias court, ni --help (une option inconnue, --help compris, est refusée avec le code 1). |
--read <dir> |
(nouvelle session, resume) Le dossier que l'essai lit derrière le premier dossier d'entrée que la liste confirmée ne relie à aucun dossier réel (/workspace quand le besoin n'a nommé aucun dossier), à la place du répertoire de travail. Le répertoire de travail garde tous ses autres rôles — la session vit toujours sous son .orkeon/forge/<slug>/, les settings se résolvent toujours à côté : --read déplace les documents, pas l'atelier. Un dossier inexistant est refusé avec le code 1 avant toute création de session (--read names no directory) ; promote refuse l'option, puisqu'il ne monte rien. Un dossier de lecture hors du répertoire de travail est automatiquement mis en liste blanche pour les outils fichiers, comme orkeon run le fait pour le dossier de son script — les montages du forge sont les siens, il n'y a donc pas de --allow-external-mounts ici — et il en va de même d'un dossier réel relié à un dossier que la session avait confirmé quand le run a démarré (une reprise ; voir l'étape des dossiers pour un dossier confirmé pendant le run). C'est ainsi qu'un client réessaie une équipe rouverte sur son propre dossier d'entrée. |
--reference <id> |
(nouvelle session) Le cas d'usage qui sert de modèle à l'équipe : un identifiant d'orkeon usecases, dont le crew — agents, tâches, processus, outils de chaque agent — est montré à l'assistant qui conçoit l'équipe comme un modèle de structure, pas de contenu à recopier : le brief seul décide de ce que fait l'équipe. Montré quand l'équipe est conçue, jamais pendant l'entretien ; les outils que le catalogue du bac à sable n'offre pas en sont retirés, et sa taille est bornée — chaque texte coupé à 200 caractères, l'ensemble à 4 000 (environ 1 150 jetons), au-delà desquels la suite d'une équipe plus grande est coupée, et c'est dit. Mesuré le 2026-09-24 sur le vrai catalogue d'outils : une référence ajoute de 2 100 à 4 500 caractères à chaque appel qui conçoit l'équipe — +590 à +1 290 jetons estimés, +800 pour le cas d'usage médian, sur un appel d'environ 3 000 sans elle. La session l'enregistre (reference dans session.json : identifiant et titre) et l'annonce dans session.started ; une reprise ou une réouverture compose à nouveau avec elle, et l'option est refusée ailleurs que sur une nouvelle session. La promotion la trace : « Inspiré de : <titre> (<id>) » dans FORGE.md, à côté de la ligne de provenance (« Inspired by: » quand le brief n'est pas en français), et reference dans forge.json. Un identifiant inconnu est refusé avec le code 1 et USECASES-UNKNOWN-ID avant toute création de session et tout appel de modèle — une ligne error puis session.finished « failed » en mode --events. C'est ainsi qu'un client transmet le cas d'usage choisi dans une galerie. |
--lang <code> |
(nouvelle session, resume) La langue dans laquelle l'assistant converse et écrit le nom de l'équipe, ses agents et ses tâches : fr, en, es, de ou zh — l'anglais sans l'option. L'utilisateur la change en écrivant dans une autre langue ou en le demandant ; le brief enregistre alors cette langue (language), et l'équipe est conçue dans celle-ci. Refusée sur tout autre verbe, et pour tout autre code. C'est ainsi qu'un client transmet la langue de son interface (l'anglais, la valeur par défaut, n'est pas envoyé). |
--pack <dir> |
Surcharge le pack de prompts embarqué. |
--to <dir> |
(promote) Dossier de destination ; doit être inexistant ou vide — sauf s'il s'agit du dossier auquel la session est liée (celui vers lequel elle a promu, ou ce dossier déplacé ou renommé depuis ; jamais une copie, refusée avec la raison), qui est alors mis à jour en place. |
--name <équipe> |
(promote, rename) Le nom de l'équipe : il devient le titre de FORGE.md, de forge.json et de la session elle-même — sans lui, ils gardent l'objectif du brief ; pour rename, le nouveau nom, qui nomme aussi le dossier (ci-dessous). Pris tel qu'écrit, tiret initial compris : la valeur de --name n'est jamais lue comme l'option suivante. Un client le transmet toujours. |
--schedule daily@HH:mm\|hourly |
(promote) Génère les artefacts de planification sous schedule/ — XML de tâche Windows, timer systemd, ligne cron — et note la planification dans forge.json. La promotion elle-même n'installe rien : c'est forge schedule (ci-dessous). |
--check |
(schedule) Dit où en est la planification — installed, absent ou stale — sans rien changer. |
--with-settings |
(promote) Copie le fichier de settings résolu dans le dossier. Off par défaut — un settings porte souvent des clés API et le dossier est fait pour être partagé. |
La source du livrable. Le livrable d'une tâche du plan garde source: tool_call quand chaque agent qui peut exécuter la tâche l'écrit lui-même — l'agent que la tâche nomme dans une crew sequential, parallel ou graph ; chaque agent sauf le manager dans une crew hierarchical ou consensual ; chaque agent dans une crew autonomous —, avec un outil intégré qui écrit ce chemin (les outils qui écrivent), parmi ses propres outils ou ceux que la tâche accorde (tools: sur la tâche), comme le moteur les compte. Sinon la forge écrit source: final_message, et le framework enregistre la réponse finale de l'agent au chemin : aucun outil n'est accordé pour cela. Un livrable binaire (.docx, .xlsx, .pdf, une image…) n'est jamais le texte d'une réponse : la validation du plan refuse le plan quand un agent qui peut exécuter sa tâche n'a pas l'outil qui écrit son format, en nommant la tâche, les agents et l'outil à donner (docx_writer, xlsx_writer, image_generation), ou un format texte à livrer à la place quand aucun outil intégré ne l'écrit ; file_write n'écrit que des fichiers texte et ne compte jamais pour lui. reopen relit les tools: d'une tâche et applique aussi ce refus, bien qu'il lise une équipe sans la règle de passation : un fichier de crew dont le livrable binaire ne peut être écrit par aucun agent qui peut exécuter sa tâche est refusé, l'erreur nommant ce fichier. La crew YAML écrit source: final_message et laisse le défaut implicite ; crew.ork.ts écrit toujours la source (.deliverable({ path, source: "tool_call" }), que les typings exigent). reopen ne relit pas la source : il la déduit de nouveau du plan, si bien qu'une source modifiée à la main dans les fichiers de la crew est remplacée par celle que donne le plan.
Le bac à sable : l'essai tourne in-process avec les dossiers confirmés montés et rien d'autre de l'équipe — /workspace et /output seulement quand la liste les contient. Les écritures sont confinées au dossier de la session : chaque dossier de sortie atterrit dans folders/<nom> et est mis de côté dans runs/<n>/folders/<nom> après l'essai, là où la vérification des livrables regarde ; /forge contient ses fichiers de travail. Un dossier d'entrée lit le dossier réel qui lui est relié, sinon --read, sinon le répertoire de travail pour /workspace, sinon le folders/<nom> de la session — un dossier gardé dans l'équipe, lisible avant que l'équipe existe. shell_command/code_interpreter sont retirés du catalogue d'outils — le plan d'équipe ne peut nommer que des outils que la validation acceptera.
Le dossier promu est ordinaire : crew/ (ou crew/crew.ork.ts), un dossier par dossier confirmé (/workspace lit input/) — ce que la session gardait dans son folders/<nom> y est déplacé —, run.sh/run.cmd composés contre la grammaire d'orkeon run avec ces dossiers montés et vos entrées d'exemple pré-remplies, FORGE.md — la carte d'identité de l'équipe (objectif, critères d'acceptation, verdict, version), écrite en français quand le brief est en français, et en anglais pour toute autre langue — et forge.json, son jumeau lisible par la machine (identifiant de la session, slug, titre, format, instant de promotion, brief, et le cas d'usage qui lui a servi de modèle) que forge reopen lit — l'identifiant est ce qui relie le dossier à sa session où qu'aille le dossier. Aucun des deux fichiers ne nomme quoi que ce soit de la machine — ni chemin, ni commande : la section de planification de FORGE.md renvoie à orkeon forge schedule ., et ce que le planificateur d'une machine a enregistré reste dans schedule/. orkeon run <dir>/crew le lance — depuis l'intérieur de <dir>, et sans les --mount que fournit run.sh, si bien qu'une équipe qui produit des livrables n'écrit rien par cette voie ; un client qui pilote le CLI peut détecter le dossier et poser les montages lui-même. Un client qui adopte une équipe peut réécrire run.sh/run.cmd depuis leur team.json — le réglage de modèle de l'équipe en --llm-profile, chaque dossier lié à l'équipe comme le passe un lancement. Tous deux écrivent les lanceurs par un seul compositeur (TeamLauncherScript) : run.cmd est en UTF-8, pose chcp 65001 et rend la page de code de l'appelant avant qu'orkeon démarre ; chaque valeur arrive au run telle qu'écrite quoi que contienne le chemin de l'équipe (&, ^, %, !, accents) ; un saut de ligne devient une espace dans run.cmd — le fichier le dit — et reste dans run.sh ; une option à une seule valeur s'écrit --option=valeur. Au-delà des 8 191 caractères que tient une commande cmd une fois développée, run.cmd ne lance rien — il écrit la longueur, la borne et l'option la plus longue, et sort en 1 — tandis que run.sh reste complet : la promotion le dit par un warning (FORGE-LAUNCHER-TOO-LONG, aussi sur stderr avec --events) et réussit.
Une fois la promotion écrite, la session suit son équipe : son dossier sous .orkeon/forge/ prend le nom du dossier de destination, tel quel — suffixé -2, -3… quand une autre session porte déjà ce nom, qui n'est jamais écrasée — et session.json comme forge.json prennent le nouveau slug : forge list montre chaque session adoptée sous le nom de l'équipe qu'elle a produite, plus sous le besoin avec lequel elle a été ouverte. --events l'annonce : session.renamed porte from, to, le nouveau dir et suffixed. Un renommage que le disque refuse (poignée ouverte sous Windows, antivirus) laisse la promotion réussie — code 0 — avec un événement warning (FORGE-SESSION-NOT-RENAMED) : l'équipe reste liée à sa session par l'identifiant, dans tous les cas. Les artefacts générés portent eux aussi le nom du dossier d'équipe, jamais celui de la session : schedule/orkeon-<équipe>.service et .timer avec leurs descriptions, la tâche planifiée Orkeon <équipe>, la commande d'installation, l'en-tête des lanceurs. <équipe> est le nom du dossier tel que l'écrit la règle des dossiers — ASCII minuscule et tirets, ce qu'un nom d'unité accepte — c'est-à-dire le nom lui-même pour tout dossier que crée un client.
La planification. Orkeon n'a pas d'ordonnanceur à lui : c'est le système qui lance une équipe planifiée, et le CLI — qui possède les artefacts — l'y installe et l'en retire. promote --schedule génère schedule/ (les trois familles, quelle que soit la machine) et note la planification déclarée dans forge.json ; il ne touche jamais au planificateur du système. forge schedule <dossier-equipe> l'enregistre pour l'utilisateur courant, sans élévation ni mot de passe :
- Windows —
schtasks /Create /TN "Orkeon <équipe>" /XML schedule/windows-task.xml /F. La tâche s'exécute tant que l'utilisateur a sa session ouverte ; une exécution manquée machine éteinte ou sur batterie a lieu dès que possible. Son action lance%SystemRoot%\System32\cmd.exe /d /v:off /s /c ""<équipe>\run.cmd"":/sretire le premier et le dernier guillemet et eux seuls, si bien que le lanceur démarre quoi que contienne son chemin —&,(,^,!,%, espaces, accents — ;/décarte les commandes AutoRun du registre,/v:offgarde un!. - Linux — les deux unités sont copiées dans
~/.config/systemd/user/($XDG_CONFIG_HOMErespecté), puissystemctl --user daemon-reloadetenable --now orkeon-<équipe>.timer.ExecStartporte le chemin du lanceur échappé pour systemd :\\et\"comme en C,%%pour un%,$$pour un$. Un timer utilisateur tourne tant que l'instance systemd de l'utilisateur tourne — de l'ouverture à la fermeture de session, ou toujours une foisloginctl enable-lingerposé. - macOS et les autres systèmes — une ligne de la crontab de l'utilisateur, marquée
# orkeon:<équipe>, lue aveccrontab -let réécrite en entier aveccrontab -: toutes les autres lignes restent exactement telles quelles, et rien n'est jamais écrit par-dessus une crontab qui n'a pas pu être lue. Le chemin du lanceur est entre apostrophes pour le shell à qui cron passe la ligne, chaque%— le séparateur de lignes de cron — écrit\%. launchd n'est pas utilisé.
Chaque commande est un programme et sa liste d'arguments, jamais un shell. Installer à nouveau réinstalle. Des artefacts qui décrivent un autre dossier — une copie, une équipe déplacée ou renommée depuis sa promotion — sont d'abord régénérés, et un enregistrement que ce dossier a fait sous un ancien nom est retiré. Ce qui a été installé est noté dans schedule/installed.json (expression, famille, noms, dossier, date), à côté des artefacts qu'il décrit — ce que le planificateur de cette machine sait de l'équipe ; forge.json ne garde que la planification déclarée. Le contrôle et le retrait agissent sur ces noms notés, jamais sur des noms qu'ils calculeraient. --check ne change rien et répond installed, absent (jamais installée, retirée hors d'Orkeon, faite sur un autre système — ou le dossier est une copie, et l'enregistrement noté est celui de l'original) ou stale, à réinstaller (elle lance un autre chemin, porte un autre nom, se déclenche sur une autre planification que celle déclarée, ou est désactivée — ou c'est une tâche Windows dont la commande est run.cmd lui-même : raison outdated). forge unschedule <dossier-equipe> retire l'enregistrement de ce dossier, schedule/ avec ce qui y est noté, et la planification que déclare forge.json ; rien à retirer est un succès, et une copie ne retire jamais l'enregistrement de son original. Un nom qu'un autre dossier d'équipe tient déjà n'est jamais remplacé (FORGE-SCHEDULE-NAME-TAKEN) ; un dossier qui ne déclare aucune planification n'a rien à installer (FORGE-SCHEDULE-NONE). Quand le système refuse — une stratégie, pas de bus de session utilisateur, pas de crontab — le verbe sort en 1 avec FORGE-SCHEDULE-REFUSED, et l'événement error porte command : ce qu'il faut lancer à la main à la place. Avec --events, l'issue est un événement schedule.state (path, state, reason, expression, family, names, et removed pour un retrait). Une ré-adoption régénère schedule/ et garde installed.json — les noms notés sont le seul chemin vers l'enregistrement — ; une ré-adoption qui abandonne la planification laisse l'enregistrement tourner et le dit par un warning (FORGE-SCHEDULE-STILL-INSTALLED) : seul unschedule le retire. Les deux verbes ne prennent aucune option hors --events (et --check pour schedule). Les lanceurs appellent orkeon par son nom, et cron comme systemd donnent à une exécution planifiée un PATH minimal : un CLI installé par dotnet tool install (sous ~/.dotnet/tools) n'y est pas trouvé, le /usr/bin/orkeon du paquet .deb l'est. La clé suit le même contrat : une exécution planifiée ne lit ni le PATH ni les export du profil du shell, si bien que la variable que le fichier de réglages nomme pour une clé (ApiKeyEnvVar, p. ex. ZAI_API_KEY — voir la configuration) va là où le planificateur lit : une ligne ZAI_API_KEY=… dans ~/.config/environment.d/*.conf pour le gestionnaire systemd de l'utilisateur, une ligne de variable en tête de la crontab pour cron — des fichiers que l'utilisateur possède et écrit lui-même ; Orkeon n'en écrit aucun. Sous Windows, la tâche tourne comme l'utilisateur, et un run lit la portée Utilisateur où un client peut mémoriser les clés, quel que soit l'environnement que construit le Planificateur de tâches. C'est ainsi qu'un client installe, contrôle et arrête la planification d'une équipe. L'enregistrement lance le lanceur par son chemin et ne lui passe rien — les arguments de la tâche à cmd.exe, l'ExecStart de l'unité, la ligne cron — : un lanceur réécrit plus tard est ce que la prochaine exécution planifiée lance, et rien n'est à réinstaller. Des artefacts dont la commande de tâche est run.cmd, ou dont l'ExecStart ou la ligne cron n'est pas échappée, sont réécrits avant une installation.
Renommer une équipe. forge rename <dossier-equipe> --name <nom> renomme une équipe promue, tout ou rien. Le dossier prend le dossier du nom, à côté de là où il est — la règle des dossiers, equipe quand il ne reste rien d'utilisable ; la session que la règle R lie au dossier le suit, comme après une promotion (suffixée -2… après le nom d'une autre session, jamais par-dessus) ; les titres suivent — session.json (et son promotedTo), forge.json, la fiche d'équipe team.json (son seul name : tous les autres champs sont gardés, connus de cette version ou non), la ligne de titre de FORGE.md, l'en-tête des lanceurs ; schedule/ est régénéré pour le nouveau chemin et le nouveau nom, et un enregistrement que le système exécute est réinstallé sous le nouveau nom, l'ancien retiré. Un nom dont le dossier est celui de l'équipe ne fait que la retitrer. Chaque étape est d'abord journalisée : quand l'une échoue — le disque refuse, le système refuse le nouvel enregistrement —, tout ce qui a été fait avant est remis en place, l'ancien enregistrement en dernier, et le verbe sort en 1 en disant que l'équipe n'a pas été renommée : FORGE-RENAME-FAILED, ou le FORGE-SCHEDULE-REFUSED du système. Un dossier déjà présent sous le nouveau nom — une autre équipe, un dossier, un fichier — est refusé avec FORGE-RENAME-TAKEN, qui dit ce qui s'y trouve ; un enregistrement qui exécute encore une équipe ne déclarant plus de planification refuse aussi le renommage (FORGE-SCHEDULE-STILL-INSTALLED : unschedule d'abord), puisqu'il resterait à lancer un dossier qui n'existe plus. Une copie est renommée sans que la session de son original soit jamais touchée, et un dossier qui ne contient aucune équipe — ni forge.json, ni team.json, ni définition d'équipe — n'est jamais déplacé (FORGE-TEAM-UNREADABLE). Avec --events : les warning, session.renamed quand le dossier de session a bougé, schedule.state quand la planification a été réinstallée, puis team.renamed (from, path, name) ; un refus est un seul error, après lequel rien n'a changé. Le verbe ne prend aucune option hors --name et --events. C'est le « Renommer » d'un client.
Codes de sortie et codes d'erreur. 0 terminé (une session mise en pause par --dry comprise), 1 une erreur d'usage ou un refus — un réglage que refuse le host du moteur compris (orkeon forge: <raison>) —, 2 une erreur inattendue, 130 Ctrl+C — la session est sauvegardée et reprenable. Un refus nomme son code sur stderr, et en mode --events dans un événement error (code, message, recoverable). En plus des codes ci-dessus, un cycle peut signaler FORGE-BRIEF-INCOMPLETE (l'entretien n'a produit aucun brief valide), FORGE-FOLDERS-INVALID (les dossiers confirmés enfreignent les règles, ou relient un dossier d'entrée que l'essai dans le processus ne pourrait pas lire — récupérable, ils sont proposés à nouveau), FORGE-BLUEPRINT-INVALID (aucun plan d'équipe valide), FORGE-TOOL-UNKNOWN (le plan nomme un outil que le catalogue du bac à sable n'offre pas), FORGE-VALIDATION-FAILED (le crew rendu échoue encore à la validation après les tentatives de réparation), FORGE-BUDGET-EXHAUSTED (une dimension du budget est épuisée — la session reste reprenable), FORGE-SESSION-CORRUPT (un fichier de session manquant ou illisible), FORGE-PROMOTE-FAILED (le dossier n'a pas pu être écrit — la session reste Ready) et FORGE-STAGE-FAILED / FORGE-ENGINE-CRASHED (une étape a échoué), FORGE-ENGINE-INCOMPLETE (une étape n'a pas de runner dans ce build) et FORGE-ENGINE-INVALID-TRANSITION (un runner a renvoyé un déclencheur que la machine refuse depuis l'étape courante) ; FORGE-MOUNT-AMBIGUOUS est un événement warning, pas une erreur (les réglages déclarent deux fois une racine virtuelle et le forge n'a pas de sélecteur, donc aucune entrée de cette racine n'est montée). Les verbes de planification ajoutent trois codes warning : FORGE-SCHEDULE-NOT-OWNED (l'enregistrement consigné appartient au dossier dont celui-ci est une copie, et n'est pas touché), FORGE-SCHEDULE-OTHER-SYSTEM (il a été fait sur un autre système d'exploitation) et FORGE-SCHEDULE-FILES-KEPT (l'enregistrement est retiré mais certains de ses fichiers n'ont pas pu être supprimés) ; forge rename un quatrième, FORGE-RENAME-SIDECAR-UNREADABLE (le team.json de l'équipe n'a pas pu être lu, donc le nom qu'il consigne est resté tel quel) ; forge promote un cinquième, FORGE-LAUNCHER-TOO-LONG (le run.cmd de l'équipe ne lance rien : sa commande dépasse les 8 191 caractères que tient une commande cmd — la promotion réussit, run.sh est complet).
orkeon usecases
orkeon usecases search "je veux un résumé de mes mails chaque matin" # les cas d'usage les plus proches
orkeon usecases search "summarize my emails every morning" --top 3
orkeon usecases list --category finance-trading --process parallel # le catalogue, filtré
orkeon usecases show 03-email-pipeline --crew # une fiche, et son fichier de crew
orkeon usecases export 01-research-assistant --to ./research --lang fr # un cas d'usage, en dossier d'équipe
Le catalogue des cas d'usage d'exemple : les 104 exemples numérotés d'examples/, chacun décrit par une fiche écrite en cinq langues (usecases.json). L'outil embarque le catalogue lui-même — le manifeste, le fichier de crew de chaque exemple et son dossier data/ — si bien que chaque sous-commande fonctionne hors ligne, ne lit rien sur le disque et n'appelle aucun LLM ; seul export écrit. Les exemples finance sont référence seule : on peut les chercher et les lire, pas les importer, car leurs crews dépendent d'un dossier _tools/ partagé que l'outil n'embarque pas.
search <texte> classe le catalogue selon un besoin écrit en langage naturel, en français, anglais, espagnol, allemand ou chinois simplifié.
- Par les termes : BM25 sur le titre et le problème de chaque fiche dans les cinq langues, ses tags, ses outils et sa catégorie. La requête et les fiches sont normalisées de la même façon — minuscules, accents repliés (
resumetrouverésumé), chinois découpé en bigrammes de caractères —, si bien qu'une requête trouve ses termes dans la langue où elle est tapée. - Par le sens : le modèle d'embeddings local (BGE-micro-v2, sur la machine) compare la requête au texte anglais de chaque fiche, et son classement est fusionné avec celui des termes par RRF. Le modèle ne lit que l'anglais (voir Limites connues) : le sens n'est donc ajouté que pour les langues où le jeu d'or (usecases.golden.yaml) a mesuré un gain — aujourd'hui l'anglais seul (mesure du 2026-09-24 sur les textes en cinq langues : les termes seuls atteignent un rappel@5 de 1,00 dans chaque langue, et le sens n'améliore le classement qu'en anglais) ; le français, l'espagnol, l'allemand et le chinois sont cherchés par les termes. Le modèle se charge à la première recherche qui en a besoin — environ une seconde —, puis chaque recherche prend quelques millisecondes.
- Sans le modèle (ses fichiers vont dans
LocalEmbeddingsModel/default/à côté du binaire ;orkeon doctorles vérifie), la recherche passe par les termes seuls et chaque réponse le dit. Elle ne se dégrade jamais en silence. Un hôte à vous compilé avecExcludeAssets="build"n'a aucun modèle local : il démarre, et son premier embedding local échoue par un message qui le dit (limites).
| Option | Description |
|---|---|
--top <n> |
Nombre de cas d'usage renvoyés (défaut 5). |
--lang fr\|en\|es\|de\|zh-Hans |
La langue de la requête (zh est accepté pour zh-Hans). Omise, elle est lue dans le texte — mots grammaticaux, lettres accentuées, caractères chinois — et des mots-clés qui ne trahissent rien comptent comme de l'anglais. Elle choisit le mode de recherche et les titres affichés. |
--events jsonl |
Répond par une ligne usecases.results sur stdout au lieu du rendu texte (jsonl est la seule valeur ; toute autre sort en 1). Sans texte, mode session : une requête par ligne de stdin, une réponse par requête, le modèle chargé une seule fois pour toutes, et la fin de stdin termine le processus avec le code 0. |
Chaque résultat porte l'id du cas d'usage, son rank, son score (BM25 par les termes, RRF en mode hybride — comparable au sein d'une même réponse seulement), la raison de la correspondance reason (terms, meaning ou terms+meaning), les termes trouvés terms, sa similarité similarity avec la requête en mode hybride, et son titre dans la langue de la requête. La réponse porte le mode employé mode (bm25 ou hybrid), la langue et la façon dont elle a été établie (langSource : option, detected ou default), et degraded, la raison, quand le sens a été abandonné.
Le mode session est ce qui permet à un client de suggérer des cas d'usage pendant la frappe : le processus s'ouvre sur une ligne usecases.ready (taille du catalogue, langues, mode de chacune), puis répond à chaque requête avec le correlationId de la requête dans l'enveloppe.
→ {"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":"…"}]}
Une requête sans top ni lang prend le --top et la --lang de la ligne de commande. Une ligne qui n'est pas une requête est ignorée. Une requête qui ne peut pas s'exécuter — pas de text, une lang hors des cinq, un top inférieur à 1 — reçoit une ligne error portant son correlationId et le code USECASES-QUERY-INVALID, et la session continue. Les types d'événement sont déclarés une seule fois, dans Orkeon.Constants.Protocol.UseCaseEventKinds.
list imprime le catalogue : id, processus, titre, et les indicateurs data (données d'exemple), web (a besoin du réseau), keys (a besoin d'une clé tierce) et reference only. Les filtres se combinent : --category (03-finance-trading, ou finance-trading), --process (sequential, hierarchical, parallel, consensual, graph, autonomous), --tag. Une catégorie ou un processus inconnu est refusé, avec la liste des valeurs valides. --lang choisit les titres (défaut en). --events jsonl émet une ligne usecases.catalog qui contient chaque fiche en entier, sous les noms de champ du manifeste.
show <id> imprime une fiche : sa catégorie, son processus, ses agents et tâches, ses outils, ses tags, ce dont elle a besoin (réseau, clés), ses montages, si elle est importable, les fichiers que l'outil embarque pour elle, et son titre et son problème dans chaque langue écrite (--lang pour une seule). --crew ajoute le fichier de crew. --events jsonl émet une ligne usecases.sheet, avec crew sur demande. Un id inconnu sort avec le code 1 et USECASES-UNKNOWN-ID (une ligne error en mode --events).
export <id> --to <dossier> écrit un cas d'usage sous la forme d'un dossier d'équipe qu'un client peut importer tel quel : crew/config.yaml — la crew de l'exemple, octet pour octet —, son dossier data/ s'il en a un, un dossier derrière chacun de ses montages (output/ pour toute crew qui écrit des fichiers), et team.json, la fiche d'équipe qui nomme l'équipe d'après le titre du cas, la décrit par son problème — tous deux dans la langue de --lang, en par défaut — et enregistre les montages du manifeste relativement au dossier (./data:/data:ro, ./output:/output:rw). Il n'y a pas de forge.json : aucune session d'atelier n'a produit l'équipe, et forge reopen en reconstruit une depuis crew/ à la première modification de l'équipe. Seuls les montages du manifeste sont enregistrés — aucun dossier d'entrée n'est inventé. --to est créé s'il n'existe pas ; un dossier qui contient quoi que ce soit, ou un fichier, est refusé avec USECASES-DESTINATION-NOT-EMPTY — un export ne fusionne jamais —, et un cas « référence seule » avec USECASES-NOT-IMPORTABLE. --events jsonl répond par une ligne usecases.exported : id, path, name, lang, files (chaque fichier écrit, en relatif) et mounts. Le dossier se lance depuis l'intérieur — orkeon run crew/config.yaml --mount ./data:/data:ro ./output:/output:rw, comme la commande l'affiche — ou depuis un client une fois importé, qui pose les montages lui-même.
Codes de sortie : 0 réponse donnée (réponse vide comprise — un --tag inconnu ne trouve simplement rien), 1 refus (id inconnu, option invalide, cas « référence seule » ou destination non vide à l'export), 2 erreur inattendue, 130 Ctrl+C. Les codes : USECASES-UNKNOWN-ID, USECASES-OPTION-INVALID (un --lang hors des cinq, un --top inférieur à 1, une recherche sans texte et sans --events, une catégorie ou un process inconnus), USECASES-NOT-IMPORTABLE, USECASES-DESTINATION-NOT-EMPTY, et en mode session USECASES-QUERY-INVALID et USECASES-SEARCH-FAILED (une requête a échoué ; la session continue) ; USECASES-FAILED est l'erreur inattendue. Un argument manquant ou une option inconnue reçoivent à la place l'aide des options, avec le code 1 et sans code d'erreur.
orkeon init
Assistant de configuration. Génère un appsettings.json valide au chemin global par utilisateur (%APPDATA%\Orkeon\appsettings.json sous Windows, $XDG_CONFIG_HOME/Orkeon/appsettings.json — sinon ~/.config/Orkeon/appsettings.json — sous Linux et macOS, qui n'utilise volontairement pas ~/Library/Application Support) via un assistant interactif à 5 choix — ollama, docker-model-runner, openai, custom, none — ou en mode non interactif par flags, puis sonde l'endpoint (sauf --no-probe).
| Option | Description |
|---|---|
-p, --provider <preset> |
ollama | docker-model-runner | openai | custom | none (insensible à la casse). Sans elle, l'assistant pose la question — et une entrée standard non interactive est refusée avec le code 1. |
-u, --base-url <url> / -m, --model <id> |
Endpoint et modèle. Requis pour custom ; les presets ont leurs défauts (ci-dessous). |
-k, --api-key-env <nom> / --api-key <valeur> |
La variable qui contient la clé d'API — écrite dans le fichier en Llm:ApiKeyEnvVar, que chaque run lit, sauf si c'est ORKEON_Llm__ApiKey (le défaut), que le runtime lit nativement ; la sonde de init lit la clé comme un run (ci-dessous) — ou une clé stockée en clair dans le fichier (déconseillé). Voir la variable par fournisseur. |
--path <fichier> |
Écrire ailleurs qu'au chemin global par utilisateur. Un dossier reçoit un appsettings.json. |
-f, --force |
Écraser un fichier existant. |
--no-probe |
Sauter la sonde de l'endpoint. |
| Preset | URL de base | Modèle | Clé d'API |
|---|---|---|---|
ollama |
http://localhost:11434 |
llama3.2 |
aucune — --api-key et -k sont ignorés |
docker-model-runner |
http://localhost:12434/engines/llama.cpp/v1 |
ai/granite-4.0-h-tiny |
la valeur de remplissage not-needed, écrite en clair (--api-key la remplace) |
openai |
https://api.openai.com/v1 |
gpt-5.6-sol |
lue dans ORKEON_Llm__ApiKey, ou dans la variable que nomme -k (Llm:ApiKeyEnvVar), jamais écrite — sauf --api-key |
custom |
requise | requis | comme openai |
none |
— | — | — |
Le fichier ne contient qu'une section Llm (Model, BaseUrl, puis ApiKeyEnvVar quand -k nomme une autre variable que ORKEON_Llm__ApiKey, ou ApiKey quand une clé est écrite en clair) ; none n'écrit aucune section Llm, seulement un _comment qui dit que les runs se replient sur le fournisseur écho <undefined-llm>. La sonde lit le fichier qu'elle vient d'écrire comme un run le lit — les variables d'environnement sans préfixe, le fichier, puis celles en ORKEON_, la composition d'orkeon doctor — et présente la clé qu'un run présenterait : celle que la configuration résout (ORKEON_Llm__ApiKey l'emporte sur l'ApiKey du fichier), sinon la variable que nomme Llm:ApiKeyEnvVar, dans l'environnement du processus puis, sous Windows, dans celui de l'utilisateur, où un client peut mémoriser une clé. Elle dit d'où vient cette clé — Probing <endpoint> — API key from the variable named by Llm:ApiKeyEnvVar (user environment) —, jamais la clé, et une référence vers une variable posée nulle part est signalée d'abord, dans les mots des runners. Elle liste ensuite les modèles de l'endpoint (le catalogue d'Ollama pour ollama, celui d'OpenAI sinon) avec un délai de 5 secondes ; une sonde en échec est un avertissement — le fichier est écrit quand même, et le code de sortie reste 0. Une section Llm sur laquelle un run refuserait de démarrer — une référence qui n'est pas un nom de variable, une ApiKey écrite ${NOM}, une BaseUrl qui n'est pas une adresse — fait échouer la sonde avec le message du lecteur et le code 1 : le fichier est écrit, et un run le refuse tant qu'il n'est pas corrigé. Codes de sortie : 0 écrit, 1 une option erronée, un fichier déjà présent sans --force, un assistant interrompu, une section écrite qu'un run refuse, 2 une erreur inattendue, 130 Ctrl+C.
init lit l'adresse comme un run. Une adresse lue comme Ollama (port 11434) n'accepte que les préréglages ollama et custom. Deux règles : une adresse que la lecture refuse est écrite, puis refusée par la sonde ; un préréglage que la lecture contredit est refusé avant que rien soit écrit, avec le préréglage à utiliser à la place (code 1). Une adresse sans chemin est écrite quand même, avec l'avertissement d'adresse muette sur stderr et le code de sortie 0. La sonde liste le catalogue que la lecture désigne (celui d'Ollama pour une adresse Ollama, celui d'OpenAI sinon).
orkeon init --provider ollama --model llama3.2 --no-probe
orkeon init n'écrit que le fichier de settings. Pour démarrer un projet — un hôte, un plugin ou un outil — utilisez les modèles dotnet new du paquet Orkeon.Templates : Partir d'un modèle.
orkeon llm
Deux verbes contre un endpoint fournisseur réel.
orkeon llm probe — déroule le protocole de test LLM contre un fournisseur et archive éventuellement la trace de campagne. Options clés : -p, --provider (requis : openai | anthropic | ollama | azure | together | qwen | deepseek | kimi | mistral | huggingface | zai | gemini | grok | minimax | openrouter | mammouth, ou un fournisseur de décision typesafe | liquid | kev), -m, --model, -u, --base-url (requis pour Azure), --api-version (mode déploiement Azure), --workspace-id (clés à portée de workspace — les clés identity-linked d'Anthropic l'exigent), -k, --api-key-env (défaut ORKEON_LLM_API_KEY — la clé elle-même n'est jamais acceptée sur la ligne de commande), --modes (séparés par des virgules, ex. M1,M2,M8, D1–D8 pour un fournisseur de décision ; défaut : tous les modes de la famille du fournisseur, sauf D8 et ses 100k jetons d'entrée), --archive <rép> (où le rapport de campagne est écrit ; rien n'est archivé sans elle), --format md|json (défaut md), --commit <sha> (le commit court de l'arbre testé, consigné dans le rapport), --timeout (secondes par requête, défaut 180), --temperature (défaut 0), --thinking-effort (effort de raisonnement de base, ex. none — certains modèles refusent les function tools en raisonnant), --m7-effort (effort utilisé par la sonde thinking M7, défaut low — pour les modèles dont l'ensemble supporté l'exclut), --sweep-efforts (valeurs d'effort séparées par des virgules que le balayage M16 essaie, défaut low,medium,high,xhigh,max, puis chaque valeur d'un fragment effort:* de --raw-reasoning ; accepte des valeurs propres à un fournisseur comme none ou minimal). M15 (interrupteur thinking : activé puis désactivé), M16 (balayage d'effort) et M17 (budget de 1024 jetons) font partie du jeu par défaut ; chacun indique, pour chaque étape, si le champ de raisonnement est réellement parti sur le fil (sent, lowered, omitted, rejected) dans un tableau reasoning du rapport JSON et un tableau Reasoning du rapport Markdown. --raw-reasoning <fichier> alimente M18, la matrice de raisonnement brute : le fichier est un tableau JSON [{"label":"effort:xhigh","body":{"reasoning_effort":"xhigh"}}, ...] et, pour chaque élément, le fournisseur construit toujours la requête (authentification, URL, en-têtes, dialecte) mais ses champs de raisonnement sont remplacés par body juste avant l'envoi : c'est l'acceptation du fournisseur de modèle qui est mesurée, pas le jugement de capacités d'Orkeon. Chaque étape est accepted ou refused (avec l'erreur du fournisseur) ; le mode réussit si au moins une étape est acceptée, et n'est pas applicable sans l'option.
orkeon llm models — liste les modèles servis par un fournisseur. Options : -p, --provider (requis), -u, --base-url, -k, --api-key-env, -f, --filter (glob shell), --json.
ORKEON_LLM_API_KEY=... orkeon llm probe -p deepseek --modes M1,M2 --format json
orkeon llm models -p ollama --filter 'llama*'
orkeon rag
Deux verbes sur le sous-système RAG (ingest, search) ; son évaluation est orkeon eval rag. Tous partagent les options d'hôte de run : -s/--settings, -m/--mount, --allow-external-mounts, -v/--verbose <0-2> (défaut 0). Les sources relatives se résolvent contre un montage automatique {cwd} → /workspace:ro ; l'état atterrit dans {cwd}/.orkeon → /output:rw.
orkeon rag ingest — ingestion incrémentale (les sources inchangées sont sautées) : -c, --collection (requis), --source <chemin|glob|url> (requis ; plusieurs sources séparées par des espaces derrière un seul flag, globs résolus via le système de fichiers virtuel, une adresse http(s):// passée telle quelle au chargeur web — son ? ou son * ne sont pas un motif), --chunking recursive|sentence|structural|semantic (le défaut du pipeline s'il est omis), --reindex (réindexation complète — seule issue après un changement de modèle/dimension d'embedding).
orkeon rag search — pose une question, imprime la réponse fondée avec citations et scores : <question> positionnelle, -c, --collection (requis), --top-n (défaut 5).
Le modèle d'embeddings. orkeon rag n'utilise aucune empreinte d'hôte (son Orkeon:Embeddings:FingerprintPath par défaut est vide). Le manifeste de chaque collection consigne le provider, le modèle et les dimensions avec lesquels elle a été indexée et refuse un changement : ingest sans --reindex, tout search, orkeon eval rag --no-ingest -c et orkeon eval rag -c avec son pré-passage d'ingestion et sans --reindex sortent en 1 avec une ligne qui nomme la collection, les deux modèles et orkeon rag ingest --reindex. --reindex reconstruit la collection et passe. eval rag sans -c n'a pas de contrôle propre : le harnais résout la collection.
orkeon eval
Le cadre d'évaluation en commande : quatre verbes. Les verbes de notation partagent les options d'hôte de run (-s/--settings, -m/--mount, --allow-external-mounts, -v/--verbose <0-2>), lisent la section Evaluation des réglages et lisent le jeu de données par le système de fichiers virtuel (un chemin relatif se résout contre le montage automatique {cwd} -> /workspace:ro). Une seule suite, Default ; --evaluators en choisit des évaluateurs par nom, il n'y a pas de --suite.
orkeon eval run — note un jeu de données JSON (un tableau de cas : task_description, expected_output, output, context, expected_format, metadata) et écrit <output>/<jeu>-eval.json : l'EvaluationReport (snake_case) plus un tableau cases avec la sortie qui a été notée. -d, --dataset (requis), --evaluators format,schema,text-quality,similarity,tool-accuracy (défaut : tous les évaluateurs enregistrés ; coherence,fluency,groundedness aussi avec --llm-judge ; un nom inconnu est refusé, sortie 1), --llm-judge (fixe Evaluation:EnableLlmJudge pour le run ; demande un LLM), --offline (zéro réseau : les juges restent éteints, refusé avec --llm-judge, et une --crew est refusée, sortie 1, quand un de ses agents ou son manager répondrait par un fournisseur autre que le mock - l'agent et son profil sont nommés), --output (défaut /output/eval, soit ./.orkeon/eval), --min-score <0-1> (sortie 1 quand le score global est dessous). Sans --crew, chaque cas a besoin de son output. Avec --crew <fichier> (une crew YAML, un .ork.ts ou un dossier de crew, chargée avec les garde-fous d'orkeon run), la crew tourne une fois par cas avant la notation : la task_description du cas est son prompt (le contexte initial et la variable {input}), sa sortie finale remplace output dans le rapport, et le fichier du jeu de données n'est jamais modifié ; un seul hôte sert tous les cas, donc la mémoire que la crew garde passe d'un cas au suivant (les cas ne sont pas isolés les uns des autres : ordonnez-les, ou donnez à chaque cas une crew sans mémoire, si cela compte) ; --llm-mock <fichier>, --llm-record <fichier>, --llm-replay <fichier> et --llm-profile <id> sont ceux d'orkeon run (un rejeu compte comme hors ligne : --offline --llm-replay tourne sur n'importe quel profil). Une crew qui échoue sur un cas sort en 2, arrête le run et n'écrit aucun rapport : un rapport d'une partie du jeu de données se lirait comme le tout. Chaque chaîne du rapport - les sorties produites, le raisonnement des scores - passe par la rédaction de l'historique des runs (une valeur qui a la forme d'un secret devient ***REDACTED***). Un rapport qui existe déjà est écrasé, et la commande le dit.
orkeon eval bench — note les sorties enregistrées du jeu de données --runs N fois par cas (défaut 3) et écrit <jeu>-bench.json et -bench.md (moyenne et écart-type par évaluateur). --baseline <rapport> compare le run à un rapport écrit par eval bench ou eval run et sort en 1 sur une régression (--threshold, un nombre de 0 à 1, défaut 0,05). La référence est lue avant que le run n'écrive quoi que ce soit ; une référence qui est le rapport que le run écrit (.orkeon/eval/<jeu>-bench.json avec l'--output par défaut) est refusée, sortie 1 : gardez la référence ailleurs, sous contrôle de version par exemple. Une référence d'un autre jeu de données, ou notée par d'autres évaluateurs, est refusée aussi, avant l'écriture de tout rapport. --dataset, --evaluators, --llm-judge, --offline, --output et --min-score sont ceux d'eval run. Il n'accepte pas --crew.
orkeon eval compare <baseline> <current> — compare deux rapports écrits par eval run ou eval bench, imprime la comparaison en markdown (--json pour du JSON) et sort en 1 sur une régression (--threshold, un nombre de 0 à 1, défaut 0,05). Les deux rapports doivent être des fichiers distincts du même jeu de données (le nom qu'eval run et eval bench enregistrent) notés par les mêmes évaluateurs : sinon la comparaison est refusée, sortie 1, car un évaluateur noté d'un seul côté n'a rien à quoi se comparer.
orkeon eval rag — évalue une collection contre un jeu de données de référence (recall@k, MRR, groundedness) et écrit des rapports markdown/JSON ; le dossier corpus du jeu de données est d'abord ingéré, de façon incrémentale : -d, --dataset (requis), -c, --collection (défaut : la collection du jeu de données, sinon rag-eval-<nom du jeu>), --profile fast|balanced|quality|adaptive|corrective|default (défaut default = le Orkeon:Rag:Profile configuré) ou --compare fast,balanced,…, -k (défaut 5), --llm-judge, --offline (zéro réseau : stub extractif déterministe, aucune clé LLM nécessaire — il répond à la place de tout modèle, Orkeon:Rag:LlmProfile compris), --no-ingest, --reindex, --min-recall / --min-mrr (portes anti-régression, sortie 1 sous le seuil), --output (défaut /output/rag/eval, soit ./.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 # une fois, depuis un run 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 <fichier>] [--json] # les comptes déclarés, leurs droits, si chacun est prêt
orkeon email login <compte> [--settings <fichier>] [--events jsonl] # connecter un compte OAuth2 et enregistrer ses jetons
orkeon email logout <compte> [--settings <fichier>] # oublier les jetons enregistrés d'un compte OAuth
orkeon email check <compte> [--settings <fichier>] [--events jsonl] # se connecter, s'authentifier, lister les dossiers
Le côté opérateur des outils e-mail (guide) : ce qui est déclaré sous
Orkeon:Tools:Email, la seule étape interactive qu'exige un compte OAuth2, et une vérification
de connexion. Les agents ne les lancent jamais — un outil qui ne trouve aucun jeton utilisable
répond « run orkeon email login <account> ».
accountsliste chaque compte déclaré — son préréglage, comment il lit et envoie, comment il se connecte, ses droits, s'il est le compte par défaut — et ditready, ou ce qu'il faut corriger : une déclaration invalide, une variable de mot de passe ou de secret client non définie, une connexion encore à faire. La commande n'ouvre aucune connexion et n'affiche aucun secret ;--jsonécrit la même liste en JSON, sous les noms qu'utiliseemail_accounts(name,address,provider,reads,sends,rights,auth,default,ready,problem), plusconfiguration_problems(une liste, vide quand le compte se résout),credential_problemet les valeurs auxquelles se résout un champ laissé vide :incoming_host,incoming_port,incoming_security,outgoing_host,outgoing_port,outgoing_security,username,save_sent_copy,token_endpoint. La liste en texte montre les serveurs, l'identifiant de connexion et le point de terminaison des jetons d'un compte résolu sur une ligne (guide e-mail).loginconnecte un compte OAuth2. Un compte Microsoft passe par le flux par code d'appareil : la commande affiche l'adresse de vérification que renvoie Microsoft et un code, et attend pendant que vous vous connectez depuis n'importe quel navigateur. Un compte Google passe par le code d'autorisation avec PKCE : la commande affiche l'adresse d'autorisation de Google et écoute sur un port libre de127.0.0.1; quand le navigateur ne peut pas atteindre cette machine (WSL, un conteneur, une session SSH), collez dans le terminal l'adresse où le navigateur aboutit. Une ligne collée qui n'est pas cette adresse — tronquée, l'adresse à ouvrir, du texte — reçoit une phrase qui dit pourquoi, sans la répéter, et la commande continue d'attendre ; une ligne vide est ignorée. Les jetons vont dans la racine interne/credentialsdu runner (où vivent les jetons). Un compte à mot de passe n'a rien à connecter et est refusé. Avec--events jsonl, c'est un programme qui pilote la connexion au lieu d'une personne qui la lit — c'est ainsi qu'un client la lance. La sortie standard porte alors un événement JSON par ligne et rien d'autre, dans l'enveloppe du flux d'événements du run, sous les types déclarés une seule fois dansOrkeon.Constants.Protocol.EmailEventKinds:email.login.device_code(verification_uri,user_code,expires_inen secondes),email.login.authorization_url(authorization_uri),email.login.redirect_rejected(message),email.login.completed(account), eterror(code— le code d'erreur e-mail, par exempleCredentialMissingouLoginRequired—,message,recoverable), qui remplace la ligne sur stderr ; le code de sortie est celui que le verbe a sans l'option. L'entrée standard est la prise du pilote sur le verbe : une ligne qu'il y écrit est l'adresse où le navigateur a abouti — une ligne qui ne l'est pas reçoitemail.login.redirect_rejected, dont lemessagedit pourquoi sans répéter la ligne, et le verbe continue d'attendre : une ligne rejetée ne termine rien et ne change aucun code de sortie —, et la fermer abandonne la connexion avec le code de sortie130— le flux Google attend sans échéance, donc un pilote qui s'en va ne laisse jamais le verbe à l'écoute sur son port. Sans l'option, le verbe imprime pour une personne : l'adresse, le code, l'issue.logoutsupprime les jetons enregistrés d'un compte OAuth, et le dit quand il n'y en avait pas ; un compte à mot de passe n'en a pas et est refusé.checkse connecte, s'authentifie et liste les dossiers, puis affiche leur nombre et les compteurs de la boîte de réception. Avec--events jsonl, le verdict est un événement sur une ligne de la sortie standard :email.check.completed(account,folders,inbox_total,inbox_unread, etsummary, la phrase imprimée sans l'option), ouerroravec soncode— c'est ainsi qu'un client sait qu'un test refusé attend une connexion ou un mot de passe, et désigne son propre bouton ou champ plutôt qu'un terminal. Le code de sortie est celui que le verbe a sans l'option.
-s, --settings <chemin> se résout comme pour orkeon run, ancré sur le répertoire courant :
le fichier explicite, sinon appsettings.json dans le répertoire courant, sinon un
appsettings/appsettings.json trouvé en remontant, sinon le fichier utilisateur d'orkeon init,
sinon les seules variables d'environnement ORKEON_* — ce que laisse aussi un chemin explicite
qui n'existe pas, avec un avertissement. Le fichier retenu est nommé sur stderr
(Using settings: …).
Codes de sortie : 0 succès, 1 usage, configuration ou refus (un compte inconnu, une variable
non définie, une connexion à faire — fournisseur qui n'a délivré aucun jeton de rafraîchissement
compris —, un droit ou une capacité manquants), 2 ce qu'ont fait le réseau ou le serveur (un
échec de connexion, des identifiants ou une autorisation refusés par le fournisseur) ou une
erreur inattendue (ORKEON_DEBUG=1 en imprime la trace de pile), 130 Ctrl+C. Le verbe est reconnu avant la détection d'un chemin de crew, comme tous les verbes : un
dossier de crew nommé email se lance avec 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
Le côté opérateur des outils drive (guide) : ce qui est déclaré sous
Orkeon:Tools:Drive, la seule étape interactive dont chaque compte a besoin, et une vérification
de connexion. Les agents ne lancent jamais ces commandes — un outil qui ne trouve aucun jeton
utilisable répond « run orkeon drive login <account> ».
accountsliste chaque compte déclaré — son fournisseur, son dossier racine et ses droits, s'il est le compte par défaut — et ditready, ou ce qu'il faut corriger : une déclaration invalide, une variable de secret client non définie, une connexion encore à faire. Aucun accès réseau.--jsonécrit un objet par compte (name,provider,rights,root,default,ready,problem,configuration_problems,credential_problem,token_endpoint) (guide drive).loginlance la connexion OAuth : le code d'appareil de Microsoft pour OneDrive, la page de consentement de Google avec une redirection de bouclage (ou l'adresse collée où elle aboutit) pour Google Drive. Les jetons arrivent dans le sous-répertoiredrivedu répertoire d'identifiants, où chaque run les cherche. Avec--events jsonl, un programme pilote la connexion — c'est ainsi qu'un client la lance —, sur le protocole d'orkeon email loginsous les types deOrkeon.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), eterror(code,message,recoverable). Une ligne sur l'entrée standard est l'adresse où le navigateur a abouti ; fermer l'entrée standard abandonne la connexion avec le code de sortie130.checktrouve le dossier racine du compte et liste sa première page :Drive account 'pro' is reachable: root folder /Orkeon ('Orkeon') holds 3 item(s).Avec--events jsonl, le verdict est une seule ligne d'événement :drive.check.completed(account,root_path,root_name,items,more, etsummary, la phrase affichée sans l'option), ouerroravec soncode(LoginRequired,CredentialMissing, …). Le code de sortie est celui du verbe sans l'option.- Codes de sortie : 0 fait ; 1 ce que l'opérateur corrige (configuration, compte inconnu, variable manquante, connexion à faire, un droit ou une capacité manquants) ; 2 ce qu'ont fait le fournisseur ou le réseau ; 130 Ctrl+C.
orkeon typings
orkeon typings # écrit orkeon.d.ts et orkeon-cli.d.ts dans ./.orkeon/
orkeon typings --out crews/.orkeon
Écrit les typings TypeScript que porte ce build de l'outil, pour votre éditeur : orkeon.d.ts (le DSL de scripting .ork.ts) et orkeon-cli.d.ts (les commandes *.cmd.ts du REPL). Les deux sont embarqués dans l'outil : un dotnet tool install suffit — ni clone, ni build. -o/--out <dossier> (ou --out=<dossier>) choisit le dossier (./.orkeon par défaut, créé s'il manque) ; les fichiers existants sont écrasés, relancez donc la commande après une mise à jour de l'outil. Un script commence alors par /// <reference path="./.orkeon/orkeon.d.ts" />, chemin relatif au script. Hors ligne. Codes de sortie : 0 écrit, 1 un argument inconnu ou --out sans dossier (--out= compris).
Les deux mêmes fichiers sont joints à chaque Release GitHub sous le nom orkeon-typings-<version>.tar.gz (un dossier de ce nom contenant orkeon.d.ts et orkeon-cli.d.ts), produits par cette commande à partir du build de la release, listés dans SHA256SUMS et attestés. Un projet qui fige les typings d'une release, ou en compare deux, télécharge cette archive plutôt que d'exécuter l'outil installé : voir Réglage de l'éditeur.
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>]
Relit les runs que l'historique de run a enregistrés (Orkeon:RunHistory:Enabled ; le gabarit de orkeon init et orkeon-host l'activent). list écrit un résumé JSON par run, le plus récent d'abord (run_id, crew_key, status running, succeeded, failed ou orphaned, started_at, finished_at, error, et les pid, host et process_started_at du processus qui l'a mené), --crew garde un équipage et --limit (50 par défaut) borne la liste. show écrit tous les événements d'un run, de run.started à run.finished, et tail écrit à partir de --from <seq> (--follow attend un run encore en cours et s'arrête à sa fin). Les deux écrivent les lignes mêmes qu'orkeon run --events jsonl a écrites : un seul lecteur sert le flux et l'historique. L'historique est lu d'après les réglages du dossier courant (-s, --settings <chemin> nomme le fichier) et le dossier ./.orkeon/runs ; lire ne le modifie jamais (la purge revient au côté qui écrit). Un run noté running dont le processus n'existe plus sur le même hôte a été tué : il est rapporté orphaned, compte comme terminé pour la purge et pour MaxRuns, et met fin à tail --follow. Un run noté sur un autre hôte reste running : seul son hôte peut le dire. Ce qu'il contient : tous les événements du run sauf llm.delta (sans IncludeDeltas) — résultats de tâche, noms d'outils et noms de leurs arguments, tailles d'appels de modèle, messages d'erreur — et, avec chaque run, le pid et le nom d'hôte. Les secrets sont masqués avant l'écriture, avec le masquage des logs (les clés des fournisseurs dont Orkeon livre un client, les jetons bearer, les paires password=, token=, api_key=, et la valeur de toute propriété nommée comme un identifiant) ; le flux --events sur stdout n'est pas masqué. orkeon init ajoute .orkeon/ au .gitignore du dossier courant, car ce dossier garde ce que les runs ont dit et fait. Hors ligne. Codes de sortie : 0 écrit, 1 une sous-commande inconnue, un argument mal formé, un run absent de l'historique ou l'historique non activé, 130 interrompu.
orkeon mcp
orkeon mcp serve [--settings <fichier>] [--tools a,b,…] [--max-concurrency <n>] [--expose-output] [--crew <a.yaml> [<b.yaml> …]] [--allow-external-mounts]
orkeon mcp serve sert les outils d'un hôte Orkeon à un client MCP sur stdio — comme Claude Desktop ou un éditeur démarre un serveur MCP local : le client lance la commande, écrit des messages JSON-RPC sur son stdin, un par ligne, et lit les réponses sur son stdout ; fermer stdin arrête le serveur. L'hôte est celui que construit orkeon run — les réglages, résolus comme ceux d'orkeon run depuis le répertoire courant (-s, --settings <chemin> nomme le fichier), leurs montages, les outils intégrés et les serveurs MCP qu'ils déclarent —, et ce qui est servi est ce qu'imprime orkeon run --list-tools pour les mêmes réglages, human_input à part. --crew <a.yaml> [<b.yaml> …] sert chaque crew comme l'outil run_crew_<nom> (son entrée les {placeholders} de ses tâches, son résultat la sortie finale, une notifications/progress par tâche quand le client envoie un progressToken) et ses tâches comme prompts, sous le budget, le gardien et la barrière de permissions d'orkeon run — plusieurs crews se suivent, séparées par des espaces, après un seul drapeau, une crew hors du répertoire courant demande --allow-external-mounts, et seules les crews nommées sont servies ; --tools a,b,… ne sert que les outils nommés ; un nom que l'hôte n'a pas refuse le démarrage. --max-concurrency <n> (au moins 1, 4 par défaut) borne le nombre de requêtes qui s'exécutent à la fois, les autres attendent leur tour ; notifications/cancelled annule la requête qu'elle nomme. --expose-output sert /output comme ressources MCP en lecture seule (orkeon:///output/<chemin>, par le système de fichiers virtuel ; /workspace n'est jamais servi). Chaque tools/call franchit le point d'invocation des appels d'un agent de crew — garde, troncature, assainisseur de résultat, audit — sous l'appelant mcp. Stdout ne porte que le protocole : journaux, avertissements, --help et erreurs d'usage vont sur stderr. Codes de sortie : 0 le client a fermé le flux (ou --help, ou Ctrl+C ou SIGTERM), 1 une erreur d'usage, un réglage refusé, un nom de --tools que l'hôte n'a pas, un --crew refusé au démarrage (une crew qui ne se charge pas, un nom donné deux fois, un nom run_crew_* déjà tenu par un outil), ou un serveur lancé par un autre orkeon mcp serve, 2 une erreur inattendue. Un serveur pose ORKEON_MCP_SERVE dans son environnement avant de connecter les serveurs MCP de ses réglages — chaque processus qu'il lance en hérite — et un serveur qui trouve la variable posée refuse de démarrer, avec une ligne sur stderr : des réglages qui déclarent orkeon mcp serve sous leurs propres MCP:Servers feraient démarrer à chaque serveur un autre serveur avant de répondre. Une configuration client et le détail : Intégration MCP.
orkeon doctor
Diagnostic d'installation : dit en moins de 15 secondes ce qui fonctionne et ce qui manque, en table ✅/⚠️/❌ ou en --json (schéma stable {check, status, detail} pour la CI). Les vérifications, dans cet ordre : dotnet-runtime, install-channel, appsettings, llm-config, llm-profiles, runner-settings, llm-reachability, esbuild, tsc, local-embeddings, onnx-reranker, tree-sitter, workspace-write — plus, après llm-profiles, une ligne llm-profile-key (warn) par profil dont l'ApiKeyEnvVar nomme une variable posée nulle part ; chaque status vaut ok, warn ou fail. install-channel nomme le canal par lequel ce build a été installé, la version qui tourne et la commande qui met ce canal à jour (zip — orkeon <version>; to update: extract the new orkeon-cli-<version>-win-x64.zip and run its install.cmd). Le canal vaut zip, msi, msi-host, tarball, deb, homebrew, source ou dotnet-tool : il est lu dans le fichier INSTALL-CHANNEL que chaque emballage écrit à la racine de ce qu'il installe, jamais deviné — sauf l'outil dotnet, qui ne porte pas ce fichier et se reconnaît à son chemin. Un paquet Debian répond deb qu'apt l'ait pris au dépôt ou qu'il ait été téléchargé : rien en lui ne distingue les deux, et la vérification donne les deux commandes. Une installation antérieure au marqueur, ou un build lancé depuis son arbre, répond unknown et reste ok ; seul un marqueur présent qui ne nomme aucun canal est un warn. La vérification n'échoue jamais. Une commande scriptée lit la même version et le même canal par ctx.services.get("runtime") (commandes scriptées). runner-settings juge le fichier comme orkeon run le juge à son démarrage, par la même construction : les gardes qu'un run applique aux montages que déclare le fichier (une racine qu'orkeon run garde pour lui, des entrées d'une même racine distinguées par leurs ids, des dossiers qui existent), puis l'hôte que construit orkeon run — sans équipe, sans montage de ligne de commande, sans connexion MCP, le reranker ONNX qu'ajoute le CLI compris — et sa validation de démarrage. Une ligne fail par refus, chacune nommant sa clé, toutes ensemble ; une ligne ok sinon (the settings pass the start validation of orkeon run) — et une ligne warn par section que le fichier écrit et qu'aucun binaire livré ne lit, dans les mots que le run écrit sur stderr (quand un réglage est seulement signalé) ; avec une telle ligne et sans refus il n'y a pas de ligne ok, et le code de sortie reste 0 ; un refus levé par la construction elle-même — un fichier illisible, un niveau de journal — est la seule ligne, comme le run le rapporte. Elle dit skipped (the Llm section is refused — see llm-config) quand llm-config ou llm-profiles a déjà échoué. Elle laisse le répertoire courant tel qu'il était : son hôte crée son dossier de bac à sable sous le répertoire temporaire et le supprime — et, quand un compte e-mail se connecte en OAuth, le dossier des jetons qu'un run crée. Un fichier qu'un run refuse fait sortir doctor en 1. llm-config se termine par l'origine de la clé du défaut (API key from the variable named by Llm:ApiKeyEnvVar (user environment) — jamais la clé ni le nom de la variable), avertit quand cette référence ne résout rien, et échoue quand la section ne se lit pas — une ApiKey écrite ${NOM}, une référence qui n'est pas un nom de variable, une BaseUrl invalide —, comme un runner refuserait de démarrer ; llm-profiles liste chaque profil avec l'origine de sa clé ; llm-reachability interroge le catalogue avec la clé qu'un run utiliserait. --json est la seule option : les settings sont lus comme un run les lit — le fichier que trouve la chaîne d'orkeon run, ancrée au répertoire courant, entre les variables d'environnement sans préfixe, dessous, et celles en ORKEON_*, dessus ; rien d'autre — c'est aussi là que la vérification esbuild lit Orkeon:Scripting:Toolchain:EsbuildPath. L'outil dotnet ne livre pas esbuild : un ⚠️ sur cette vérification dit comment l'obtenir (npm install -g esbuild, ORKEON_ESBUILD_PATH ou EsbuildPath), et ses deux détails nomment orkeon typings pour les typings d'éditeur. La vérification tsc suit le mode de vérification de types (Orkeon:Scripting:Toolchain:TypeCheck) : un tsc introuvable est ok sous Off et Validate, son détail disant qu'il est optionnel, et fail sous Always ; un TscPath configuré qui n'existe pas est ok sous Off (inutilisé tant que la vérification de types est coupée), warn sous Validate et fail sous Always ; un tsc qui ne répond pas à --version est ok sous Off et warn sous Validate et Always. Sous Always, le détail donne la raison, puis le remède installé (npm install -g typescript, Orkeon:Scripting:Toolchain:TscPath, TypeCheck: off), et l'amorçage de checkout seulement quand orkeon tourne depuis un checkout. Un fail fait sortir orkeon doctor en 1. Codes de sortie : 0 tout vert ou avertissements seuls, 1 au moins une vérification en échec (ou une option invalide), 2 une erreur inattendue, 130 Ctrl+C.
doctor nomme le fournisseur que construit le run depuis la section Llm — OpenAI-compatible (custom) pour une adresse lue comme un serveur générique, Docker Model Runner pour celui-là — et signale une adresse sans chemin (qui ne dit rien de son fournisseur) par un warn : sur llm-config pour le défaut, et une ligne llm-profiles par profil.
orkeon doctor --json
orkeon settings
orkeon settings # les onze catégories, et les sections de chacune
orkeon settings rate-and-budgets # une catégorie : ses sections, et qui lit chacune
orkeon settings RateLimiting # une section : chaque clé, son type, son défaut, son sens
orkeon settings RateLimiting:QueueLimit # une clé
orkeon settings rate # un mot : ce qu'il nomme ou décrit
orkeon settings env # les variables d'environnement que lit Orkeon
orkeon settings --all # chaque section et chaque clé, par catégorie
orkeon settings --json # le même inventaire, pour un programme
orkeon settings --host host # seulement ce que lit orkeon-host
Liste dans le terminal, hors ligne, les réglages qu'un hôte lit — ce qu'un fichier de réglages peut contenir : l'inventaire de la référence de configuration, donné par l'outil lui-même. Il répond depuis le catalogue que l'outil embarque, produit à partir du code qui lit les réglages : il n'ouvre aucun fichier de réglages, ne construit aucun hôte et ne touche pas au réseau. Il répond donc pareil dans un dossier dont un run refuse l'appsettings.json, il fonctionne dans un dossier où il ne peut pas écrire, et il n'écrit rien. Ce qu'il montre est ce que vaut une clé quand rien ne la règle, pas ce que cette machine a réglé : orkeon doctor reste le verbe qui juge un fichier. Une clé qui porte un secret est marquée secret et n'a pas de défaut — aucune sortie du verbe ne contient la valeur d'une clé.
$ 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.
La sortie est en anglais, comme le reste du CLI.
Ce qu'un nom désigne, essayé dans cet ordre, quelle que soit sa casse :
- une catégorie, par son identifiant ou son titre —
models,rate-and-budgets,memory-and-vectors,rag,files-and-sandbox,security,tools,orchestration-and-persistence,scripts-and-console,service-host-and-a2a,observability: ses sections, chacune avec son nombre de clés, qui la lit et la première phrase de ce qu'elle configure ; - une section, par son chemin (
RateLimiting,Orkeon:Rag:WebFallback) : qui la lit, ce qu'elle configure, puis chaque clé — chemin, type, défaut, les valeurs qu'une liste fermée accepte, et son sens ; - une clé, par son chemin. Un nom ou un indice à vous tient la place de ce que le catalogue écrit
<name>ou<i>:orkeon settings Llm:Profiles:fast:ModeltrouveLlm:Profiles:<name>:Model(écrit avec les chevrons, le chemin demande des guillemets dans un shell) ; - un mot : ce qu'il nomme, puis ce qu'il ne fait que décrire — les sections avec qui les lit, les clés sur une ligne chacune. Le mot est cherché là où un mot commence, dans les chemins et dans les descriptions :
ratetrouveRateLimitingetToolRateLimiting, pasFallbackStrategy.
Un nom qui ne désigne rien sort en 1 et nomme le plus proche qui existe. La liste ne dépasse jamais 100 colonnes.
Qui lit une section est dit pour chacune : Read by: orkeon, orkeon-host, orkeon-repl, ou Read by: a C# host only — AddOrkeonToolRateLimiting() pour une section qu'aucun binaire livré ne lit — écrite dans le fichier de réglages d'orkeon run, une telle section est sans effet ; la liste des catégories la marque d'un *.
| Option | Description |
|---|---|
--all |
Chaque section et chaque clé, par catégorie. Ne prend pas de nom. |
--json |
Le catalogue à la place de la liste (ci-dessous). Suit un nom et --host. |
--host <run\|host\|repl> |
Seulement ce qu'un binaire lit : run est orkeon (tout verbe qui construit l'hôte de run), host est orkeon-host, repl est orkeon-repl ; le nom du binaire est accepté aussi. Sans elle, tout ce qu'Orkeon lit, chaque section disant qui la lit. Un nom que le binaire choisi ne lit pas sort en 1 et dit qui le lit. |
--json est un contrat, comme doctor --json : un objet à deux tableaux, écrit sur stdout et rien d'autre.
{
"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": "…" }
]
}
| Champ | Dans | Sens |
|---|---|---|
path |
les deux | Le chemin de configuration. Un nom que l'opérateur choisit s'écrit <name>, un indice <i>. |
category |
section | L'un des onze identifiants de catégorie ci-dessus. |
hosts |
section | Les binaires livrés qui la lisent, parmi orkeon, orkeon-host et orkeon-repl. Toujours présent ; vide quand aucun ne la lit. |
registration |
section | L'enregistrement public par lequel un hôte écrit en C# lit la section. Absent quand seule la composition propre d'un binaire livré la lit. |
section |
clé | Le chemin de la section à laquelle la clé appartient. |
type |
clé | string, integer, number, boolean, duration, uri, date-time, enum, any, ou list of suivi de l'un d'eux. |
default |
clé | La valeur quand rien ne règle la clé, en valeur JSON. Absent quand il n'y en a pas, ou pas qui s'écrive — un secret, une valeur qui dépend de l'instant. |
defaultNote |
clé | Ce que la valeur ne peut pas dire, en mots : ce qui tient lieu d'un défaut qui n'est pas une constante, les entrées qu'un dictionnaire porte au départ, ce dont le défaut dépend. Absent sinon. |
values |
clé | Les valeurs qu'un enum accepte. Absent sinon. |
secret |
clé | true quand la valeur est un secret ; une telle clé n'a ni default ni defaultNote. Absent sinon. |
description |
les deux | Ce que la section configure, ce que la clé veut dire. |
Les sections viennent par catégorie, dans l'ordre de la liste, puis par chemin ; les clés dans l'ordre de leurs sections, puis par chemin. Le même build écrit les mêmes octets sur toute machine : ni date, ni chemin, des fins de ligne LF. Avec un nom ou --host la forme est la même et le contenu plus étroit — une catégorie ou une section donne ses sections et leurs clés, une clé sa section et elle-même, un mot ce qu'il a trouvé. Un champ peut s'ajouter plus tard : lisez ceux que vous connaissez.
orkeon settings env liste les variables d'environnement que lit Orkeon, les trois sortes que la référence de configuration met en tableaux : celles qui portent un réglage (ORKEON_<Section>__<Clé>, la même sans le préfixe, ORKEON_<NOM> pour un secret), celles qu'un binaire lit par leur nom — chacune avec la valeur qu'elle prend, les binaires qui la lisent et ce qu'elle fait : ORKEON_DEBUG, ORKEON_ALLOW_EXTERNAL_MOUNTS, ORKEON_ESBUILD_PATH, TUI_DRIVER, XDG_CONFIG_HOME, … — et les clés de réglage qui nomment une variable (Llm:ApiKeyEnvVar, …), tirées du catalogue. Il lit la même liste que la page de référence, qu'un test y tient, et aucune variable de la machine : il dit ce qu'Orkeon lirait, pas ce qui est posé. env est cette liste et non le mot : ce que le mot nomme ou décrit parmi les réglages — MCP:Servers:<name>:Env:<name> — la suit. Il accepte --json et aucune autre option :
{
"settingsPrefix": "ORKEON_",
"variables": [
{ "name": "ORKEON_DEBUG", "readBy": ["orkeon"], "value": "`1`, `true` or `yes`", "effect": "…" }
],
"namedBySettings": ["Llm:ApiKeyEnvVar", "Llm:Profiles:<name>:ApiKeyEnvVar"]
}
readBy nomme des binaires livrés ; value et effect sont des phrases pour un lecteur, en Markdown et en anglais ; namedBySettings sont des chemins du catalogue ci-dessus. Un contrat comme celui du catalogue : un champ peut s'ajouter, aucun ne change de sens.
Codes de sortie : 0 listé ; 1 un nom qui ne désigne rien ou que le binaire de --host ne lit pas, une option inconnue, un --host qui n'est aucun des trois, env avec une autre option que --json.
orkeon-repl — la console interactive séparée
orkeon-repl est un outil distinct construit depuis src/apps/Orkeon.ConsoleApp (commande dotnet tool orkeon-repl) : un REPL interactif complet pour piloter agents, crews et outils depuis une console Terminal.Gui à deux volets (logs + REPL), avec toute la pile du framework câblée — outils intégrés, RAG, analyse de code, embeddings locaux — et des commandes scriptées en TypeScript. Il ne partage volontairement pas le nom d'assembly orkeon.
Il vous parvient comme dotnet tool, dans les archives de release multi-apps, dans l'image ghcr.io/orkeon/orkeon, et dans le paquet Debian et Ubuntu (/usr/bin/orkeon-repl, self-contained : apt install orkeon n'exige aucun .NET). Depuis un clone, voir Installer le REPL depuis les sources. Il n'a ni --help ni --version : il ouvre sa console, et avec stdin fermé et --ui plain il affiche sa bannière et s'arrête à la fin de l'entrée.
| Option | Description |
|---|---|
--ui tui\|plain\|auto |
La console : la TUI à deux volets, ou une console en lignes simples. auto (le défaut) choisit la TUI sur un terminal interactif, et la console simple quand CI=true, quand stdin ou stdout est redirigé, ou quand TERM n'est pas défini sous Linux. Une valeur inconnue sort en 2. |
--repl-wrap on\|off |
Retour à la ligne dans le volet REPL (défaut on ; true/false/1/0 sont acceptés). Une valeur inconnue sort en 2. |
--llm-log / --llm-log-path <rép> |
Le journal des échanges LLM d'orkeon run : chaque requête et chaque réponse en JSONL sous ./llm-logs, ou <rép>, qui implique --llm-log ; réglé par LlmLogging. Un dossier hors du répertoire de travail demande --allow-external-mounts ; sans lui, le REPL refuse de démarrer (code de sortie 1) avec la ligne d'orkeon run. |
--replay <fichier> |
Donne au REPL les lignes de <fichier> comme si elles étaient tapées, puis sort : la console simple (ni TUI, ni éditeur de ligne), chaque ligne affichée en écho, les journaux sur stderr. Code de sortie 0 quand chaque ligne est passée, 1 quand le rejeu s'est arrêté sur une erreur ou que le REPL lui-même a échoué (une ligne sur stderr), 2 quand le fichier est absent ou illisible. Voir Rejeu plus bas. |
--interactive |
Avec --replay : la console habituelle (TUI ou simple), le fichier rejoué, puis le clavier rendu. Sans --replay, c'est une erreur d'usage (sortie 2). |
--log-level <niveau> |
Le niveau minimal des journaux (Trace, Debug, Information — le défaut —, Warning, Error, Critical, None). Un niveau inconnu sort en 2. Sous --replay seul, il filtre les journaux écrits sur stderr ; dans la TUI, c'est le niveau de départ du volet des journaux (F2 / Maj+F2 le changent toujours). |
--runner=scripted-commands |
Démarre dans le REPL des commandes scriptées au lieu du menu principal. |
--commands-dir <chemin> / --no-script-commands / --strict-commands |
Où trouver les commandes *.cmd.ts, ou aucune, ou l'échec immédiat sur une commande cassée. |
--crews-dir <chemin> |
Où script-host résout une crew par son nom. |
--settings <chemin> / --mount <spec> |
Les fichiers de settings, à la place du fichier global (les derniers l'emportent), et des montages VFS — placés et gardés comme pour orkeon run : un --mount sur une racine que les settings déclarent remplace ses entrées pour la session (le journal dit mount /x: --mount replaces the settings entry), un --mount sur une racine neuve s'ajoute. Avant que la console s'ouvre, les lignes d'orkeon run refusent, avec le code de sortie 1, un montage sur /sandbox, sur /credentials ou sur une racine que le REPL monte lui-même (/cli-commands… avec --commands-dir, /crews… avec --crews-dir), une racine montée deux fois en ligne de commande — la même spec deux fois comprise —, une racine déclarée deux fois sans rien pour en choisir une (la ligne nomme --mount, le REPL n'ayant pas --mount-id), un dossier absent — ceux de --commands-dir et --crews-dir compris —, d'où que vienne le montage : --settings, le fichier global, une variable, --Orkeon:FileSystem:Mounts:<n>=…. |
--allow-external-mounts |
Un --mount hors du répertoire de travail est lisible, comme pour orkeon run (ou ORKEON_ALLOW_EXTERNAL_MOUNTS=1) ; sans lui, le REPL refuse de démarrer (code de sortie 1) avec la même ligne. Toute entrée des settings en vigueur (une entrée choisie par id comprise), et les dossiers de --commands-dir et --crews-dir — des entrées du REPL, comme le script d'orkeon run — sont lisibles où qu'ils soient, sans lui. |
Les cinq dernières lignes sont détaillées dans Commandes CLI en TypeScript ; chaque option à valeur accepte --x valeur et --x=valeur. --commands-dir, --crews-dir, --settings et --mount s'additionnent quand on les répète ; --llm-log-path garde le dernier ; --ui et --repl-wrap gardent le premier et prennent toujours le mot suivant comme valeur (--repl-wrap --ui plain sort en 2), et --ui= vaut auto. --replay et --log-level refusent une valeur qui commence par -- (--replay --interactive ne nomme aucun fichier : sortie 2). Les options standard de l'hôte .NET (surcharges de configuration --Cle=Valeur) s'appliquent aussi.
Réglages. Le REPL lit les réglages que lisent les runners, dans leur ordre : les variables d'environnement sans préfixe, les fichiers --settings — sinon le fichier global qu'écrit orkeon init ; un fichier nommé sur la ligne de commande le remplace, comme pour orkeon run —, puis les variables d'environnement ORKEON_, préfixe retiré (ORKEON_Llm__ApiKey est Llm:ApiKey ici comme dans chaque runner) ; la ligne de commande reste en dernier. Rien d'autre : ni l'appsettings.json du répertoire courant, ni les secrets utilisateur (d'où viennent les réglages). Sa section Llm et ses profils sont lus par le lecteur des runners, ApiKeyEnvVar compris, et le volet des journaux dit une fois d'où vient chaque clé, avec un avertissement par référence vers une variable posée nulle part.
Un réglage refusé. Le REPL juge ses réglages à son démarrage comme orkeon run : une valeur, une clé, un nom qu'il refuse, un niveau de journal qui n'en est pas un, un Orkeon:Rag:LlmProfile qu'il n'offre pas, un fichier --settings qu'il ne peut pas lire (nommé, avec la ligne et la position) — une ligne, orkeon-repl: <raison>, sur stderr, et le code 1, avant que la console ne s'ouvre. Un drapeau invalide garde son code 2.
Approbations des appels d'outils. Avec le contrôle des permissions activé (Orkeon:Security:PermissionGate:Enabled = true), un appel d'outil pour lequel le mode de la session demande — tout sauf une lecture en default, une commande en acceptEdits — vous est soumis au lieu d'être refusé. Un crew qui tourne en arrière-plan écrit la question dans la console, au nom de sa tâche (? [t1] dev-batches: tool 'shell_command' requires approval (mode 'default')., puis l'outil et ses arguments), et l'invite devient approve <outil> for [t1]? [y] once / [s] session / [n] no > . Dans la console à volets, la question s'affiche sur l'écran affiché et est enregistrée une fois dans l'écran de la tâche qui demande, quel que soit l'écran affiché ; la console simple écrit la question dans le fil de ses lignes. Dans le TUI, la question ouvre un panneau de sélection à la place de la saisie, sur Oui : Entrée confirme l'option sélectionnée, et Entrée seul autorise donc l'appel une fois (y, s et n en sélectionnent une, aucune ne répond seule), Esc refuse, et / la rend à la saisie. Une fois rendue, la ligne de statut montre la question tant qu'elle attend, quoi qui tourne (? [t1] dev-batches asks to run shell_command… ({"command":"npm test"} · answer y once · s session · n no), l'appel coupé à 60 caractères), la ligne de la tâche indique ? waits for approval of shell_command, et son détail (Entrée sur la ligne) donne l'appel entier. Votre ligne suivante y répond : y exécute l'appel, s l'exécute et autorise l'outil sans plus demander jusqu'à la sortie du REPL, n le refuse, et le modèle lit DENIED: … The operator denied the call. comme résultat de l'outil (yes, session, no, o, oui et non sont acceptés aussi). Une ligne qui commence par / exécute toujours sa commande, la question attendant pendant ce temps (/cancel --ticket=<id> annule le crew et retire sa question) ; toute autre ligne repose la question en entier, si bien qu'un texte libre n'atteint jamais l'assistant pendant qu'une question attend. Plusieurs questions s'affichent une à une. L'attente ne compte pas dans la limite de temps du crew. Une question se lit entre deux commandes, ou, pour un crew lancé par runCrew (synchrone), par l'appel en attente lui-même, et le temps mis à répondre ne compte pas dans RunCrewTimeout (limitations). Les règles qu'une commande pose pour la session (ctx.services.get("permissions"), commandes scriptées) décident d'un appel avant le mode : un appel qu'une règle autorise passe sans question, sauf en plan, et un appel qu'une règle refuse est refusé dans tous les modes. ctx.services.get("permissions").enabled dit si le contrôle est activé : à false, les règles et les modes ne contrôlent rien.
Questions human_input. Une question que pose l'outil human_input se lit à la ligne suivante, comme une approbation : l'invite devient answer> , une option numérotée ou sa valeur répond à un choix, et une ligne vide prend l'option recommandée ou la valeur par défaut. Une question posée par une tâche d'arrière-plan nomme cette tâche : [t8] dev-spec asks: <question>, puis ses options. Dans la console à volets, elle s'affiche sur l'écran affiché et dans l'écran de la tâche, l'invite lit answer [t8]> , et la réponse se tape dans le champ principal ou dans le fil de la tâche (choisir la tâche dans la liste des tâches, puis Entrée sur la ligne) ; envoyée à une tâche qui n'attend aucune réponse, la ligne reste dans le champ (@<task> waits for no answer: nothing was sent, the text stays in the field.). La console simple imprime la question dans le fil de ses lignes, marquée de la même façon. Une fois la réponse prise, [t8] answer taken: <answer> clôt la question : la ligne suivante est un nouveau tour. Plusieurs questions se posent une à une : la suivante est annoncée ([t9] <task> has a question: asked once the one waiting is answered.) et écrite une fois celle qui attend répondue. Une question retirée avant sa réponse dit [t8] question withdrawn. Tant qu'une approbation d'outil attend, le champ principal répond d'abord à l'approbation, et l'invite ne lit pas answer [t8]> . Une ligne qui commence par / lance toujours sa commande pendant que la question attend.
Consommation de la session. Une commande scriptée lit la consommation LLM de la session par ctx.services.get("usage").report() (commandes scriptées) : les tokens de prompt, de complétion, lus et écrits dans le cache et de raisonnement de la session, puis une ligne par modèle et une par instance de commande (un crew lancé par runCrewAsync compris), chacune avec son coût — ce que le fournisseur a facturé, sinon le prix du registre pour le modèle (Orkeon:CostTracking), null quand aucun des deux n'est connu. L'outil token_budget répartit les tokens que tient le tampon de session par sorte d'entrée (used_tokens_by_kind : system, user, assistant, tool, et other pour une note), si bien qu'une commande /context dit ce qui remplit la fenêtre.
Rejeu. --replay <fichier> rejoue une session : chaque ligne du fichier est donnée exactement comme si elle était tapée — une commande, du texte libre pour l'assistant, ou la réponse à une question. Le fichier est lu par le VFS, un chemin relatif contre le répertoire de travail (/workspace sur un projet) ; les lignes finissent par LF ou CRLF ; une ligne vide et une ligne dont le premier caractère non blanc est # sont sautées. Avant chaque ligne, le rejeu attend qu'aucune instance de commande ne tourne, crews en arrière-plan comprises (/tasks), et cesse d'attendre dès qu'une question demande la ligne : une approbation d'appel d'outil, ou une question human_input, reçoit la ligne suivante du fichier, comme vous y répondriez. Le rejeu s'arrête à la première erreur — une commande qui échoue ou est annulée, une commande inconnue, une tâche d'arrière-plan lancée par le rejeu qui finit en échec ou dont le rappel completed() lève une erreur ([t1] <commande> completed() failed: <erreur>, imputé à la ligne qui l'a lancée ; un completed() qui dure seulement longtemps est attendu, ce n'est pas une erreur), une question qui attend encore quand le fichier se termine (replay ended with an approval waiting: <outil>), une commande qui lit une ligne que le fichier n'a pas (la lecture reçoit la fin de l'entrée, sous --interactive aussi : le clavier ne revient qu'après la ligne d'arrêt), Ctrl-C (qui annule aussi la commande en cours ; dans la TUI, la touche d'interruption Échap Échap) — avec replay stopped at line N: <cause>, sur une ligne à part. Une ligne répond à une approbation, que la lise la boucle de lecture ou un runCrew en attente ; une réponse pour toute la session (s) règle en outre d'un coup chaque approbation en file pour le même outil, et le fichier ne porte donc aucune ligne pour elles. Le rejeu ne conclut qu'une fois finis la commande en cours, le travail d'arrière-plan qu'elle a lancé et leurs rappels completed() (avec ce qu'ils lancent) : un échec après la dernière ligne compte encore. Un second Ctrl-C pendant que le rejeu s'arrête encore (une commande qui ignore son annulation), ou un Ctrl-C sans rejeu en cours, termine le processus comme d'habitude (code de sortie 130 sous Linux et macOS). Seul, --replay sort alors avec le code 1 ; avec --interactive, il rend le clavier, comme à la fin du fichier (replay finished: N line(s)). Dans une session, /replay <fichier> rejoue un fichier de la même façon et rend toujours le clavier ; il est refusé pendant qu'un rejeu tourne.
# smoke.replay — à lancer par : orkeon-repl --runner=scripted-commands --replay smoke.replay
/help
/dev-batches plan.md
# le crew demande à lancer shell_command : l'autoriser pour la session
s
/tasks
Serveurs MCP et plugins. Le REPL connecte les serveurs que ses réglages déclarent sous MCP:Servers avant de charger ses commandes, comme orkeon run le fait avant de charger une crew, et charge les plugins d'une section Plugins. Leurs outils atteignent l'espace de noms tools d'une commande et les crews qu'elle lance (.tools([...]), act) comme les outils intégrés ; un serveur qui échoue coûte une ligne d'erreur et le REPL démarre. Voir Intégration MCP et Plugins.
Les autres binaires livrés
Les archives de release portent plus de lanceurs que les deux documentés ici : orkeon-slim
(la même CLI, framework-dependent) et orkeon-host (le daemon de service longue durée —
voir le service host). La liste est complète. La
matrice de publication et
Trois façons d'exécuter Orkeon listent
exactement quelle archive porte quoi.
Voir aussi : Trois façons d'exécuter Orkeon · Exécuter votre premier exemple · Retour à l'index