aggrega plugin
Die Wasm-Plugins inspizieren, die die CLI auflösen kann
Übersicht
aggrega pluginBeschreibung
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.Unterbefehle
| Befehl | Beschreibung |
|---|---|
aggrega plugin add | Ein Plugin des genannten Typs in der Registry finden und hinzufügen |
aggrega plugin gen-catalog | Plugin-Katalogentitäten aus dem describe() des Guests plus einem verfassten Overlay generieren |
aggrega plugin list | Die Plugins, die die CLI auflösen kann, mit ihren describe()-Metadaten auflisten |
aggrega plugin remove | Ein konfiguriertes Plugin des genannten Typs entfernen |
aggrega plugin run-local | Einen lokalen .wasm-Guest laden und einen seiner Exporte aufrufen |
aggrega plugin sync | Die maschinengepflegten Datensätze eines Plugins (Host-Funktionen, CLI-Befehle) in seiner Entitätsdatei mit seiner .wasm abgleichen |
Beschreibung von 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.Flags von aggrega plugin add
| Flag | Standard | Beschreibung |
|---|---|---|
--accept-capabilities | false | Die deklarierten Capabilities eines CLI-Plugins ohne die interaktive Abfrage akzeptieren (nur Typ cli) |
--capability | — | Capability, die die Provider-Bindung bedient (erforderlich für und nur gültig mit dem Typ provider) |
--dry-run | false | Alles außer Schreiben ausführen: die resultierende Konfiguration als Inhalt zurückgeben, unter Nennung der Datei, für die sie bestimmt ist, und nichts erstellen oder ändern. Ohne dieses Flag wird die Anbindung in die aufgelöste Konfigurationsdatei geschrieben. Mit dem Typ cli nicht akzeptiert. |
--global | false | Die Anbindung in die globale Konfiguration schreiben, die von allen Workspaces gemeinsam genutzt wird. |
--role | — | Rolle der Governance-Anbindung: annotation-transform, label-transform, ir-verdict oder render-verdict (erforderlich für und nur gültig mit dem Typ governance) |
--workspace | false | Die Anbindung in die Workspace-Konfiguration dieses Projekts schreiben. Eine Provider- oder Socket-Anbindung landet standardmäßig hier; ein CLI-Plugin standardmäßig in der globalen Konfiguration. |
--yes | false | Die Bestätigungsabfrage für CLI-Capabilities bei nicht interaktiver Verwendung überspringen (nur Typ cli) |
Beschreibung von 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.Flags von aggrega plugin gen-catalog
| Flag | Standard | Beschreibung |
|---|---|---|
--dry-run | false | Alles außer Schreiben ausführen: die generierten Entitäten als Inhalt zurückgeben, unter Nennung der Datei, für die jede bestimmt ist, und nichts erstellen oder ändern. Jedes andere Verhalten ist das des Schreibens, sodass eine Auswahl, die das Schreiben ablehnen würde, auch hier abgelehnt wird. Ohne dieses Flag werden die Entitäten unter —output-dir geschrieben. |
--from-embedded | false | für jeden in diese Binärdatei eingebetteten Guest eine Entität generieren |
--output-dir | — | Verzeichnis, unter das die generierten Entitäten geschrieben werden (erforderlich) |
--overlay | — | Verzeichnis (—from-embedded) oder Datei (—plugin) des verfassten Overlays (erforderlich) |
--plugin | — | eine einzelne Entität für den .wasm-Guest unter diesem Pfad generieren |
Beschreibung von 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.Flags von aggrega plugin list
| Flag | Standard | Beschreibung |
|---|---|---|
--output, -o | table | Ausgabeformat: table|json. |
Beschreibung von 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.Flags von aggrega plugin remove
| Flag | Standard | Beschreibung |
|---|---|---|
--global | false | Aus der globalen Konfiguration entfernen, die von allen Workspaces gemeinsam genutzt wird. |
--workspace | false | Aus der Workspace-Konfiguration dieses Projekts entfernen. Eine Provider- oder Socket-Anbindung landet standardmäßig hier; ein CLI-Befehl standardmäßig in der globalen Konfiguration. |
Beschreibung von 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.Flags von aggrega plugin run-local
| Flag | Standard | Beschreibung |
|---|---|---|
--export | — | der deklarierte Export, der aufgerufen werden soll |
--plugin | — | Dateisystempfad zum .wasm-Artefakt |
--type | — | der Plugin-Typ, dem die describe()-Selbstauskunft des Guests entsprechen muss |
--with | — | Nutzdaten für den Export: Inline-JSON oder @ |
Beschreibung von 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.Flags von aggrega plugin sync
| Flag | Standard | Beschreibung |
|---|---|---|
--plugin | — | Pfad zum .wasm-Artefakt des Plugins, dessen Importe und describe() die verzeichneten Host-Funktionen und Befehle bestimmen |
Was ein Importer-Eintrag bewirkt
aggrega plugin add importer schreibt die Identität des Plugins und die neueste dafür veröffentlichte Version oder die Version, die Sie als <name>:<version> angeben — importer/<name>:<version> — in die Liste plugins.importer. Dieser Eintrag bindet den Importer an, den er benennt: Ein Import, der ein Format anfordert, das der Importer ankündigt, führt diesen Importer in dieser Version aus, auch wenn andere Importer in Ihrem Katalog das Format ebenfalls ankündigen, und nur diesem Importer wird übergeben, was der Eintrag unter with enthält. Welcher Importer eine Quelle in Entwürfe verwandelt beschreibt den Eintrag vollständig.
Ein Importer wird durch einen Eintrag angebunden, daher fügt das Hinzufügen eines Importers, den die Liste plugins.importer der zu schreibenden Datei bereits benennt — in beliebiger Version oder über einen Bereich —, keinen zweiten Eintrag hinzu. Der Befehl verschiebt diesen Eintrag stattdessen auf die aufgelöste Version: Der Eintrag behält seinen Platz in der Liste und alles, was er unter with enthält. Das Hinzufügen eines Importers in der Version, die sein Eintrag bereits benennt, lässt den Eintrag unverändert.
Die Befehle eines CLI-Plugins und ihre Flags
Bei jedem Start fügt aggrega für jeden Befehl, den ein konfiguriertes cli-Plugin beiträgt, einen Befehl hinzu und liest die Befehle und ihre Flags aus der describe()-Selbstauskunft des Plugins — aus dem Describe-Cache, wenn dieser den gepinnten Digest des Plugins enthält, und andernfalls durch Abfragen des Plugins. Jedes deklarierte Flag wird an seinem Befehl deklariert, sodass aggrega help <command> es so auflistet, wie es die Flags eines eingebauten Befehls auflistet; das Plugin erhält seine Argumente trotzdem ungeparst und liest seine eigenen Flags selbst.
Der gepinnte Digest steht neben der Referenz des Plugins in der Liste plugins.cli der Konfiguration, geschrieben als sha256: gefolgt von 64 hexadezimalen Kleinbuchstaben-Ziffern — die Schreibweise, die aggrega plugin add cli verzeichnet. Ein anders geschriebener Digest, etwa reines Hexadezimal ohne das Präfix sha256:, wird beim Laden der Konfigurationsdatei unter Nennung der Datei und des Eintrags abgelehnt; bis er korrigiert ist, wird kein Befehl eines konfigurierten Plugins hinzugefügt, und eine Warnung auf der Standardfehlerausgabe enthält die Ablehnung.
Bevor aggrega einen der Befehle eines Plugins hinzufügt, prüft es jedes Flag, das jeder davon deklariert. Ein Plugin, dessen Deklarationen die Prüfung nicht bestehen, wird übersprungen: Keiner seiner Befehle wird hinzugefügt, eine Warnung auf der Standardfehlerausgabe benennt das Plugin, den Befehl, das Flag und was daran falsch ist, und jeder andere Befehl — eingebaut oder von einem anderen Plugin — läuft wie gewohnt:
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 digitEine Flag-Deklaration besteht die Prüfung, wenn:
- das Flag einen Namen hat und kein anderes Flag desselben Befehls ihn hat;
- seine Kurzform, falls es eine hat, ein einzelner ASCII-Buchstabe oder eine einzelne ASCII-Ziffer ist, die kein anderes Flag desselben Befehls verwendet;
- weder sein Name noch seine Kurzform ein Flag wiederverwendet, das jeder
aggrega-Befehl bereits hat —--help,-hund die globalen Flags; - sein Typ, falls es einen deklariert,
string,booloderintist — ein Flag ohne Typ ist ein String-Flag; - sein Standardwert, falls es einen deklariert, ein Wert seines Typs ist.
Das Überspringen wiederholt sich samt Warnung bei jedem Aufruf, bis die Konfiguration eine Version des Plugins pinnt, deren Deklarationen die Prüfung bestehen. Die Felder einer Flag-Deklaration sind unter spec.commands auf der Seite der Entität Plugin beschrieben.
Entitäten generieren und Datensätze abgleichen: zwei verschiedene Arten von Handlung
Zwei dieser Unterbefehle erzeugen eine Datei, und was sie erzeugen, ist nicht dieselbe Art von Sache.
plugin gen-catalog — generierte Entitäten gehören Ihnen und dürfen bearbeitet werden
aggrega plugin gen-catalog erzeugt Plugin-Katalogentitäten. Eine Entität ist ein Katalogdokument: Sie legen sie ab, prüfen sie und bearbeiten sie zusammen mit dem Rest Ihres Katalogs weiter. Da es Inhalt ist, der Ihnen gehört, kann der Befehl ihn Ihnen übergeben, statt ihn auf die Festplatte zu schreiben.
--dry-run tut alles, was gen-catalog tut, außer zu schreiben. Es gibt die generierten Entitäten als Inhalt zurück — keine Datei wird erstellt, kein Verzeichnis angelegt — und jedes Dokument in der Antwort benennt die Datei, für die es bestimmt ist, sodass ein Aufrufer weiß, wohin jedes gehört. Ein Aufrufer mit einem eigenen Dokumentmodell, etwa ein Editor, legt den Inhalt dort ab, wo Sie ihn sehen, bevor er gespeichert wird, und ihn ändern oder rückgängig machen können. Ohne das Flag werden die Entitäten unter --output-dir geschrieben, denn ein Aufrufer an einem Terminal hat keinen besseren Ort dafür.
Der zurückgegebene Inhalt und die geschriebenen Bytes sind derselbe Inhalt: --dry-run gibt zurück, was das Schreiben erzeugt hätte, keine separat zusammengestellte Vorschau. Auch jedes andere Verhalten ist das des Schreibens — dieselben Guests werden gelesen, dieselben Overlays zugeordnet, und --output-dir ist in beiden Fällen erforderlich, weil jedes zurückgegebene Dokument dennoch die Datei benennt, für die es bestimmt ist, und dieser Pfad daraus zusammengesetzt wird.
Jede Entität wird zusammengesetzt und validiert, bevor irgendeine davon ausgeliefert wird, sodass ein Lauf entweder die ganze Menge oder nichts erzeugt. Ein Overlay, das die Generierung anhält — eines, das fehlt, oder dessen Identität nicht zu dem Guest passt, mit dem es zusammengeführt wird —, hinterlässt keine teilweise geschriebene Ausgabe, die aufgeräumt werden müsste.
plugin sync — maschinengepflegte Datensätze gehören dem Compiler
aggrega plugin sync bringt die maschinengepflegten Datensätze eines Plugins mit seinem Modul in Einklang: die aus dem Import-Abschnitt des Moduls abgeleitete Menge der Host-Funktionen und das aus der eigenen Selbstauskunft des Plugins gelesene Abbild der Befehle. Beides ist Grundwahrheit in der Binärdatei statt von irgendjemandem gewählter Werte.
Es schreibt immer und bietet kein --dry-run. Das gilt, obwohl es in eine von Ihnen verfasste Entitätsdatei schreibt — die Grenze wird am Inhalt gezogen, nicht an der Datei. Datensätze, die der Compiler über sich selbst pflegt, sind nicht von Ihnen zu bearbeiten, daher gibt es nichts zu prüfen, bevor sie geschrieben werden; das umgebende Dokument bleibt Byte für Byte unberührt, und nur diese Blöcke ändern sich.