aggrega plugin
Inspecter les plugins Wasm que la CLI peut résoudre
Synopsis
aggrega pluginDescription
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.Sous-commandes
| Commande | Description |
|---|---|
aggrega plugin add | Trouver un plugin du type indiqué dans le registry et l’ajouter |
aggrega plugin gen-catalog | Générer des entités Plugin du catalogue à partir du describe() du guest et d’un overlay rédigé |
aggrega plugin list | Lister les plugins que la CLI peut résoudre avec leurs métadonnées describe() |
aggrega plugin remove | Supprimer un plugin configuré du type indiqué |
aggrega plugin run-local | Charger un guest .wasm local et appeler l’un de ses exports |
aggrega plugin sync | Synchroniser les enregistrements gérés par la machine d’un plugin (fonctions hôtes, commandes CLI) dans son fichier d’entité avec son .wasm |
Description de 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 de aggrega plugin add
| Option | Par défaut | Description |
|---|---|---|
--accept-capabilities | false | Accepter les capabilities déclarées d’un plugin cli sans l’invite interactive (type cli uniquement) |
--capability | — | Capability que sert la liaison de provider (obligatoire pour le type provider, et valide uniquement avec lui) |
--dry-run | false | Tout faire sauf écrire : renvoyer la configuration résultante sous forme de contenu, en nommant le fichier auquel elle est destinée, et ne rien créer ni modifier. Sans ce flag, l’attachement est écrit dans le fichier de configuration résolu. Non accepté avec le type cli. |
--global | false | Écrire l’attachement dans la configuration globale partagée par tous les workspaces. |
--role | — | Rôle de l’attachement de gouvernance : annotation-transform, label-transform, ir-verdict ou render-verdict (obligatoire pour le type governance, et valide uniquement avec lui) |
--workspace | false | Écrire l’attachement dans la configuration du workspace de ce projet. Un attachement provider ou socket va ici par défaut ; un plugin cli va par défaut dans la configuration globale. |
--yes | false | Ignorer l’invite de confirmation des capabilities cli pour un usage non interactif (type cli uniquement) |
Description de 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 de aggrega plugin gen-catalog
| Option | Par défaut | Description |
|---|---|---|
--dry-run | false | Tout faire sauf écrire : renvoyer les entités générées sous forme de contenu, en nommant le fichier auquel chacune est destinée, et ne rien créer ni modifier. Tout autre comportement est celui de l’écriture, de sorte qu’une sélection que l’écriture refuserait est refusée ici aussi. Sans ce flag, les entités sont écrites sous —output-dir. |
--from-embedded | false | générer une entité pour chaque guest intégré à ce binaire |
--output-dir | — | répertoire sous lequel les entités générées sont écrites (obligatoire) |
--overlay | — | répertoire (—from-embedded) ou fichier (—plugin) de l’overlay rédigé (obligatoire) |
--plugin | — | générer une seule entité pour le guest .wasm situé à ce chemin |
Description de 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 de aggrega plugin list
| Option | Par défaut | Description |
|---|---|---|
--output, -o | table | Format de sortie : table|json. |
Description de 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 de aggrega plugin remove
| Option | Par défaut | Description |
|---|---|---|
--global | false | Supprimer de la configuration globale partagée par tous les workspaces. |
--workspace | false | Supprimer de la configuration du workspace de ce projet. Un attachement provider ou socket va ici par défaut ; une commande cli va par défaut dans la configuration globale. |
Description de 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 de aggrega plugin run-local
| Option | Par défaut | Description |
|---|---|---|
--export | — | l’export déclaré à appeler |
--plugin | — | chemin du système de fichiers vers l’artefact .wasm |
--type | — | le type de plugin auquel doit correspondre l’auto-description describe() du guest |
--with | — | payload de l’export : JSON inline, ou @ |
Description de 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 de aggrega plugin sync
| Option | Par défaut | Description |
|---|---|---|
--plugin | — | Chemin de l’artefact .wasm du plugin dont les imports et le describe() déterminent les fonctions hôtes et les commandes enregistrées |
Ce que fait une entrée importer
aggrega plugin add importer écrit l’identité du plugin et la dernière version publiée pour lui, ou la version que vous indiquez sous la forme <name>:<version> — importer/<name>:<version> — dans la liste plugins.importer. Cette entrée attache l’importer qu’elle nomme : un import qui demande un format qu’annonce l’importer exécute cet importer, à cette version, même lorsque d’autres importers de votre catalogue annoncent aussi ce format, et seul cet importer reçoit ce que l’entrée porte sous with. Quel importer transforme une source en brouillons décrit l’entrée en entier.
Un importer est attaché par une seule entrée, donc ajouter un importer que la liste plugins.importer du fichier en cours d’écriture nomme déjà — à n’importe quelle version, ou par une plage — n’ajoute pas de seconde entrée. La commande déplace plutôt cette entrée vers la version qu’elle a résolue : l’entrée garde sa place dans la liste et tout ce qu’elle porte sous with. Ajouter un importer à la version que nomme déjà son entrée laisse l’entrée telle quelle.
Les commandes d’un plugin CLI et leurs flags
À chaque démarrage, aggrega ajoute une commande pour chaque commande qu’apporte un plugin cli configuré, en lisant les commandes et leurs flags dans l’auto-description describe() du plugin — depuis le cache de describe lorsqu’il contient le digest épinglé du plugin, et sinon en interrogeant le plugin. Chaque flag déclaré est déclaré sur sa commande, de sorte que aggrega help <command> le liste comme il liste les flags d’une commande intégrée ; le plugin reçoit tout de même ses arguments non analysés et lit lui-même ses flags.
Le digest épinglé se trouve à côté de la référence du plugin dans la liste plugins.cli de la configuration, écrit sha256: suivi de 64 chiffres hexadécimaux en minuscules — la graphie qu’enregistre aggrega plugin add cli. Un digest écrit autrement, par exemple en hexadécimal brut sans le préfixe sha256:, est refusé au chargement du fichier de configuration, en nommant le fichier et l’entrée ; tant qu’il n’est pas corrigé, aucune commande de plugin configuré n’est ajoutée, et un avertissement sur la sortie d’erreur standard porte le refus.
Avant d’ajouter l’une des commandes d’un plugin, aggrega vérifie chaque flag que déclare chacune d’elles. Un plugin dont les déclarations échouent est ignoré : aucune de ses commandes n’est ajoutée, un avertissement sur la sortie d’erreur standard nomme le plugin, la commande, le flag et ce qui ne va pas, et toute autre commande — intégrée ou issue d’un autre plugin — s’exécute normalement :
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 digitUne déclaration de flag est acceptée lorsque :
- le flag a un nom, et aucun autre flag de la même commande ne l’a ;
- sa forme abrégée, s’il en a une, est une seule lettre ou un seul chiffre ASCII qu’aucun autre flag de la même commande n’utilise ;
- ni son nom ni sa forme abrégée ne réutilisent un flag que possède déjà chaque commande
aggrega—--help,-het les flags globaux ; - son type, s’il en déclare un, est
string,boolouint— un flag sans type est un flag chaîne ; - sa valeur par défaut, s’il en déclare une, est une valeur de son type.
L’omission se répète, avec son avertissement, à chaque invocation jusqu’à ce que la configuration épingle une version du plugin dont les déclarations sont acceptées. Les champs d’une déclaration de flag sont décrits sous spec.commands sur la page de l’entité Plugin.
Générer des entités et synchroniser des enregistrements : deux types d’actes différents
Deux de ces sous-commandes produisent un fichier, et ce qu’elles produisent n’est pas de même nature.
plugin gen-catalog — les entités générées vous appartiennent et sont à modifier
aggrega plugin gen-catalog produit des entités Plugin du catalogue. Une entité est un document du catalogue : vous la classez, la relisez et continuez à la modifier avec le reste de votre catalogue. Comme c’est un contenu qui vous appartient, la commande peut vous le remettre plutôt que de l’écrire sur le disque.
--dry-run fait tout ce que fait gen-catalog, sauf écrire. Il renvoie les entités générées sous forme de contenu — aucun fichier n’est créé, aucun répertoire n’est créé — et chaque document de la réponse nomme le fichier auquel il est destiné, de sorte qu’un appelant sait où chacun doit aller. Un appelant qui gère son propre modèle de document, comme un éditeur, y place le contenu, où vous le voyez avant qu’il ne soit enregistré et pouvez le modifier ou l’annuler. Sans le flag, les entités sont écrites sous --output-dir, car un appelant dans un terminal n’a pas de meilleur endroit où les mettre.
Le contenu renvoyé et les octets écrits sont le même contenu : --dry-run renvoie ce que l’écriture aurait produit, et non un aperçu assemblé séparément. Tout autre comportement est aussi celui de l’écriture — les mêmes guests sont lus, les mêmes overlays appariés, et --output-dir est obligatoire dans les deux cas, car chaque document renvoyé nomme toujours le fichier auquel il est destiné et ce chemin est composé à partir de lui.
Chaque entité est composée et validée avant qu’aucune ne soit livrée, de sorte qu’une exécution produit soit l’ensemble complet, soit rien. Un overlay qui arrête la génération — un overlay manquant, ou dont l’identité ne correspond pas au guest avec lequel il est fusionné — ne laisse derrière lui aucune sortie partiellement écrite à nettoyer.
plugin sync — les enregistrements gérés par la machine appartiennent au compilateur
aggrega plugin sync met les enregistrements gérés par la machine d’un plugin en accord avec son module : l’ensemble des fonctions hôtes dérivé de la section d’import du module, et le reflet des commandes lu dans l’auto-description du plugin lui-même. Les deux sont une vérité de terrain dans le binaire plutôt que des valeurs que quelqu’un choisit.
Il écrit toujours et ne propose pas de --dry-run. Cela reste vrai même s’il écrit dans un fichier d’entité que vous avez rédigé — la limite se trace sur le contenu, pas sur le fichier. Les enregistrements que le compilateur tient sur lui-même ne sont pas à vous de modifier, il n’y a donc rien à relire avant qu’ils ne soient appliqués ; le document qui les entoure reste intact octet pour octet, et seuls ces blocs changent.