aggrega plugin
CLI が解決できる Wasm プラグインを検査します
概要
aggrega plugin説明
Work with the WebAssembly plugins this CLI can resolve.
All of Aggrega's provider-specific and policy-specific behaviour lives in Wasmplugins rather than in the binary, so this is where you see which ones arereachable, add or remove a workspace binding, and check a guest before youpublish it.
Plugins reach the CLI two ways. Some are compiled into the binary and resolvewith no filesystem, cache or network access. The rest are workspace bindings in.aggrega-config.yaml, resolved through the plugin cascade. "aggrega plugin list"shows both groups together.
The subcommands below cover the whole life of a binding: list what is reachable,add and remove bindings, run a local guest export directly, sync themachine-owned records in a Plugin entity with its .wasm, and generate Plugincatalog entities from a guest's own metadata.サブコマンド
| コマンド | 説明 |
|---|---|
aggrega plugin add | レジストリで指定した種類のプラグインを見つけて追加します |
aggrega plugin gen-catalog | ゲストの describe() と作成済みのオーバーレイから Plugin カタログエンティティを生成します |
aggrega plugin list | CLI が解決できるプラグインを describe() メタデータとともに一覧表示します |
aggrega plugin remove | 指定した種類の設定済みプラグインを削除します |
aggrega plugin run-local | ローカルの .wasm ゲストを読み込み、そのエクスポートの 1 つを呼び出します |
aggrega plugin sync | エンティティファイル内のプラグインの機械所有レコード(ホスト関数、CLI コマンド)をその .wasm と同期します |
aggrega plugin add の説明
Find a plugin of the named type in the configured registry and add it to yourconfiguration.
Examples: aggrega plugin add cli moo # add the moo command aggrega plugin add cli moo:0.2.4 # a specific version aggrega plugin add governance rego --role render-verdict
Arguments: <type> The plugin socket to add for. One of: provider, governance, linter, importer, or cli. The governance type requires --role. <query> The plugin's name, optionally followed by :<version> to add that version rather than the latest published one. The name is looked up directly first. Where no plugin of the chosen type has that name, it is matched as a case-insensitive substring against the plugin names of that type, which reads the registry's whole catalog and must resolve to exactly one plugin — otherwise the command lists the candidates so you can narrow it. A query naming a version is never matched that way. The provider type takes no version.
What add writes depends on the type:
- A socket type (governance, linter, importer) pins the version the query names, or else the latest published version, and adds the bare plugin identity (<type>/<name>:<version>) to the plugins.<type> list. The latest is never taken from pre-release versions, so a plugin that publishes only those is added by naming one. A governance entry also records its --role, one of annotation-transform, label-transform, ir-verdict, or render-verdict. An importer the plugins.importer list already names keeps its one entry, moved to the pinned version with its place and what it carries under with. - The provider type adds a plugins.providers entry naming the plugin by its bare identity (provider/<name>) with no version; --capability names the capability the binding serves, preserving existing settings. The version is the one the Recipe pins, or else the highest available, and the lockfile records the one a pull chose. - The cli type fetches the plugin from the registry, verifies it, and caches its bytes, then pins it into the plugins.cli list as a top-level aggrega command — no separate pull step. Its resolved reference and the content digest of the verified bytes are recorded so the command runs those exact bytes, resolving from the local cache on later runs with no further network access. A cli plugin defaults to the global config, so its command is available in every workspace; --workspace pins it to this project instead. It needs no workspace: run outside one, its bytes are cached in the machine-wide cache rather than in the folder you ran it in. Its declared capabilities are confirmed before installing, and --accept-capabilities or --yes skips that prompt for non-interactive use.
A provider or socket attachment is written to a workspace's own configurationunless --global is passed, so outside a workspace it is refused before theregistry is reached; so is anything else that can be refused without it.
A provider or socket attachment is configuration you go on editing, so --dry-rundoes everything the plain command does except write: it hands back theconfiguration the write would have produced, creating and modifying nothing. Theanswer names the file that content is for — which matters here, because a--global attachment targets the config shared across every workspace. A callerthat keeps its own document model puts the content there, where it is visiblebefore it is saved and can be amended or undone. The registry is still searched,and for a socket type the version still resolved, since the returned documentcarries the identity a write would have written.
Under --dry-run standard output carries that content and nothing else, so it staysparseable; a version substitution is announced on standard error instead. The clitype does not accept --dry-run: what it records is the content digest of the bytesit verified, which is a record the machine maintains rather than content youedit.aggrega plugin add のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--accept-capabilities | false | 対話式プロンプトなしで cli プラグインが宣言したケイパビリティを受け入れます(cli タイプのみ) |
--capability | — | provider バインディングが提供するケイパビリティ(provider タイプでは必須で、provider タイプでのみ有効) |
--dry-run | false | 書き込み以外のすべてを行います。結果の設定を対象ファイル名とともにコンテンツとして返し、何も作成・変更しません。指定しない場合、アタッチメントは解決された設定ファイルに書き込まれます。cli タイプでは使用できません。 |
--global | false | すべてのワークスペースで共有されるグローバル設定にアタッチメントを書き込みます。 |
--role | — | governance アタッチメントのロール:annotation-transform、label-transform、ir-verdict、または render-verdict(governance タイプでは必須で、governance タイプでのみ有効) |
--workspace | false | このプロジェクトのワークスペース設定にアタッチメントを書き込みます。provider または socket のアタッチメントはデフォルトでここに書き込まれ、cli プラグインはデフォルトでグローバル設定に書き込まれます。 |
--yes | false | 非対話的な使用のために cli のケイパビリティ確認プロンプトをスキップします(cli タイプのみ) |
aggrega plugin gen-catalog の説明
Generate one Plugin entity per selected Wasm guest.
Each entity's contract fields — pluginType, abiVersion, capabilities, exports,and contract — are derived from the guest's describe() self-report, so theentity can never promise a capability the binary does not provide. The entity'sidentity (metadata.name), runtime limits, and provider block come from an authoredper-plugin overlay; the entity version is the guest's describe() self-reportversion. The plugin-level description, when the guest reports one, is emitted asmetadata.description and omitted cleanly when it does not.
Two selection modes:
--from-embedded generate an entity for every guest embedded in this binary. The overlay path is a directory; each overlay is matched to a guest by its metadata.name identity, and, where overlays in several socket directories (<socket>/<name>.yaml) declare one name, by the directory naming the guest's socket. --plugin <f.wasm> generate a single entity for one non-embedded guest. The overlay path is a single overlay file.
The output is written under <output-dir>/<pluginType>/<name>/<version>/plugin.yamland carries a generated-output banner. The leading pluginType segment keeps twosame-named plugins in different sockets apart, since a bare plugin name is uniqueonly within its own socket. Regenerating over unchanged inputs yieldsbyte-identical files.
A generated entity is a catalog document you own and go on editing, so --dry-rundoes everything gen-catalog does except write: it hands the content back, creatingand modifying nothing, and the answer names the file each document is for. Acaller that keeps its own document model — an editor, for instance — puts thecontent there, where it is visible before it is saved and can be amended orundone. Every other behaviour is the write's — the same guests are read and thesame overlays matched — so a selection gen-catalog would refuse is refused under--dry-run too. Without the flag the entities are written, because a caller at aterminal has nowhere better to put them.aggrega plugin gen-catalog のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--dry-run | false | 書き込み以外のすべてを行います。生成したエンティティをそれぞれの対象ファイル名とともにコンテンツとして返し、何も作成・変更しません。その他の動作はすべて書き込み時と同じであるため、書き込みで拒否される選択はここでも拒否されます。指定しない場合、エンティティは —output-dir 配下に書き込まれます。 |
--from-embedded | false | このバイナリに埋め込まれたすべてのゲストについてエンティティを生成します |
--output-dir | — | 生成したエンティティを書き込むディレクトリ(必須) |
--overlay | — | 作成済みのオーバーレイのディレクトリ(—from-embedded)またはファイル(—plugin)(必須) |
--plugin | — | このパスにある .wasm ゲストについて単一のエンティティを生成します |
aggrega plugin list の説明
List every Wasm plugin the CLI can see and, for each, its self-reporteddescribe() metadata.
Two groups are printed. Embedded built-ins are the provider and linter guestscompiled into the binary; they resolve with no filesystem, cache, or networkaccess. Configured plugins are the workspace bindings — the provider and linterbindings and the CLI-extension commands — resolved through the plugin cascade.Each plugin's type appears in the TYPE column, so a CLI-extension command(type cli) is legible alongside the socket plugins; a CLI plugin also carries astatus of its own — ready, unresolved, describe-failed, or digest-drift whenits bytes changed since it was pinned at install.
The default output is a scannable table with one row per plugin, showing itstype, name, served capabilities, and version. The output is read-only anddeterministic. A plugin that fails to resolve or describe is listed with itsfailure status rather than halting the whole listing.
With -o json, the output is a structured object carrying the full per-plugindetail — type, name, version, commit, capabilities, input kinds, boundaryassembly, exports, origin, readiness, and any resolve or describe error —grouped as embedded and configured. It is suitable for programmaticconsumption and documentation generation.aggrega plugin list のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--output, -o | table | 出力形式:table|json。 |
aggrega plugin remove の説明
Remove a configured plugin of the named type from a config file so it no longerparticipates.
The type is one of provider, governance, linter, importer, or cli — the sameset 'plugin add' accepts. The query identifies the entry to remove: the plugin'sshort name (matched against 'add's short name so remove is symmetric with add),its full pinned reference, or, for the provider type, the capability the bindingserves. A query that matches nothing halts and leaves the config untouched, so atypo never silently removes the wrong plugin.
A provider or socket attachment defaults to this project's workspace config; a clicommand defaults to the global config shared across every workspace. --global and--workspace force the file the removal targets, overriding the default.aggrega plugin remove のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--global | false | すべてのワークスペースで共有されるグローバル設定から削除します。 |
--workspace | false | このプロジェクトのワークスペース設定から削除します。provider または socket のアタッチメントはデフォルトでここが対象となり、cli コマンドはデフォルトでグローバル設定が対象となります。 |
aggrega plugin run-local の説明
Load a .wasm guest from a filesystem path, call one of its declaredexports with an optional payload, and write the guest's answer to stdout.
The guest is addressed directly by --plugin path; it is not resolved throughthe workspace plugin cascade. The export named by --export must be one theguest advertises in its describe() self-report, or the call is rejected beforethe guest runs.
The command has two forms. The artifact form takes no positional argument andloads the guest bare. The entity form takes a Plugin entity file as its onepositional argument: the entity is schema-validated, and its declaredmetadata.pluginType and export contract are cross-checked against the guest'sdescribe() before the guest runs. In both forms the guest bytes come from--plugin; the entity carries no artifact path.
The payload is supplied with --with, and it is always written as JSON. A valuebeginning with @ reads the payload bytes from a file (--with @input.json); anyother value is taken as a literal inline JSON payload (--with '{"k":1}'). When--with is omitted, the export receives the minimal empty JSON object {}. Theresolved payload is validated as JSON before the guest runs, so malformed inputis reported up front.
An export a socket calls with a payload reads it in a binary encoding ratherthan as JSON; a CLI plugin's cli_run export is the exception, and reads JSON.Which encoding an export reads is fixed by the socket that export serves, so noflag selects it: the resolved payload is converted into the encoding the namedexport reads before the guest is called. The conversion reads the payload'sshape from the export's name, so it covers each export a socket calls bydefault; an entry function an attachment or a pipeline step names under a nameof its own receives the payload as written. The authored payload stays JSONeither way.
The answer is converted the same way in reverse. An export a socket callsanswers in that binary encoding, so its answer is read as the export's outputshape and written to stdout as indented JSON; an answer that is not that shapeis reported as an error naming the export rather than printed. A cli_runexport's answer, and an entry function under a name of its own, are written tostdout exactly as the guest wrote them. When the guest exits non-zero, what itwrote is passed through unchanged.
In the artifact form, --type optionally names a plugin type the guest'sdescribe() self-report must agree with, or the load is rejected before theguest runs; when omitted, no type expectation is imposed. In the entity form--type is rejected, because the entity's metadata.pluginType supplies the type.
The guest's clean exit code becomes this command's exit status, so a failureinside the plugin is distinguishable from a failure of aggrega itself.aggrega plugin run-local のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--export | — | 呼び出す宣言済みのエクスポート |
--plugin | — | .wasm アーティファクトへのファイルシステムパス |
--type | — | ゲストの describe() の自己申告が一致すべきプラグインの種類 |
--with | — | エクスポートへのペイロード:インライン JSON、またはファイルから読み込む場合は @ |
aggrega plugin sync の説明
Sync a plugin's machine-owned records in a Plugin entity file with its .wasm.
Two records are not authored by hand: the set of host functions a plugin maycall, derived from the plugin's .wasm import section, and the top-level commands aCLI plugin contributes, read from the plugin's describe() self-report. Both areground truth in the binary. This command reads the .wasm, derives thehost-function set in canonical form and the command mirror in describe()-declaredorder, and aligns the entity's spec.runtime.hostFunctions and spec.commands withthem — creating the runtime block when the file has none. Only those blockschange; every comment, blank line, and other field is preserved byte-for-byte. Aplugin that imports no host functions or contributes no commands records anexplicit empty list, so each field is always present and reviewable.
The write is idempotent: re-running when the records already match the .wasmleaves the file untouched. Commit the result; publish (aggrega push) then onlyverifies the committed records against the .wasm and refuses to publish a filewhose records are out of sync with its binary.aggrega plugin sync のフラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--plugin | — | プラグインの .wasm アーティファクトへのパス。そのインポートと describe() によって、記録されるホスト関数とコマンドが決まります |
importer エントリの役割
aggrega plugin add importer は、プラグインの識別子と、そのプラグインについて公開されている最新バージョン、または <name>:<version> として指定したバージョン(importer/<name>:<version>)を plugins.importer リストに書き込みます。このエントリは、指定したインポーターをアタッチします。そのインポーターが提示するフォーマットを求めるインポートは、カタログ内の他のインポーターが同じフォーマットを提示している場合でも、そのバージョンのそのインポーターを実行します。また、エントリが with の下に持つ内容を受け取るのは、そのインポーターだけです。エントリの詳細はソースをドラフトに変換するインポーターで説明しています。
インポーターは 1 つのエントリによってアタッチされるため、書き込み対象のファイルの plugins.importer リストがすでに指定しているインポーターを追加しても(どのバージョンであっても、範囲指定であっても)、2 つ目のエントリは追加されません。代わりに、コマンドはそのエントリを解決したバージョンに移します。エントリはリスト内の位置と、with の下に持つすべての内容を保持します。エントリがすでに指定しているバージョンでインポーターを追加した場合、エントリはそのまま変更されません。
CLI プラグインのコマンドとそのフラグ
aggrega は起動するたびに、設定された cli プラグインが提供するコマンドごとに 1 つのコマンドを追加します。コマンドとそのフラグは、プラグインの describe() の自己報告から読み取ります。describe キャッシュがプラグインの固定されたダイジェストを保持している場合はキャッシュから、そうでない場合はプラグインを describe して読み取ります。宣言された各フラグはそのコマンド上で宣言されるため、aggrega help <command> は組み込みコマンドのフラグと同じようにそれを一覧表示します。ただし、プラグインは引数を解析されないまま受け取り、自身のフラグを自分で読み取ります。
固定されたダイジェストは、設定の plugins.cli リストでプラグインの参照の隣に置かれ、sha256: の後に 64 桁の小文字の 16 進数が続く形で書かれます。これは aggrega plugin add cli が記録する表記です。sha256: 接頭辞のない 16 進数のみなど、それ以外の表記のダイジェストは、設定ファイルの読み込み時にファイルとエントリを示して拒否されます。修正されるまで、設定されたどのプラグインのコマンドも追加されず、標準エラーへの警告がその拒否を伝えます。
aggrega は、プラグインのコマンドを追加する前に、各コマンドが宣言するすべてのフラグを検査します。宣言が検査に失敗したプラグインはスキップされます。そのコマンドはどれも追加されず、標準エラーへの 1 つの警告がプラグイン、コマンド、フラグ、およびその問題点を示し、組み込みか別のプラグインからかを問わず、他のすべてのコマンドは通常どおり実行されます。
warning: CLI plugin "oci://hub.aggrega.ai/plugin/cli/greet:1.2.0" was not added as a command: its command "greet" declares the flag "--verbose" with the shorthand "vv"; a shorthand is a single ASCII letter or digitフラグの宣言は、次の場合に検査を通過します。
- フラグに名前があり、同じコマンドの他のどのフラグもその名前を持たない。
- 短縮形がある場合、それが 1 文字の ASCII 英字または数字であり、同じコマンドの他のどのフラグも使用していない。
- 名前も短縮形も、すべての
aggregaコマンドが既に持つフラグ(--help、-h、およびグローバルフラグ)を再利用していない。 - 型を宣言する場合、それが
string、bool、intのいずれかである。型のないフラグは文字列フラグになる。 - デフォルト値を宣言する場合、それがその型の値である。
このスキップは、宣言が検査を通過するバージョンのプラグインを設定が固定するまで、呼び出しのたびに警告とともに繰り返されます。フラグの宣言が持つフィールドについては、Plugin エンティティのページの spec.commands で説明しています。
エンティティの生成とレコードの同期:2 つの異なる種類の操作
これらのサブコマンドのうち 2 つはファイルを生成しますが、生成するものの種類は同じではありません。
plugin gen-catalog — 生成されたエンティティは利用者が編集するものです
aggrega plugin gen-catalog は Plugin のカタログエンティティを生成します。エンティティはカタログのドキュメントです。ファイルとして保存し、レビューし、カタログの他の部分とともに編集を続けます。利用者が所有するコンテンツであるため、コマンドはそれをディスクに書き込む代わりに利用者へ渡すことができます。
--dry-run は、書き込み以外のすべてを gen-catalog と同じように行います。生成されたエンティティをコンテンツとして返し(ファイルもディレクトリも作成されません)、応答内の各ドキュメントは対象となるファイルを示すため、呼び出し側はそれぞれの配置先を把握できます。エディタのように独自のドキュメントモデルを持つ呼び出し側は、コンテンツをそこに配置します。そこでは保存前に内容を確認し、修正や取り消しができます。このフラグがない場合、エンティティは --output-dir の下に書き込まれます。ターミナルの呼び出し側には、それ以上に適した置き場所がないためです。
返される内容と書き込まれるバイト列は同じ内容です。--dry-run は書き込みが生成したはずのものを返すのであり、別途組み立てられたプレビューを返すのではありません。その他のすべての動作も書き込み時と同じです。同じゲストが読み込まれ、同じオーバーレイが照合されます。また、どちらの場合も --output-dir が必須です。返される各ドキュメントは、それが対象とするファイルを依然として指定しており、そのパスはこのフラグから組み立てられるためです。
すべてのエンティティは、いずれかが渡される前に組み立てと検証が行われるため、1 回の実行ではセット全体が生成されるか、何も生成されないかのどちらかです。生成を停止させるオーバーレイ(存在しないもの、またはマージ対象のゲストと ID が一致しないもの)があっても、後片付けが必要な中途半端な出力は残りません。
plugin sync — マシン所有のレコードはコンパイラのものです
aggrega plugin sync は、プラグインのマシン所有のレコードをそのモジュールと一致させます。対象は、モジュールのインポートセクションから導出されるホスト関数セットと、プラグイン自身のセルフレポートから読み取られるコマンドミラーです。どちらも誰かが選ぶ値ではなく、バイナリ内にある実際の事実です。
このコマンドは常に書き込みを行い、--dry-run は提供しません。利用者が作成したエンティティファイルに書き込む場合でも同様です。境界はファイルではなくコンテンツで引かれています。コンパイラが自身について管理するレコードは利用者が編集するものではないため、反映前にレビューすべきものはありません。周囲のドキュメントはバイト単位でそのまま保たれ、変更されるのはそれらのブロックだけです。