AWR
GitHub
日本語
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

CLIの使用

GitHub でソースを見る

awrコマンドラインツールは、AWRプロジェクトの完全な管理エントリーポイントです。エージェントがMCP経由で できることはすべてターミナルからもできます —— さらに、MCPが公開しないプロジェクト管理も行えます。

インストール

どちらのパッケージチャネルも同じRust CLIとMCPサーバーをインストールします。別のJavaScriptや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

awr --versionとawr-mcp --versionで確認してください。

サポートされるターゲットは、macOS 15以降（arm64およびIntel）、glibc 2.39以降のLinux（Ubuntu 24.04が ベースライン、x64およびarm64）、Windows x64です。npmランチャーはNode 22.14以降が必要で、オプションの ネイティブパッケージに依存するため、オプション依存関係を有効にしたままにしてください。PyPIランチャーは Python 3.9以降が必要です。Linuxではldd --version | head -n 1でglibcを確認してください。Gitは Git紐付け操作にのみ必要です。SQLiteは同梱されています。初めてのプロジェクトのウォークスルーは クイックスタートを参照してください。

すべてのコマンドの形

ドキュメント全体のCLI例は共通のプレフィックスを共有します:

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

--projectはプロジェクトルートを指し、--jsonはstdoutを単一の機械可読JSONオブジェクトに切り替えます （詳細は後述）。自分で出力を読むときは--jsonを外してください —— デフォルトの人間向け出力は意図的に 制限されています。statusは現在の提案を最大1件、readyは最大10件を表示します。

プロジェクトの現状を確認する

statusが最初の確認先です。デフォルトのactionビューは、現在の継続、クレーム可能な作業、待機、 実際のブロッカー、履歴サマリーを表示します:

awr --project /absolute/project status --view full --branch main
  • --view action/full/summary —— デフォルトはaction。fullは従来の完全な構造を返します。
  • --branch NAME_OR_ID —— デフォルトブランチの代わりに、名前、内部ID、またはmainでブランチを 読みます。読み取りのためにブランチを選択しても、デフォルトブランチ、セッション、クレーム、Gitの チェックアウトは一切変わりません。

readyは、診断、クレーム情報、切り捨てのヒント付きで、着手可能な作業アイテムを一覧します。 --limitはデフォルト10で、1から100を受け付けます。--branchもここで使えます:

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

作業アイテムを読む

work showは1つのアイテムの全体 —— タスク、受け入れ基準、依存関係、決定、証跡、来歴 —— を表示 します。--source-sha SHAは特定のソースリビジョン時点で読み、--branchは別のブランチで読みます:

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

searchはプロジェクト全体からアイテムを検索します。クエリテキストは位置引数です。--type、 --status、--work、--limitで結果を絞り込みます:

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

タスクのコンテキストをコンパイルする

context compileは、タスクのL1実行コンテキスト —— 予算化された作業セット —— を、完全性、ギャップ、 来歴、コンテキストハッシュとともに組み立てます:

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

以下はすべてオプションです。--sessionと--detachedはセッションバインドを制御します。--agent、 --intent、--budgetはコンパイルを調整します。--goal、--path、--tagは繰り返し指定可能です。 --source-shaは特定のソースバージョンに対してコンパイルします。--checkpointと--after-revisionは カスタムベースラインを設定し、相互に排他です。--branch IDは別のブランチで通常のコンテキスト ベースラインを使います —— これはbranch contextとは別の意味で、後者はデフォルトブランチを切り替えずに、 名前付きブランチがフォークしてからの増分をコンパイルします:

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

デフォルトのテキスト出力は、完全な受け入れ基準とハードルールが保持された、予算制約付きの実行 コンテキストです。必須のギャップが存在する場合、JSON結果はok=falseでerror.code=ContextIncomplete になります。ハードな事実が予算を超える場合はBudgetExceededになります —— 黙って切り捨てられる ことは決してありません。

作業を前に進める

作業アイテムはworkサブコマンドで状態を変更します:

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

block、unblock、cancel、reopenも同じ形で、--next-action、--summary、--blockerが対応する 詳細を運びます。完了はJSONファイルから受け入れ基準と証跡を紐付け、成功時にこのセッションのクレームを 解放します:

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

イベントと証跡を記録する

event appendはプロジェクトログに書き込みます:

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

