CLI の概要
aggrega CLI はコンパイラのエントリポイントです。Aggrega とのあらゆるやり取り(Aggregate をデプロイ可能な成果物へコンパイルすること、カタログや IR の調査、依存関係の解決と固定、カタログエンティティの公開、validate による正しさの検査、lint による公開の慣例の検査、IDE へのサービス提供)は、aggrega のサブコマンドを通じて実行されます。この一連の章では、各サブコマンドのフラグ、入力、出力を説明します。
aggrega validate と aggrega lint は互いに補完し合うチェッカーで、同じ 3 つのスコープ(カタログ全体、Release の依存関係クロージャ、または 1 つのエンティティ)を対称的に持ちます。aggrega validate は正しさ(スキーマ、ピラー、参照の解決、extends、provider の入力種別の対応能力、そしてレンダリングを行うエンティティについては分離されたレンダリング)を検査し、aggrega lint は公開の慣例(命名、カテゴリディレクトリとの整合、アノテーションの接頭辞、バージョン更新の大きさ)を検査します。どちらも成果物は出力しません。「これは正しいか?」に答えるには validate を、「これはカタログの公開の規律に従っているか?」に答えるには lint を使用します。
aggrega build は単一エントリポイント原則(Single Entry Point Principle)に従います。Release が唯一のコンパイル入力です。aggrega build --release release.yaml は Release の aggregate: と manifest: のポインタを読み取ってトポロジーの残りの部分を特定し、dist/ の下に境界(boundary)ごとの出力を生成します。名前付き境界は宣言された directory: の下に、何も宣言していない場合は dist/boundaries/<boundary-name>/ の下にレンダリングされます。名前付き境界の代わりにトップレベルの components: を宣言する Release は、dist/ の直下にフラットにレンダリングされます。トポロジーが保持するすべての component はいずれかの境界に属していなければならず、どの境界にも保持されていない component があるとビルドは停止します。component が境界に到達するには、その境界の components: の下で(サブ Aggregates がフラット化された後に持つ id で)名前を指定されるか、その境界が aggregates: の下で取り込むサブ Aggregate の内部に置かれるかのいずれかです。どちらにも該当しない component は、Release が宣言するすべての境界の外でレンダリングされることになり、出力場所、sync wave、アノテーション、component ごとの infra: をどこからも取得できません。そのため、Release の境界設定が一度も適用されていない成果物を出力するのではなく、ビルドは停止してその component を名指しします。同じ関係は Release の側からも検査されます。トポロジーが保持していない component を名指しする境界エントリは何も設定しないため、これもビルドを停止させ、診断はそのエントリが指定した id を報告します。aggrega pull は Release を入力とする同じ形を共有します。aggrega inspect は任意のエンティティ(カタログ名、エンティティファイル、レジストリ参照、または Release)を受け取ります。aggrega push はカタログエンティティを受け取ります。aggrega validate と aggrega lint はカタログエンティティ、Release(--release 経由)、またはカタログ全体を受け付けます。aggrega serve は長時間実行されるプロセスとして動作します。グローバルフラグのページでは、サブコマンド全体に適用されるフラグを説明しています。
リリースがコマンド、フラグ、アシスタントツールについて何を変更しうるか、またパッチリリースが決して変更しないものは何かは、互換性 に記載されています。
コマンド別リファレンス
aggrega build— 主要なコンパイルコマンドです。Release ポインタを読み取り、それが参照する Aggregate と Manifest を解決し、境界ごとのコンパイル済みアーティファクトを出力します。aggrega inspect— 任意のエンティティを読みやすく表示します。対象は、名前で指定するカタログエンティティ、パスで指定するエンティティファイル、レジストリから直接読み取る公開済みエンティティ、または完全に解決された Release です。Release の場合、--ir-graphはその IR Graph を JSON として書き出し、--closureはその依存関係のクロージャを報告します。aggrega pull— Release の依存関係を解決し、すべての依存関係を固定する Release ごとのロックファイルを書き出します。カタログエンティティとソースアーティファクトをキャッシュします。aggrega push— カタログエンティティを OCI レジストリに公開します。プッシュ時に署名することもできます。aggrega sign— 公開済みの 1 つ以上のアーティファクトに署名し、各署名を OCI リファラーとして添付します。aggrega auth token— OIDC ID トークンを対話的に取得して stdout に出力します。一連のキーレス署名を 1 回の認証で行うためのものです。aggrega registry— ワークスペースが認識するレジストリとその署名信頼ポリシーを管理します。エントリの追加、一覧表示、削除を行い、registry updateで公開済みカタログメタデータの検索可能なローカルインデックスを構築します。aggrega search— 設定済みレジストリのローカルインデックスから、公開済みカタログエンティティとインストール可能な CLI プラグインを、フリーテキストのクエリと任意のファセットフィルタに一致するものとして検索します。aggrega validate— カタログ全体、Release の依存関係閉包(--release)、または 1 つのエンティティを対象に、正しさ(スキーマ、ピラー、参照解決、extends、入力種別の対応能力、分離レンダリング)をチェックします。aggrega lint— カタログ全体、Release の依存関係閉包(--release)、または 1 つのエンティティを対象に、公開の慣例をチェックします。--pre-publishを指定すると、レジストリを参照するバージョン更新ゲートが加わります。aggrega serve— IDE 統合のための、長時間稼働するサービスとしてのコンパイラのデーモン(stdin/stdout 上の JSON-RPC)です。aggrega version— CLI のバージョンを出力します。-o jsonを指定すると機械可読なオブジェクトを出力します。aggrega get-schema— エンティティ種別またはコントラクト種別の正規の JSON Schema を出力します。--listはすべての種別を列挙します。ファイルを記述する際の基準となる正式な形です。aggrega scaffold— エンティティ種別のスターター文書を、その種別のスキーマから導出して出力します。必須フィールドを含み、固定値は埋められ、値が必要な箇所にはすべてプレースホルダーが入ります。下書きの作成ではファイルは書き出さないため、必要な場所にリダイレクトしてください。--exampleを指定すると、代わりにドキュメントの実行可能な例の 1 つを新しいディレクトリに書き出します。--example --listで例の一覧を表示できます。aggrega mcp— 標準入出力または HTTP 上で Model Context Protocol サーバーを実行し、MCP 対応クライアントを Aggrega を理解するオーサリングアシスタントにします。Aggrega ファイルのオーサリングを参照してください。aggrega skills— AI アシスタントに Aggrega のインストール方法と使い方を教えるスキルを、そのアシスタントのスキルフォルダーにインストールします。1 つのプロジェクトを対象にするか、--globalを指定すると自分のすべてのプロジェクトが対象になります。aggrega cache— ディスク上のキャッシュを検査・保守します。キャッシュの内容の一覧表示、どのロックファイルからも参照されていないアーティファクトキャッシュのエントリの回収、コンパイル済みモジュールキャッシュのサイズ上限までの削減、またはすべてのキャッシュの消去を行います。aggrega config— Aggrega が読み取る設定を検査・管理します。適用される設定と、各設定をどのレイヤーが決定したかを表示し、動作する設定を初期作成し、ビルドに不可欠な設定をワークスペースに固定します。aggrega deprecate— 公開済みのアーティファクトに、署名付きの非推奨マーカーを付与します。aggrega edit-document— ドキュメントに範囲を限定した構造化編集を 1 つ適用し、変更しないバイトはすべてそのまま保持します。aggrega explain— コードが示す停止条件を説明します。aggrega import— 外部のソース記述を、Aggrega のオーサリングファイルの下書きに変換します。aggrega login— OCI レジストリに認証し、push、pull、lint --pre-publishが提示する認証情報を保存します。aggrega logout— 保存されているレジストリの認証情報を削除します。aggrega pin— エンティティの外部入力に対するコンテンツピンを、その横にあるentity.lockに記録します。aggrega plugin— CLI が解決できる Wasm プラグインを一覧表示し、ワークスペースのバインディングを追加または削除し、ゲストを公開する前に検査します。aggrega push-artifact— ドキュメントバンドルなどのスタンドアロンのデータアーティファクトを、OCI レジストリのdocs/名前空間の下に公開します。- 設定 — ある設定をどのファイルに書くか、そしてレイヤーがどのように組み合わされるかを説明します。まずここから始めてください。ほとんどのプロジェクトが必要とする 2 つのファイルから始まり、大規模なプロジェクトが利用する仕組みはその後に置かれています。
- グローバルフラグ — サブコマンド間で共有されるフラグ(ワークスペースのルート、グローバル設定ファイル、カラー出力とプレーンなアクセシブル出力、オフライン動作)です。オフラインは設定項目や環境変数としても指定できます。設定、設定スキーマ、環境変数を参照してください。
- ワークスペース境界 — ワークスペースの内側に何があるか、ワークスペースの外へ通じるシンボリックリンクが各種のパスに何をもたらすか、意図的に外側を参照するパス、そしてパスが拒否されたときの対処法を説明します。
| コマンド | 説明 |
|---|---|
aggrega auth | 署名 ID を管理します |
aggrega build | Aggregate と Release を、ワークスペースルートの dist/ 配下にプロバイダーネイティブなアーティファクトとしてコンパイルします |
aggrega cache | ディスク上のキャッシュを検査・保守します |
aggrega config | ワークスペース設定を検査・管理します |
aggrega deprecate | 公開済みアーティファクトに署名付きの非推奨マーカーを添付します |
aggrega edit-document | 文書に範囲を限定した構造化編集を 1 つ適用し、変更しないバイトはすべて保持します |
aggrega explain | コードが示す停止条件を説明します |
aggrega get-schema | エンティティ種別またはコントラクト種別の JSON Schema を出力します |
aggrega import | 外部のソース記述を Aggrega のオーサリングファイルの草案に変換します |
aggrega inspect | カタログエンティティを名前で、エンティティファイルをパスで、公開済みエンティティをレジストリ参照で検査します |
aggrega lint | カタログ、Release、または 1 つのエンティティを対象に、カタログ公開の慣例をチェックします |
aggrega login | OCI レジストリに認証し、認証情報を保存します |
aggrega logout | 保存済みのレジストリ認証情報を削除します |
aggrega mcp | AI アシスタント統合のため、標準入出力または HTTP 上で Model Context Protocol サーバーを実行します |
aggrega pin | エンティティの外部入力のコンテンツピンを、その隣の entity.lock に記録します |
aggrega plugin | CLI が解決できる Wasm プラグインを検査します |
aggrega pull | カタログとソースの依存関係をキャッシュに解決し、Release ごとのロックファイルを書き出します |
aggrega push | カタログエンティティをバンドルして OCI レジストリに公開します |
aggrega push-artifact | 単独のデータアーティファクト(ドキュメントバンドルなど)を OCI レジストリに公開します |
aggrega registry | レジストリとその署名信頼ポリシーを管理します |
aggrega scaffold | エンティティ種別のスターター文書の草案を作成するか、実行可能な例を新しいディレクトリに書き出します |
aggrega search | 設定済みレジストリのローカルインデックスを検索します |
aggrega serve | stdin/stdout 上の JSON-RPC 2.0 で、長時間稼働するサービスとしてのコンパイラとして実行します |
aggrega sign | 公開済みの 1 つ以上のアーティファクトに署名し、その署名を添付します |
aggrega skills | Aggrega のスキルを AI アシスタントにインストールします |
aggrega validate | カタログ、Release、または 1 つのエンティティを対象に正しさをチェックします |
aggrega version | aggrega CLI のバージョンを出力します |
位置引数と終了ステータス
すべてのコマンドは、使い道のない位置引数を拒否し、その呼び出しが有効であるかのように完了するのではなく、非ゼロの終了ステータスによってその拒否を報告します。この規則は、サブコマンドをまとめるためだけに存在するコマンドにも適用されます。そうしたコマンドでは、打ち間違えたサブコマンド名は認識されない位置引数として届きます。この場合、コマンドのヘルプが表示され、終了ステータスは非ゼロになるため、スクリプトから使われる場面でのタイプミスは、成功した実行と見なされることなく明確に失敗します。認識されないコマンドを指定して aggrega を呼び出した場合も同じように動作し、十分に近いコマンドがある場合は、さらに最も近いコマンドの名前を示します。
認識されないコマンドは、その名前の CLI プラグインを見つける方法も示します。 この回答は、aggrega registry update が構築し aggrega search が読み取る、デフォルトレジストリのローカルインデックスから得られます。そのため即座に返され、オンラインでもオフラインでも、打ち間違えた語がレジストリに送られることはありません。インデックスにその名前の CLI プラグインがある場合、メッセージはそれをインストールする aggrega plugin add cli <name> コマンドを示します。インデックスにない場合は、それを探す検索 aggrega search <name> --kind plugin --plugin-type cli を示します。まだインデックスが構築されていない場合は aggrega plugin add cli <name> を示します。このコマンドはその名前でレジストリ上のプラグインを検索し、公開されているものがなければ拒否します。どちらのコマンドも、必要に応じて名前をシェル向けに引用符で囲みます。
位置引数が意味を持つ場合は、各コマンド自身のリファレンスページに、受け付けるものが記載されています。インストールされた CLI プラグインは意図的な例外です。そのコマンドは引数の解析を自身に委ねるため、引数ベクター全体がプラグインに転送され、プラグインが自身の引数の唯一のパーサーとなります。そして、呼び出しが返すのはプラグイン自身の終了ステータスです。
進行状況と、コマンドがレジストリを待つ時間
待機中のコマンドは、何を待っているかを示します。 コマンドがレジストリ、ダウンロード、またはプラグインの初回コンパイルを待つ場合は常に、aggrega build や aggrega pull と同じように、その手順を標準エラー出力に表示します。端末では、手順名をスピナーとそれまでの経過時間とともに示す行が表示され、手順が完了するとチェックが付き、手順が失敗した場合はチェックが付かないままになります。その場で再描画できない端末や --plain 指定時には、手順が終わるたびにその所要時間とともに 1 行ずつ表示されます。標準エラー出力が端末でない場合は何も表示されず、いずれの場合もコマンドが標準出力に出力する内容は変わりません。手順は、コマンドが実際にそれを待っている間だけ表示されます。そのため、キャッシュから提供された実行では何も表示されず、プラグインのコンパイルは、キャッシュされたものではなく実際のコンパイルと言えるほど時間がかかった場合にのみ表示されます。
このように手順を表示するコマンドは、インストール済みのすべての CLI プラグインのコマンドのほかに、次のとおりです:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
サーバーを際限なく待つリクエストはありません。 リクエストは、完全に送信された後、サーバーが応答を開始するまで最大 30 秒待ち、すでに届きつつある応答の次の部分を最大 30 秒待ちます。リクエストをそれ以上待たせるサーバーは E0376 で拒否され、そのサーバーと待機時間が示されます。制限されるのは待機だけです。進み続けるダウンロードやアップロードは、必要なだけ時間がかかります。Recipe の source: が HTTPS で取得する Helm チャートには 2 つの待機のうち最初のものだけが適用され、その期限切れは E0376 ではなく、ネットワークライブラリ自身の言葉で報告されます。タイムアウト時にコマンドがもともと再試行するリクエスト — aggrega registry update 中の読み取りや、公開中の書き込み — は、拒否が報告される前に再試行されます。
レジストリのリポジトリ一覧全体の走査は 5 分以内に終わります。 レジストリの中には、一覧リクエストに応答する前に、保持しているすべてのリポジトリを集めるものがあります。そのため、一覧の各ページは 30 秒ではなく、走査が続きうる限り待たれます。5 分経っても終わらない一覧は停止され、E0377 で拒否されます。aggrega plugin add は、与えられた名前とまったく同じ名前のプラグインがない場合にのみ、その名前を含む名前のプラグインを探すために一覧を走査します。そのため、プラグインを正確な名前で指定すれば、走査を待つことはありません。
速度を落とすよう求めるレジストリに対しては、休みなく 5 分間求め続けるまで待機します。コマンドは、そのようなレジストリが求める時間だけ待機し、同時に送るリクエストを減らし、待機をほかの進捗と一緒に表示します。5 分間「速度を落として」以外に何も応答しないレジストリは E0378 で拒否されます。その方法は速度を落とすよう求めるレジストリで説明しています。
この 3 つの上限は固定されており、変更する設定はありません。
入力するパスとワークスペース境界
コマンドラインで入力するパス(--release、--catalog、--output-dir、検証・lint・ピン留め・公開の対象ファイル、--workspace-root)は、ワークスペースの内側か外側かにかかわらず、途中のリンクをたどって、その指し示す先で使われます。その後コマンドが自身の判断で読み書きするものは、誰が実行してもワークスペース内に制限されます。つまり、ワークスペースの設定ファイル、カタログドキュメント、Release の隣にあるドキュメント、Release のロックファイルを、ワークスペースの外へ出るリンク経由で読むことはなく、Release や Manifest がワークスペースの外へ書き出すパスをたどることもなく、出力、ロックファイル、キャッシュをそのようなリンク経由で書き込むこともありません。ワークスペースの外で指定したディレクトリも、その配下にあるものについては同様に制限され、ワークスペースの外で指定した Release は、それ自身のディレクトリ内のファイルにしか到達しません。aggrega edit-document は、入力したパスも制限される唯一のコマンドで、ワークスペースが持つドキュメントのみを編集します。ワークスペース境界では、この規則、意図的に外部へ到達するパス、および各拒否への対処法を説明しています。
カタログインデックスの検索
aggrega search [query] は、ワークスペースが認識しているレジストリ全体から公開済みのエンティティを検索します。省略可能な [query] は大文字と小文字を区別しない部分文字列で、各エンティティの名前と説明に対して照合されます。ファセットフィルタで結果を絞り込めます。
--kindは、1 つ以上のエンティティ種別(component、feature、recipe、featurerecipe、workload、plugin)に限定します。繰り返し指定でき、大文字と小文字を区別せず、複数の種別は OR で結合されます。-l/--selectorは、エンティティのカタログラベルで絞り込みます。カテゴリは専用のフラグではなくラベルです:-l component.aggrega.ai/category=datastore。--capabilityと--plugin-typeは、宣言されたケイパビリティまたはソケット種別でプラグインを絞り込みます。--capabilityは繰り返し指定でき、OR で結合されます。--registryは、ホストまたはわかりやすいエイリアスで指定した単一のレジストリに検索範囲を限定します。デフォルトでは、設定済みのすべてのレジストリが検索されます。--limitは結果の件数に上限を設けます。-o/--outputは出力形式を選択します:table(デフォルト、人間が読める形式)、json(機械可読な配列)、names(識別子のみ、1 行に 1 つ)。
検索は常にローカルインデックス、つまり aggrega registry update が構築・更新するオフラインのスナップショットを読み取ります。ネットワークには接続せず、必要に応じて何かを取得することもありません。インデックスが存在しない場合、コマンドは失敗し、先に aggrega registry update を実行するよう案内します。実行のたびに、レジストリごとの「最終更新」の鮮度を示す行が標準エラー出力に出力されるため、標準出力の json および names の出力はスクリプト処理向けにクリーンなまま保たれます。
シェル補完
aggrega completion <shell> は、bash、zsh、fish、powershell 用の補完スクリプトを stdout に出力します。スクリプトは実行した時点の CLI の実際のコマンドツリーから生成されるため、常にそれを生成したバイナリのコマンドとフラグを反映します。CLI が拡張されても再生成すべき静的ファイルはありません。
何もインストールせずに現在のセッションで補完を試すには、スクリプトを直接 source します。
source <(aggrega completion bash)補完を恒久的にインストールするには、シェルが起動時に読み込む場所にスクリプトを書き込みます。
bash
Bash の補完は bash-completion パッケージに依存します。まだ存在しない場合は、OS のパッケージマネージャーでインストールしてください。
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
シェルで補完がまだ有効になっていない場合は、一度だけ有効にします。
echo "autoload -U compinit; compinit" >> ~/.zshrc次に、fpath 上のディレクトリに補完スクリプトを書き込みます。
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
生成したスクリプトを PowerShell プロファイルに追記し、すべてのセッションで読み込まれるようにします。
aggrega completion powershell >> $PROFILEインストールした補完を有効にするには、新しいシェルを起動します。