Die CLI verwenden

Die awr-Kommandozeile ist der vollständige Verwaltungs-Einstiegspunkt für ein AWR-Projekt: Alles, was ein Agent über MCP tun kann, kannst du von deinem Terminal aus tun — plus die Projektverwaltung, die MCP nicht bereitstellt.

Installation

Beide Paketkanäle installieren dieselbe Rust-CLI und denselben MCP-Server; es gibt kein separates JavaScript- oder Python-SDK:

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

Überprüfe mit awr --version und awr-mcp --version.

Unterstützte Zielplattformen sind macOS 15+ (arm64 und Intel), Linux mit glibc 2.39+ (die Ubuntu-24.04-Basislinie, x64 und arm64) und Windows x64. Der npm-Launcher erfordert Node 22.14+ und setzt auf optionale native Pakete, also lass optionale Abhängigkeiten aktiviert; der PyPI-Launcher erfordert Python 3.9+. Prüfe unter Linux glibc mit ldd --version | head -n 1. Git wird nur für Git-gebundene Operationen benötigt; SQLite ist gebündelt. Für einen Rundgang durch das erste Projekt siehe Schnellstart.

Die Form jedes Befehls

CLI-Beispiele in der gesamten Dokumentation teilen einen gemeinsamen Präfix:

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

--project zeigt auf das Projektstammverzeichnis; --json schaltet stdout auf ein einzelnes maschinenlesbares JSON-Objekt um (Details unten). Lass --json weg, wenn du die Ausgabe selbst liest — die Standardausgabe für Menschen ist bewusst begrenzt: status zeigt höchstens einen aktuellen Vorschlag, und ready listet höchstens 10 Einträge.

Prüfen, wo das Projekt steht

status ist deine erste Anlaufstelle. Seine Standardansicht action zeigt die aktuelle Fortsetzung, claimbare Arbeit, Wartezustände, tatsächliche Blocker und eine Verlaufszusammenfassung:

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

--view action/full/summary — Standard ist action; full liefert die vollständige Legacy-Struktur.
--branch NAME_OR_ID — einen Branch per Name, interner ID oder main statt des Standard-Branchs lesen. Das Auswählen eines Branchs für einen Lesevorgang ändert niemals den Standard-Branch, Sessions, Claims oder deinen Git-Checkout.

ready listet Arbeitselemente, die übernommen werden können, mit Diagnosen, Claim-Informationen und Hinweisen zur Kürzung. --limit ist standardmäßig 10 und akzeptiert 1 bis 100; --branch funktioniert auch hier:

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

Arbeitselemente lesen

work show liefert ein Element vollständig — Aufgabe, Abnahmekriterien, Abhängigkeiten, Entscheidungen, Nachweise und Herkunft. --source-sha SHA liest es zum Stand einer bestimmten Quellenrevision; --branch liest es auf einem anderen Branch:

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

search findet Elemente im ganzen Projekt. Der Abfragetext ist positional; --type, --status, --work und --limit grenzen die Ergebnisse ein:

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

Kontext für eine Aufgabe kompilieren

context compile stellt den L1-Ausführungskontext zusammen — das budgetierte Arbeitsset für eine Aufgabe — mit Vollständigkeit, Lücken, Herkunft und dem Kontext-Hash:

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

Alle diese Optionen sind optional: --session und --detached steuern die Session-Bindung; --agent, --intent und --budget steuern die Kompilierung; --goal, --path und --tag sind wiederholbar; --source-sha kompiliert gegen eine bestimmte Quellenversion; --checkpoint und --after-revision setzen eigene Basislinien und schließen sich gegenseitig aus. --branch ID nutzt die gewöhnliche Kontextbasislinie auf einem anderen Branch — eine andere Bedeutung als branch context, das das Inkrement eines benannten Branchs seit seiner Abzweigung kompiliert, ohne deinen Standard-Branch zu wechseln:

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

Die Standard-Textausgabe ist der budgetbegrenzte Ausführungskontext mit vollständig erhaltenen Abnahmekriterien und harten Regeln. Wenn erforderliche Lücken existieren, hat das JSON-Ergebnis ok=false mit error.code=ContextIncomplete; wenn harte Fakten das Budget überschreiten, erhältst du BudgetExceeded — niemals stillschweigend gekürzte Fakten.

Arbeit voranbringen

Arbeitselemente ändern ihren Zustand über work-Unterbefehle:

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

Dieselbe Form gilt für block, unblock, cancel und reopen, wobei --next-action, --summary und --blocker die entsprechenden Details tragen. Der Abschluss bindet Abnahmekriterien und Nachweise aus einer JSON-Datei und gibt bei Erfolg den Claim dieser Session frei:

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

Ereignisse und Nachweise aufzeichnen

event append schreibt in das Projektlog:

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

Optionale Flags: --work, --session, --branch, --importance (Standard normal) und --payload FILE (eine JSON-Wertdatei, {} wenn weggelassen). Die Standardausgabe zeigt ID, Typ, Kurzzusammenfassung und Version — sie gibt das Payload nicht zurück; nutze event show --full, um ein Ereignis explizit zu expandieren. Du kannst reservierte Domänenereignisse wie work.completed nicht fälschen; diese kommen nur von den Zustandsänderungsbefehlen.