オプションフラグ: --work、--session、--branch、--importance（デフォルトnormal）、 --payload FILE（JSON値のファイル。省略時は{}）。デフォルトの出力はID、タイプ、短いサマリー、 バージョンを表示します —— ペイロードはエコーしません。イベントを明示的に展開するには event show --fullを使います。work.completedのような予約済みドメインイベントを偽造することは できません。それらは状態変更コマンドからのみ生成されます。

evidence addはJSON入力ファイルから証跡を記録します:

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

入力フィールドにはwork_item_key、branch_id、external_key、evidence_type、level、summary、 locator、sha256、source_sha、command、scope、verified_atがあります。書き込みが成功すると 保存されたレコードとevent_idが返りますが、記録は実行ではありません。 validation_basis=caller_supplied_bindingsは、AWRがあなたの提出したバインディングを保存したことを 意味します —— コマンドを実行したことや、ビジネス上の受け入れが通ったことを意味しません。 evidence showはレコードのサマリー読み取りビューを返します。書き込みの領収書ではありません。

パスとサイズの規則: 証跡入力とイベントペイロード内の相対パスは--projectルートに対して解決されます。 完了入力内の相対パスはプロセスのカレントディレクトリに対して解決されるため、自動化では絶対パスを 使ってください。証跡入力とイベントペイロードのファイルは1 MiBまで、完了入力は64 KiBまでです。

リビジョンと楽観的並行制御

書き込みは--expected-revision Rを取ります。Rはあなたが最後に観察したproject_revisionです。 プロジェクトが先に進んでいる場合、書き込みは他人の作業を黙って上書きするのではなく RevisionConflictで失敗します —— statusで読み直し、新しいリビジョンで再試行してください。出力には 3つのバージョン番号が現れ、互換性はありません。revisionはオブジェクトのバージョン、 source_revisionはソースのバージョン、project_revisionはプロジェクト状態のバージョンです。

書き込みが中断されたり部分的に適用されたりした場合は、次に何をするか決める前に、提案、イベント、 セッション、現在のリビジョンを確認してください —— プロセス障害の後に闇雲に再試行しないでください。 2つのワークスペースエラーに触れておきます。WorkspaceConflict（awr workspaceから）は、両側が同じ 追跡ファイルを編集し、何も自動マージされなかったことを意味します。WorkspaceContendedはpublishまたは dropが3コミット連続で横取りされたことを意味し、対処は単純に同じコマンドをもう一度実行することです。

JSON出力、エラー、終了コード

--json付きでは、成功したコマンドはstdoutに正確に1つのJSONオブジェクトを出力します。エラーは stderrへの型付きJSONです:

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

2つのストリームは別々にパースしてください —— 2>&1でマージして結合テキストをパースしてはいけません。 codeとdetailsが判断のための機械可読の根拠で、messageは人間向けです。--jsonは既知のサブコマンドの 前後どちらに置いても構いません。未知のトップレベルコマンドでもJSONエラーを得たい場合は、コマンドの前に 置いてください。終了コード:

  • 0 —— 成功（--helpと--versionも含む）。
  • 1 —— ドメインエラー（stderrへの型付きエラー）。stdoutに部分的で検査可能な本文を伴う場合があります。 未実装のトップレベルコマンドのUnsupportedも含みます。
  • 2 —— 引数の欠落または不正、未知のネストされたサブコマンド。--jsonモードではInvalidInput。

CLIの終わりとMCPの始まり

CLIとMCPサーバーは同じドメイン状態を公開します。共有の作業・コンテキストツールでは、同じプロジェクト、 ブランチ選択、インデックス済みソース、パラメータのもとで、両者が同じ識別子、バージョン、受け入れ基準、 依存関係、診断、ギャップを返します。違いは姿勢です:

  • CLIは完全なプロジェクト管理エントリーポイントであり、その読み取りは再構築可能なデータベース プロジェクションを更新することがあります（source_refresh）。
  • MCPの読み取りツールは厳密に読み取り専用です（read_only=true）。ソースが変更されている場合、MCPの 読み取りは更新する代わりに古いスナップショットをSourceStaleで拒否します。awr source reindexを 実行してから再度読んでください。
  • MCP stdioはエージェントクライアント向けの固定ツールカタログを公開します（共有HTTPサービスは プロジェクトディレクトリツールを追加します）。そのカタログを超える管理はCLIに残ります。

実際には、セットアップ、管理、再インデックス、アドホックな調査はターミナルから行い、エージェント クライアントがセッション中にMCPツールを呼び出します。エージェント側はMCPツールを、 問題が起きたときはトラブルシューティングを参照してください。