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 게스트를 로드하고 그 export 중 하나를 호출합니다 |
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 유형에 필수이며, 해당 유형에서만 유효) |
--dry-run | false | 쓰기를 제외한 모든 작업을 수행합니다. 결과 구성을 대상 파일 이름과 함께 내용으로 반환하며, 아무것도 생성하거나 수정하지 않습니다. 이 플래그가 없으면 첨부 항목이 해석된 구성 파일에 기록됩니다. cli 유형에서는 허용되지 않습니다. |
--global | false | 모든 작업 공간에서 공유되는 전역 구성에 첨부 항목을 기록합니다. |
--role | — | 거버넌스 첨부 역할: annotation-transform, label-transform, ir-verdict 또는 render-verdict(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 | — | 호출할 선언된 export |
--plugin | — | .wasm 아티팩트의 파일 시스템 경로 |
--type | — | 게스트의 describe() 자체 보고가 일치해야 하는 플러그인 유형 |
--with | — | export에 전달할 페이로드: 인라인 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 | — | 기록되는 호스트 함수와 명령을 결정하는 import와 describe()를 가진 플러그인 .wasm 아티팩트의 경로 |
importer 항목이 하는 일
aggrega plugin add importer는 플러그인의 식별자와 그에 대해 게시된 최신 버전 또는 <name>:<version>으로 지정한 버전(importer/<name>:<version>)을 plugins.importer 목록에 기록합니다. 이 항목은 자신이 지정하는 importer를 연결합니다. importer가 알리는 형식을 요청하는 가져오기는 카탈로그의 다른 importer들도 그 형식을 알리는 경우에도 해당 버전의 그 importer를 실행하며, 항목이 with 아래에 담은 내용은 그 importer에만 전달됩니다. 어떤 importer가 소스를 초안으로 변환하는가에서 이 항목을 자세히 설명합니다.
importer는 하나의 항목으로 연결되므로, 기록 중인 파일의 plugins.importer 목록이 이미 지정하고 있는 importer를 추가하면(어떤 버전이든, 범위로 지정되었든) 두 번째 항목은 추가되지 않습니다. 대신 명령은 그 항목을 자신이 해석한 버전으로 옮깁니다. 항목은 목록 내 위치와 with 아래에 담은 모든 내용을 유지합니다. 항목이 이미 지정하고 있는 버전으로 importer를 추가하면 항목은 그대로 유지됩니다.
CLI 플러그인의 명령과 그 플래그
aggrega는 시작할 때마다 구성된 cli 플러그인이 제공하는 명령마다 명령을 하나씩 추가하며, 명령과 그 플래그는 플러그인의 describe() 자체 보고에서 읽습니다. describe 캐시가 플러그인의 고정된 다이제스트를 보유하고 있으면 캐시에서 읽고, 그렇지 않으면 플러그인을 describe하여 읽습니다. 선언된 각 플래그는 해당 명령에 선언되므로 aggrega help <command>는 내장 명령의 플래그를 나열하는 방식 그대로 이를 나열합니다. 플러그인은 여전히 인수를 파싱되지 않은 상태로 받아 자신의 플래그를 직접 읽습니다.
고정된 다이제스트는 구성의 plugins.cli 목록에서 플러그인 참조 옆에 있으며, sha256: 뒤에 소문자 16진수 64자리를 붙여 씁니다. 이는 aggrega plugin add cli가 기록하는 표기입니다. sha256: 접두사 없는 16진수만 쓰는 등 다른 방식으로 표기된 다이제스트는 구성 파일을 로드할 때 거부되며, 이때 파일과 항목이 명시됩니다. 이를 수정할 때까지 구성된 어떤 플러그인의 명령도 추가되지 않으며, 표준 오류의 경고가 거부 내용을 전달합니다.
aggrega는 플러그인의 명령을 추가하기 전에 각 명령이 선언하는 모든 플래그를 검사합니다. 선언이 검사를 통과하지 못한 플러그인은 건너뜁니다. 그 플러그인의 명령은 하나도 추가되지 않고, 표준 오류에 플러그인, 명령, 플래그와 그 문제점을 명시하는 경고가 하나 출력되며, 내장 명령이든 다른 플러그인의 명령이든 나머지 모든 명령은 평소대로 실행됩니다.
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플래그 선언은 다음 경우에 통과합니다.
- 플래그에 이름이 있고, 같은 명령의 다른 플래그가 그 이름을 갖지 않는 경우
- 단축형이 있다면, 같은 명령의 다른 플래그가 사용하지 않는 단일 ASCII 문자 또는 숫자인 경우
- 이름과 단축형 모두 모든
aggrega명령이 이미 가진 플래그(--help,-h, 전역 플래그)를 재사용하지 않는 경우 - 타입을 선언한다면 그 타입이
string,bool또는int인 경우. 타입이 없는 플래그는 문자열 플래그입니다. - 기본값을 선언한다면 그 값이 해당 타입의 값인 경우
구성이 선언이 통과하는 플러그인 버전을 고정할 때까지, 건너뛰기와 그 경고는 호출할 때마다 반복됩니다. 플래그 선언이 갖는 필드는 Plugin 엔터티 페이지의 spec.commands에서 설명합니다.
엔터티 생성과 레코드 동기화: 서로 다른 두 종류의 작업
이 하위 명령 중 두 가지는 파일을 생성하며, 각각이 생성하는 것은 같은 종류가 아닙니다.
plugin gen-catalog — 생성된 엔터티는 사용자가 편집하는 것입니다
aggrega plugin gen-catalog는 Plugin 카탈로그 엔터티를 생성합니다. 엔터티는 카탈로그 문서입니다. 파일로 보관하고, 검토하고, 카탈로그의 나머지 부분과 함께 계속 편집합니다. 사용자가 소유하는 내용이므로, 명령은 이를 디스크에 쓰는 대신 사용자에게 건네줄 수 있습니다.
--dry-run은 쓰기를 제외하고 gen-catalog가 하는 모든 일을 수행합니다. 생성된 엔터티를 내용으로 반환하며 — 파일도 만들지 않고 디렉터리도 만들지 않습니다 — 응답의 각 문서는 자신이 대상으로 하는 파일을 명시하므로, 호출자는 각 문서가 어디에 속하는지 알 수 있습니다. 편집기처럼 자체 문서 모델을 유지하는 호출자는 내용을 그곳에 넣으며, 사용자는 저장되기 전에 이를 확인하고 수정하거나 되돌릴 수 있습니다. 이 플래그가 없으면 엔터티는 --output-dir 아래에 쓰여집니다. 터미널의 호출자에게는 이를 둘 더 나은 곳이 없기 때문입니다.
반환되는 내용과 쓰여지는 바이트는 같은 내용입니다. --dry-run은 별도로 조립한 미리보기가 아니라 쓰기가 생성했을 내용을 반환합니다. 다른 모든 동작도 쓰기와 같습니다. 같은 게스트를 읽고, 같은 오버레이를 매칭하며, 어느 경우든 --output-dir이 필요합니다. 반환되는 각 문서도 여전히 자신이 대상으로 하는 파일을 명시하고, 그 경로가 이 값으로 구성되기 때문입니다.
모든 엔터티는 어느 하나라도 전달되기 전에 구성되고 검증되므로, 한 번의 실행은 전체 집합을 생성하거나 아무것도 생성하지 않습니다. 생성을 중단시키는 오버레이 — 누락되었거나, 병합 대상 게스트와 식별자가 일치하지 않는 오버레이 — 는 정리해야 할 부분적으로 쓰인 출력을 남기지 않습니다.
plugin sync — 기계가 소유하는 레코드는 컴파일러의 것입니다
aggrega plugin sync는 플러그인의 기계 소유 레코드를 모듈과 일치시킵니다. 이 레코드는 모듈의 import 섹션에서 도출한 호스트 함수 집합과, 플러그인 자체 보고에서 읽은 명령 미러입니다. 둘 다 누군가 선택하는 값이 아니라 바이너리 안의 실제 사실입니다.
이 명령은 항상 쓰기를 수행하며 --dry-run을 제공하지 않습니다. 사용자가 작성한 엔터티 파일 안에 쓰더라도 마찬가지입니다. 경계는 파일이 아니라 내용에 그어집니다. 컴파일러가 스스로에 관해 유지하는 레코드는 사용자가 편집하는 것이 아니므로, 반영되기 전에 검토할 것이 없습니다. 주변 문서는 바이트 단위로 그대로 유지되며, 해당 블록만 변경됩니다.