Utiliser le CLI

L'outil en ligne de commande awr est le point d'entrée complet de gestion d'un projet AWR : tout ce qu'un agent peut faire via MCP, vous pouvez le faire depuis votre terminal — plus l'administration du projet que MCP n'expose pas.

Installation

Les deux canaux de paquets installent le même CLI Rust et le même serveur MCP ; il n'y a pas de SDK JavaScript ou Python séparé :

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

Vérifiez avec awr --version et awr-mcp --version.

Les cibles prises en charge sont macOS 15+ (arm64 et Intel), Linux avec glibc 2.39+ (la base Ubuntu 24.04, x64 et arm64), et Windows x64. Le lanceur npm requiert Node 22.14+ et s'appuie sur des paquets natifs optionnels, donc gardez les dépendances optionnelles activées ; le lanceur PyPI requiert Python 3.9+. Sous Linux, vérifiez glibc avec ldd --version | head -n 1. Git n'est requis que pour les opérations liées à Git ; SQLite est embarqué. Pour un premier projet pas à pas, voir Démarrage rapide.

La forme de chaque commande

Les exemples CLI de toute la documentation partagent un préfixe commun :

awr --project /absolute/project --json <command>

--project pointe vers la racine du projet ; --json fait passer stdout à un unique objet JSON lisible par machine (détails ci-dessous). Omettez --json quand vous lisez la sortie vous-même — la sortie humaine par défaut est délibérément bornée : status montre au plus une suggestion courante et ready liste au plus 10 éléments.

Vérifier où en est le projet

status est votre premier arrêt. Sa vue action par défaut montre la continuation courante, le travail réservable, les attentes, les blocages réels et un résumé de l'historique :

awr --project /absolute/project status --view full --branch main

--view action/full/summary — la valeur par défaut est action ; full donne la structure complète historique.
--branch NAME_OR_ID — lit une branche par nom, identifiant interne ou main au lieu de la branche par défaut. Sélectionner une branche pour une lecture ne change jamais la branche par défaut, les sessions, les réservations ou votre checkout Git.

ready liste les éléments de travail qui peuvent être pris, avec des diagnostics, des informations de réservation et des indications de troncature. --limit vaut 10 par défaut et accepte 1 à 100 ; --branch fonctionne aussi ici :

awr --project /absolute/project ready --limit 25

Lire les éléments de travail

work show donne un élément en entier — tâche, critères d'acceptation, dépendances, décisions, preuves et provenance. --source-sha SHA le lit tel qu'il était à une révision source précise ; --branch le lit sur une autre branche :

awr --project /absolute/project work show W-123 --source-sha abc123

search trouve des éléments dans tout le projet. Le texte de la requête est positionnel ; --type, --status, --work et --limit restreignent les résultats :

awr --project /absolute/project search "payment retry" --type work --limit 20

Compiler le contexte d'une tâche

context compile assemble le contexte d'exécution L1 — l'ensemble de travail budgété d'une tâche — avec la complétude, les lacunes, la provenance et le hash de contexte :

awr --project /absolute/project context compile --work W-123

Toutes ces options sont optionnelles : --session et --detached contrôlent la liaison de session ; --agent, --intent et --budget orientent la compilation ; --goal, --path et --tag sont répétables ; --source-sha compile contre une version source précise ; --checkpoint et --after-revision définissent des bases de référence personnalisées et sont mutuellement exclusifs. --branch ID utilise la base de contexte ordinaire sur une autre branche — un sens différent de branch context, qui compile l'incrément d'une branche nommée depuis sa dérivation sans changer votre branche par défaut :

awr --project /absolute/project branch context feature-x --work W-123

La sortie texte par défaut est le contexte d'exécution contraint par le budget, avec les critères d'acceptation complets et les règles strictes préservés. Si des lacunes requises existent, le résultat JSON a ok=false avec error.code=ContextIncomplete ; si des faits stricts dépassent le budget, vous obtenez BudgetExceeded — jamais des faits silencieusement tronqués.

Faire avancer le travail

Les éléments de travail changent d'état via les sous-commandes work :

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

La même forme s'applique à block, unblock, cancel et reopen, avec --next-action, --summary et --blocker portant les détails correspondants. L'achèvement lie les critères d'acceptation et les preuves depuis un fichier JSON et libère la réservation de cette session en cas de succès :

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

Enregistrer des événements et des preuves

event append écrit dans le journal du projet :

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

