aggrega plugin
Kiểm tra các Wasm plugin mà CLI có thể phân giải
Cú pháp
aggrega pluginMô tả
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.Lệnh con
| Lệnh | Mô tả |
|---|---|
aggrega plugin add | Tìm một plugin thuộc loại được chỉ định trong registry và thêm nó |
aggrega plugin gen-catalog | Tạo các thực thể catalog Plugin từ describe() của guest cùng với một overlay do người dùng viết |
aggrega plugin list | Liệt kê các plugin mà CLI có thể phân giải cùng với metadata describe() của chúng |
aggrega plugin remove | Gỡ bỏ một plugin đã cấu hình thuộc loại được chỉ định |
aggrega plugin run-local | Nạp một guest .wasm cục bộ và gọi một trong các export của nó |
aggrega plugin sync | Đồng bộ các bản ghi do máy sở hữu của một plugin (host function, lệnh CLI) trong tệp thực thể của nó với tệp .wasm của nó |
Mô tả 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.Các flag của aggrega plugin add
| Cờ | Mặc định | Mô tả |
|---|---|---|
--accept-capabilities | false | Chấp nhận các capability đã khai báo của một plugin cli mà không cần lời nhắc tương tác (chỉ dành cho loại cli) |
--capability | — | Capability mà binding provider phục vụ (bắt buộc với, và chỉ hợp lệ với, loại provider) |
--dry-run | false | Làm mọi thứ trừ việc ghi: trả về cấu hình kết quả dưới dạng nội dung, nêu tên tệp mà nó dành cho, và không tạo hay sửa đổi gì. Nếu không có flag này, phần gắn kết được ghi vào tệp cấu hình đã phân giải. Không được chấp nhận với loại cli. |
--global | false | Ghi phần gắn kết vào cấu hình toàn cục dùng chung cho mọi workspace. |
--role | — | Vai trò gắn kết governance: annotation-transform, label-transform, ir-verdict hoặc render-verdict (bắt buộc với, và chỉ hợp lệ với, loại governance) |
--workspace | false | Ghi phần gắn kết vào cấu hình workspace của dự án này. Phần gắn kết provider hoặc socket mặc định được ghi ở đây; một plugin cli mặc định được ghi vào cấu hình toàn cục. |
--yes | false | Bỏ qua lời nhắc xác nhận capability của cli khi dùng không tương tác (chỉ dành cho loại cli) |
Mô tả 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.Các flag của aggrega plugin gen-catalog
| Cờ | Mặc định | Mô tả |
|---|---|---|
--dry-run | false | Làm mọi thứ trừ việc ghi: trả về các thực thể được tạo dưới dạng nội dung, nêu tên tệp mà mỗi thực thể dành cho, và không tạo hay sửa đổi gì. Mọi hành vi khác đều giống như khi ghi, nên một lựa chọn mà thao tác ghi sẽ từ chối thì ở đây cũng bị từ chối. Nếu không có flag này, các thực thể được ghi vào bên dưới —output-dir. |
--from-embedded | false | tạo một thực thể cho mỗi guest được nhúng trong binary này |
--output-dir | — | thư mục mà các thực thể được tạo sẽ được ghi vào bên dưới (bắt buộc) |
--overlay | — | thư mục overlay do người dùng viết (—from-embedded) hoặc tệp (—plugin) (bắt buộc) |
--plugin | — | tạo một thực thể duy nhất cho guest .wasm tại đường dẫn này |
Mô tả 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.Các flag của aggrega plugin list
| Cờ | Mặc định | Mô tả |
|---|---|---|
--output, -o | table | Định dạng đầu ra: table|json. |
Mô tả 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.Các flag của aggrega plugin remove
| Cờ | Mặc định | Mô tả |
|---|---|---|
--global | false | Gỡ bỏ khỏi cấu hình toàn cục dùng chung cho mọi workspace. |
--workspace | false | Gỡ bỏ khỏi cấu hình workspace của dự án này. Phần gắn kết provider hoặc socket mặc định ở đây; một lệnh cli mặc định ở cấu hình toàn cục. |
Mô tả 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.Các flag của aggrega plugin run-local
| Cờ | Mặc định | Mô tả |
|---|---|---|
--export | — | export đã khai báo cần gọi |
--plugin | — | đường dẫn hệ thống tệp tới artifact .wasm |
--type | — | loại plugin mà phần tự báo cáo describe() của guest phải khớp |
--with | — | payload cho export: JSON nội tuyến, hoặc @ |
Mô tả 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.Các flag của aggrega plugin sync
| Cờ | Mặc định | Mô tả |
|---|---|---|
--plugin | — | Đường dẫn tới artifact .wasm của plugin, mà các import và describe() của nó xác định các host function và lệnh được ghi lại |
Một mục importer làm gì
aggrega plugin add importer ghi danh tính của plugin và phiên bản mới nhất được phát hành cho nó, hoặc phiên bản bạn chỉ định dưới dạng <name>:<version> — importer/<name>:<version> — vào danh sách plugins.importer. Mục đó gắn importer mà nó nêu tên: một lần import yêu cầu một định dạng mà importer quảng bá sẽ chạy importer đó, ở phiên bản đó, ngay cả khi các importer khác trong catalog của bạn cũng quảng bá định dạng ấy, và chỉ importer đó được trao những gì mục mang dưới with. Importer nào biến một nguồn thành bản nháp mô tả đầy đủ về mục này.
Một importer được gắn bởi một mục, nên việc thêm một importer mà danh sách plugins.importer của tệp đang được ghi đã nêu tên — ở bất kỳ phiên bản nào, hoặc theo một khoảng — không thêm mục thứ hai. Thay vào đó, lệnh chuyển mục đó sang phiên bản mà nó đã phân giải: mục giữ nguyên vị trí trong danh sách và mọi thứ nó mang dưới with. Thêm một importer ở đúng phiên bản mà mục của nó đã nêu sẽ để nguyên mục đó.
Các lệnh của một plugin CLI và các cờ của chúng
Mỗi lần aggrega khởi động, nó thêm một lệnh cho mỗi lệnh mà một plugin cli đã cấu hình đóng góp, đọc các lệnh và cờ của chúng từ bản tự báo cáo describe() của plugin — từ bộ đệm describe khi bộ đệm này giữ digest đã ghim của plugin, và nếu không thì bằng cách describe plugin. Mỗi cờ được khai báo sẽ được khai báo trên lệnh của nó để aggrega help <command> liệt kê cờ đó theo cách nó liệt kê các cờ của một lệnh tích hợp sẵn; plugin vẫn nhận các đối số của nó ở dạng chưa phân tích và tự đọc các cờ của mình.
Digest đã ghim nằm cạnh tham chiếu của plugin trong danh sách plugins.cli của cấu hình, được viết là sha256: theo sau là 64 chữ số thập lục phân viết thường — cách viết mà aggrega plugin add cli ghi lại. Một digest được viết theo bất kỳ cách nào khác, chẳng hạn như chuỗi thập lục phân trần không có tiền tố sha256:, sẽ bị từ chối khi tệp cấu hình được nạp, kèm tên tệp và mục; cho đến khi nó được sửa, không lệnh nào của plugin đã cấu hình được thêm vào, và một cảnh báo trên standard error mang thông tin từ chối đó.
Trước khi thêm bất kỳ lệnh nào của một plugin, aggrega kiểm tra mọi cờ mà từng lệnh khai báo. Một plugin có khai báo không hợp lệ sẽ bị bỏ qua: không lệnh nào của nó được thêm vào, một cảnh báo trên standard error nêu tên plugin, lệnh, cờ và lỗi của cờ đó, và mọi lệnh khác — tích hợp sẵn hoặc từ plugin khác — chạy như bình thường:
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 digitMột khai báo cờ hợp lệ khi:
- cờ có tên, và không cờ nào khác của cùng lệnh có tên đó;
- dạng viết tắt của nó, nếu có, là một chữ cái hoặc chữ số ASCII duy nhất mà không cờ nào khác của cùng lệnh sử dụng;
- cả tên lẫn dạng viết tắt của nó đều không dùng lại một cờ mà mọi lệnh
aggregađã có —--help,-h, và các cờ toàn cục; - kiểu của nó, nếu được khai báo, là
string,boolhoặcint— một cờ không có kiểu là cờ chuỗi; - giá trị mặc định của nó, nếu được khai báo, là một giá trị thuộc kiểu của nó.
Việc bỏ qua, kèm cảnh báo của nó, được lặp lại ở mỗi lần gọi cho đến khi cấu hình ghim một phiên bản của plugin có khai báo hợp lệ. Các trường mà một khai báo cờ mang được mô tả dưới spec.commands trên trang thực thể Plugin.
Sinh thực thể và đồng bộ bản ghi: hai loại hành động khác nhau
Hai trong số các lệnh con này tạo ra một tệp, và những gì chúng tạo ra không cùng một loại.
plugin gen-catalog — các thực thể được sinh ra thuộc về bạn để chỉnh sửa
aggrega plugin gen-catalog tạo ra các thực thể danh mục Plugin. Một thực thể là một tài liệu danh mục: bạn lưu nó, xem xét nó, và tiếp tục chỉnh sửa nó cùng với phần còn lại của danh mục. Vì đó là nội dung bạn sở hữu, lệnh có thể trao nó cho bạn thay vì ghi nó xuống đĩa.
--dry-run làm mọi việc mà gen-catalog làm, ngoại trừ việc ghi. Nó trả về các thực thể được sinh ra dưới dạng nội dung — không tệp nào được tạo, không thư mục nào được tạo — và mỗi tài liệu trong kết quả nêu tên tệp mà nó dành cho, để bên gọi biết mỗi tài liệu thuộc về đâu. Một bên gọi giữ mô hình tài liệu riêng, chẳng hạn như một trình soạn thảo, đặt nội dung vào đó, nơi bạn thấy nó trước khi được lưu và có thể sửa đổi hoặc hoàn tác. Khi không có cờ này, các thực thể được ghi vào --output-dir, vì một bên gọi ở terminal không có nơi nào tốt hơn để đặt chúng.
Nội dung được trả về và các byte được ghi là cùng một nội dung: --dry-run trả về những gì thao tác ghi lẽ ra đã tạo ra, không phải một bản xem trước được lắp ráp riêng. Mọi hành vi khác cũng giống thao tác ghi — cùng các guest được đọc, cùng các overlay được khớp, và --output-dir đều bắt buộc trong cả hai trường hợp, vì mỗi tài liệu được trả về vẫn nêu tên tệp mà nó dành cho và đường dẫn đó được ghép từ cờ này.
Mọi thực thể đều được ghép và xác thực trước khi bất kỳ thực thể nào được chuyển giao, nên một lần chạy hoặc tạo ra toàn bộ tập hợp hoặc không tạo ra gì. Một overlay làm dừng quá trình sinh — overlay bị thiếu, hoặc có danh tính không khớp với guest mà nó được hợp nhất vào — không để lại đầu ra ghi dở nào cần dọn dẹp.
plugin sync — các bản ghi do máy sở hữu thuộc về trình biên dịch
aggrega plugin sync đưa các bản ghi do máy sở hữu của một plugin về khớp với module của nó: tập host-function suy ra từ phần import của module, và bản phản chiếu lệnh đọc từ bản tự báo cáo của chính plugin. Cả hai đều là sự thật gốc nằm trong tệp nhị phân chứ không phải các giá trị do ai đó chọn.
Lệnh này luôn ghi, và không cung cấp --dry-run. Điều đó vẫn đúng ngay cả khi nó ghi vào một tệp thực thể do bạn soạn — ranh giới được vạch trên nội dung, không phải trên tệp. Các bản ghi mà trình biên dịch duy trì về chính nó không thuộc về bạn để chỉnh sửa, nên không có gì cần xem xét trước khi chúng được ghi; phần còn lại của tài liệu được giữ nguyên từng byte, và chỉ những khối đó thay đổi.