evidence add zeichnet Nachweise aus einer JSON-Eingabedatei auf:

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

Eingabefelder sind unter anderem work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope und verified_at. Ein erfolgreicher Schreibvorgang gibt den gespeicherten Datensatz und eine event_id zurück, aber Aufzeichnen ist nicht Ausführung: validation_basis=caller_supplied_bindings bedeutet, dass AWR die von dir übermittelten Bindungen gespeichert hat — nicht, dass es deinen Befehl ausgeführt hat oder dass die fachliche Abnahme bestanden wurde. evidence show liefert die zusammenfassende Leseansicht eines Datensatzes; es ist kein Schreibbeleg.

Pfad- und Größenregeln: Relative Pfade in Nachweis-Eingaben und Ereignis-Payloads werden gegen das --project-Stammverzeichnis aufgelöst; relative Pfade in einer Abschluss-Eingabe werden gegen das aktuelle Verzeichnis des Prozesses aufgelöst — verwende daher in der Automatisierung absolute Pfade. Nachweis-Eingabe- und Ereignis-Payload-Dateien sind auf 1 MiB begrenzt, Abschluss-Eingaben auf 64 KiB.

Revisionen und optimistische Nebenläufigkeit

Schreibvorgänge nehmen --expected-revision R, wobei R die zuletzt von dir beobachtete project_revision ist. Wenn das Projekt weitergezogen ist, schlägt der Schreibvorgang mit RevisionConflict fehl, statt die Arbeit eines anderen stillschweigend zu überschreiben — lies mit status erneut und versuche es mit der neuen Revision. Drei Versionsnummern erscheinen in der Ausgabe und sind nicht austauschbar: revision ist die Version eines Objekts, source_revision die Version der Quelle und project_revision die Version des Projektstatus.

Wenn ein Schreibvorgang unterbrochen oder teilweise angewendet wird, prüfe den Vorschlag, die Ereignisse, die Session und die aktuelle Revision, bevor du entscheidest, was als Nächstes zu tun ist — wiederhole nach einem Prozessfehler nicht blind. Zwei Workspace-Fehler verdienen Erwähnung: WorkspaceConflict (von awr workspace) bedeutet, beide Seiten haben dieselbe verfolgte Datei bearbeitet, und nichts wird automatisch gemergt; WorkspaceContended bedeutet, ein publish oder drop wurde drei Commits in Folge verdrängt, und die Abhilfe ist schlicht, denselben Befehl erneut auszuführen.

JSON-Ausgabe, Fehler und Exit-Codes

Mit --json gibt ein erfolgreicher Befehl genau ein JSON-Objekt auf stdout aus. Fehler sind typisiertes JSON auf stderr:

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

Parse die beiden Streams getrennt — führe sie niemals mit 2>&1 zusammen und parse den kombinierten Text. code und details sind die maschinenlesbare Grundlage für Entscheidungen; message ist für Menschen. --json darf vor oder nach einem bekannten Unterbefehl stehen; setze es vor den Befehl, um JSON-Fehler für unbekannte Top-Level-Befehle zu erhalten. Exit-Codes:

0 — Erfolg (auch --help und --version).
1 — ein Domänenfehler (typisierter Fehler auf stderr), möglicherweise mit einem partiellen, einsehbaren Body auf stdout; auch Unsupported für nicht implementierte Top-Level-Befehle.
2 — fehlende oder ungültige Argumente oder unbekannte verschachtelte Unterbefehle; InvalidInput im --json-Modus.

Wo die CLI endet und MCP beginnt

Die CLI und der MCP-Server stellen denselben Domänenzustand bereit: Bei den gemeinsamen Arbeits- und Kontext-Tools geben beide dieselben Bezeichner, Versionen, Abnahmekriterien, Abhängigkeiten, Diagnosen und Lücken unter demselben Projekt, derselben Branch-Auswahl, derselben indizierten Quelle und denselben Parametern zurück. Der Unterschied ist die Haltung:

Die CLI ist der vollständige Projektverwaltungs-Einstiegspunkt, und ihre Lesevorgänge dürfen wiederherstellbare Datenbankprojektionen aktualisieren (source_refresh).
MCP-Lesetools sind strikt schreibgeschützt (read_only=true). Wenn sich die Quelle geändert hat, verweigert ein MCP-Lesevorgang den veralteten Snapshot mit SourceStale, statt zu aktualisieren; führe awr source reindex aus und lies erneut.
MCP stdio stellt einen festen Tool-Katalog für Agent-Clients bereit (der gemeinsame HTTP-Dienst ergänzt Projektverzeichnis-Tools); Verwaltung jenseits dieses Katalogs bleibt in der CLI.

In der Praxis steuerst du Einrichtung, Verwaltung, Reindizierung und Ad-hoc-Untersuchungen vom Terminal, während dein Agent-Client während einer Session MCP-Tools aufruft. Siehe MCP-Tools für die Agent-Seite und Fehlerbehebung, wenn etwas schiefgeht.