グローバルフラグ
すべての aggrega サブコマンドで使用できるフラグです。
--workspace-root <path>
<path> をワークスペースルートとして使用し、探索を完全に省略します。このフラグを省略した場合、aggrega はカレントディレクトリから上位へたどってルートを探索します。その探索で何も見つからず、かつコマンドがその Release またはドキュメントを絶対パスで指定している場合は、代わりにそのファイルのフォルダから上位へたどります。何がルートの基準となるか、その順序、およびどのコマンドがそのようなファイルを指定するかについては、設定を参照してください。
AGGREGA_WORKSPACE_ROOT は対応する環境変数です。--workspace-root が指定されていない場合、この変数がルートを与えます。両方が設定されている場合はフラグが優先されます。
ルートは、どこで指定されてもルートであり、サーバーも例外ではありません。独自のワークスペースを指定しない aggrega mcp へのリクエストはそのルート内で応答され、その上位は探索されません。既存のフォルダではないルート(何も指していないパス、またはファイルを指すパス)は、そのワークスペースを読み込むすべてのコマンドによって、コマンドが他の処理を行う前に拒否されます。aggrega serve と aggrega mcp のリスナーはそのようなルートでは起動を拒否し、標準入出力経由の aggrega mcp はそれでも起動しますが、そのワークスペース内で動作するすべての呼び出しに対してこの拒否を返します。拒否メッセージには、ルートを与えたのが --workspace-root と AGGREGA_WORKSPACE_ROOT のどちらであるかが、指定されたとおりの値とともに示されます。aggrega version のようにワークスペースを読み込まないコマンドは、ルートも読み込まないため、それを理由に拒否されることはありません。
どちらも指定されず、探索でも基準となるものが見つからない場合は、コマンドを実行したフォルダがルートになり、ワークスペースを読み込むコマンドはその旨を標準エラーに 1 行で出力し、そのフォルダとこのフラグを示します。詳しくは設定を参照してください。そこでは、このようなフォルダではアーティファクトキャッシュに何も書き込まれない理由も説明しています。
グローバル設定ファイル
--config <path> は、1 回の呼び出しに対してグローバル設定ファイルを明示的に指定します。これは AGGREGA_CONFIG 環境変数より優先され、その環境変数はさらにデフォルトの場所より優先されます。どちらも意図的にファイルを指定するものであるため、存在しないパスは暗黙のフォールバックではなく明示的なエラーになります。AGGREGA_* の設定変数とは異なり、どちらも個々の設定を上書きするものではなく、どのファイルを適用するかを選択します。どのファイルに解決された場合でも、プロジェクト自身の設定ファイルは引き続きその上に重ねられます。解決順序とそのファイルに記述する内容については Configuration を参照してください。
--config と環境変数 AGGREGA_CONFIG は、読み込み元だけでなく書き込み先も選択します。--config <path> を付けて実行したコマンドは、そのファイルから設定を読み込み、変更も同じファイルに適用します。そのため、あるコマンドが書き込んだ内容は、同じ実行形式の次のコマンドがそのまま読み戻します。
設定を変更するコマンドは、設定の性質に応じて書き込むファイルを選択します。マシン全体のツール設定(レジストリ)はデフォルトでグローバルファイルに、ビルドに関与する設定(provider のバインディングや、governance/linter/importer のソケット接続)はデフォルトでコミットされたプロジェクトファイルに書き込まれます。これを上書きするには --global または --workspace を指定します。コマンドは書き込み先を出力します。
新しいマシンでグローバル設定を初期化するには(レジストリとその署名信頼ポリシーを登録し、YAML を手で編集せずに署名済みアーティファクトを pull・検証できるようにするには)、aggrega config init を実行します。現在適用されている設定を確認し、--origin を付けて各設定をどのレイヤーが決定したかを確認するには、aggrega config show を実行します。
--offline
この 1 回の実行について、すべてのネットワークアクセスを拒否します。
オフラインは 1 つのコマンドのモードではなくワークスペースの姿勢であり、このフラグ、AGGREGA_OFFLINE、設定ファイルのトップレベルの offline キーという 3 か所から指定できます。これらは同じ意味を持ち、通常の順序で優先されます。フラグは変数より優先され、変数はファイルより優先されます。
オフにする方向も、オンにする方向と同じくこのフラグの役割です。 --offline=false は、コミットされた設定ファイルやエクスポートされた変数がこの姿勢をオンにしている場合に、1 つのコマンドについてネットワークを許可します。これは、そのファイルを自分で編集できない場合に重要です。.aggrega-config.yaml に offline: true が記述されたプロジェクトでは、クローンしたすべての人に対して公開が拒否されます。--offline=false を渡すことが、コミットもエクスポートされた変数も必要としない唯一の解決策です。
拒否されるものと拒否されないもの
境界は、入力されたコマンドではなく、その処理が何を必要とするかによって決まります。
レジストリにアクセスしなければ成り立たないため、拒否されるもの:
--upgrade(どこに現れる場合でも)。これはすべての依存関係を再解決し、それぞれをレジストリが現在提供している最も高いバージョンへ引き上げます。「利用可能な最新」とは、レジストリが今この時点で提供しているものについての主張です。これをウォームキャッシュに対して実行すると、たまたまキャッシュされていたものを固定しながら最新へ引き上げたと報告することになり、停止するよりも悪い結果になります。- 処理そのものがネットワークの往復であるコマンド:
aggrega push、aggrega push-artifact、aggrega registry update。これらはエンティティを読み込んだりリポジトリを走査したりする前にその旨を伝えます。また、拒否の際には 3 か所のうちどこがこの姿勢を設定したかを示すため、フラグを入力していない人でもどこを確認すればよいかがわかります。
マシンがすでに要求を満たせる可能性があるため、拒否されないもの:
- 通常の
aggrega pullとaggrega build --auto-pull。どちらもすでに記録されているピンを尊重し、ピンのないものだけを解決します。そのため、すべての参照がキャッシュされているかcatalog_dirsのカタログに存在するワークスペースは、外部に一切アクセスせずに完了します。そのような実行で本当に何かを取得する必要がある場合は、その時点で拒否され、満たせなかった参照が示されます。 - 記入済みのロックファイルに対する
aggrega build。これはクロージャ全体をキャッシュから読み込みます。唯一のアクセスは修復です。ピン留めされた外部入力のストア内のコピーが失われている場合、その入力はロックファイルにすでに記録されているダイジェストによって再取得されます。この姿勢のもとではそのための通信手段すらないため、失われたコピーは代わりにビルドを停止させ、その姿勢を示します。 --dry-runによる公開。その動作は、何を公開するかを報告するだけで何も呼び出さないことに尽きます。そのため、これはこの姿勢と矛盾するものではなく、オフラインでも安全な公開の形式です。
カタログとアーティファクトのローカルコピーを保持するエアギャップ環境のマシンこそ、この区分によって動作し続けることを意図したケースです。そのようなワークスペースはオフラインですが、行うことのほとんどは依然として満たすことができます。
設定の優先順位
フラグはすべてに優先します。環境変数、設定ファイル、組み込みのデフォルトのいずれよりも優先されます。完全な優先順位は Configuration に、AGGREGA_ プレフィックス付きの変数の一覧は environment-variables.md に記載されています。
aggrega config show --origin は、各設定をどのレイヤーが決定したかを報告し、入力したフラグはフラグとして報告されます。そのため、拒否のメッセージが想定外のレイヤーを示した場合は、このコマンドで確認できます。
関連項目
- configuration.md — 各設定をどのファイルに記述するか、および優先順位モデルの全体。
- environment-variables.md —
AGGREGA_*変数の完全なリファレンス。 - aggrega-serve.md — デーモンは同じルート探索の経路でワークスペースを解決します。
| フラグ | デフォルト | 説明 |
|---|---|---|
--config | — | グローバル設定ファイルへのパス。AGGREGA_CONFIG 環境変数とデフォルトの場所を上書きします。ワークスペースツリー内の設定ファイルは引き続きその上に重ねられます |
--no-color | false | すべての出力で ANSI カラーを無効にします。NO_COLOR 環境変数でも有効になります |
--offline | false | この 1 回の実行に限り、すべてのネットワークアクセスを拒否します。設定を編集せずにオフラインの状態を有効にするものです。設定ファイルまたは AGGREGA_OFFLINE ですでに有効になっている場合に 1 回の実行だけ無効にするには、—offline=false を渡します。拒否されるのは、レジストリなしでは成り立たないものです。すなわち、各依存関係をレジストリが現在提供する最高バージョンに引き上げることだけを役割とする —upgrade と、処理そのものがネットワークの往復である push、push-artifact、registry update の各コマンドです。引き続き実行されるのは、マシンがすでに満たせるものです。すなわち、内容の揃ったロックファイルに対するビルド、すでにキャッシュされているかローカルカタログに存在する参照に対する —auto-pull、そして公開する内容を報告するだけで何も呼び出さないドライランです |
--plain | false | アクセシブルモード:カラーを無効にし、端末上であってもスピナーのアニメーションやカーソルの再描画を行わない、プレーンで静的な進捗行を表示します。スクリーンリーダー向けです |
--workspace-root | — | ワークスペースルートとして使用する絶対パス(探索をスキップします) |