Options facultatives : --work, --session, --branch, --importance (par défaut normal) et --payload FILE (un fichier de valeur JSON, {} si omis). La sortie par défaut montre l'identifiant, le type, le résumé court et la version — elle ne répercute pas le payload ; utilisez event show --full pour développer un événement explicitement. Vous ne pouvez pas forger d'événements de domaine réservés tels que work.completed ; ceux-ci ne proviennent que des commandes de changement d'état.

evidence add enregistre une preuve depuis un fichier d'entrée JSON :

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

Les champs d'entrée incluent work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope et verified_at. Une écriture réussie renvoie l'enregistrement sauvegardé et un event_id, mais l'enregistrement n'est pas une exécution : validation_basis=caller_supplied_bindings signifie qu'AWR a stocké les liaisons que vous avez soumises — pas qu'il a exécuté votre commande ni que l'acceptation métier a réussi. evidence show donne la vue de lecture résumée d'un enregistrement ; ce n'est pas un reçu d'écriture.

Règles de chemins et de tailles : les chemins relatifs dans les entrées de preuves et les payloads d'événements se résolvent par rapport à la racine --project ; les chemins relatifs dans une entrée d'achèvement se résolvent par rapport au répertoire courant du processus, donc utilisez des chemins absolus dans l'automatisation. Les fichiers d'entrée de preuves et de payloads d'événements sont plafonnés à 1 Mio, les entrées d'achèvement à 64 Kio.

Révisions et concurrence optimiste

Les écritures prennent --expected-revision R, où R est la dernière project_revision que vous avez observée. Si le projet a avancé entre-temps, l'écriture échoue avec RevisionConflict au lieu d'écraser silencieusement le travail de quelqu'un d'autre — relisez avec status et réessayez contre la nouvelle révision. Trois numéros de version apparaissent dans la sortie et ne sont pas interchangeables : revision est la version d'un objet, source_revision est la version de la source, et project_revision est la version de l'état du projet.

Si une écriture est interrompue ou partiellement appliquée, vérifiez la proposition, les événements, la session et la révision courante avant de décider quoi faire ensuite — ne réessayez pas aveuglément après un échec de processus. Deux erreurs d'espace de travail méritent mention : WorkspaceConflict (venant de awr workspace) signifie que les deux côtés ont édité le même fichier suivi et que rien n'est fusionné automatiquement ; WorkspaceContended signifie qu'un publish ou un drop a été préempté trois commits de suite, et le remède est simplement de relancer la même commande.

Sortie JSON, erreurs et codes de sortie

Avec --json, une commande réussie imprime exactement un objet JSON sur stdout. Les erreurs sont du JSON typé sur stderr :

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

Analysez les deux flux séparément — ne les fusionnez jamais avec 2>&1 pour analyser le texte combiné. code et details sont la base lisible par machine pour les décisions ; message est pour les humains. --json peut se placer avant ou après une sous-commande connue ; placez-le avant la commande pour obtenir des erreurs JSON pour les commandes de premier niveau inconnues. Codes de sortie :

0 — succès (aussi --help et --version).
1 — une erreur de domaine (erreur typée sur stderr), éventuellement avec un corps partiel inspectable sur stdout ; aussi Unsupported pour les commandes de premier niveau non implémentées.
2 — arguments manquants ou invalides ou sous-commandes imbriquées inconnues ; InvalidInput en mode --json.

Où le CLI s'arrête et où MCP commence

Le CLI et le serveur MCP exposent le même état de domaine : pour les outils partagés de travail et de contexte, les deux renvoient les mêmes identifiants, versions, critères d'acceptation, dépendances, diagnostics et lacunes sous le même projet, la même sélection de branche, la même source indexée et les mêmes paramètres. La différence est une question de posture :

Le CLI est le point d'entrée complet de gestion de projet, et ses lectures peuvent rafraîchir des projections de base de données reconstructibles (source_refresh).
Les outils de lecture MCP sont strictement en lecture seule (read_only=true). Si la source a changé, une lecture MCP refuse l'instantané obsolète avec SourceStale au lieu de rafraîchir ; exécutez awr source reindex et relisez.
MCP stdio expose un catalogue d'outils fixe pour les clients agents (le service HTTP partagé ajoute des outils de répertoire de projets) ; l'administration au-delà de ce catalogue reste dans le CLI.

En pratique, vous pilotez l'installation, l'administration, la réindexation et l'investigation ad hoc depuis le terminal, tandis que votre client agent appelle les outils MCP pendant une session. Voir Outils MCP pour le côté agent et Dépannage quand quelque chose tourne mal.