aggrega search
Search the local index of configured registries
Synopsis
aggrega search [query] [flags]Description
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach entity's name and description. The facet filters narrow the result further,combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe, workload, plugin); repeatable, case-insensitive --capability a plugin capability; repeatable --plugin-type a plugin socket type (for example provider, governance) -l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalogcategory is the label component.aggrega.ai/category, so'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere to look, so the command refuses: the reason goes to standard error,standard output carries nothing, and the exit status is non-zero. That is whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.Flags
| Flag | Default | Description |
|---|---|---|
--capability | [] | Plugin capability to match. Repeatable; a record declaring any one is kept. |
--include-retracted | false | Report the highest published version even where a verified marker retracts it. By default the reported version is one a resolution would take. |
--kind | [] | Entity kind to match (component|feature|recipe|featurerecipe|workload|plugin). Repeatable; a record matching any one is kept. Case-insensitive. |
--limit | 0 | Cap the number of results (0 means no cap). |
--output, -o | table | Output format: table|json|names. |
--plugin-type | — | Plugin socket type to match (for example provider, governance, linter). |
--registry | — | Search only this registry, addressed by host or friendly alias. Default searches every configured registry. |
--selector, -l | — | Label selector over the entity’s catalog labels, which include its category (-l component.aggrega.ai/category=compute). |
When no registry is configured
A search reads the local index of the registries this machine is configured to reach, so it
needs at least one of them. With none configured there is nowhere to look, and aggrega search
refuses rather than answering: it writes the reason to standard error, exits non-zero, and
leaves standard output empty — in every output format, --output json included.
The refusal is what keeps two different answers apart. A search that ran and matched nothing
exits zero and reports (no matches) on standard output; a search that could not run at all
exits non-zero and reports nothing there. A script branching on the exit status can therefore
tell “this entity is not published” from “this machine has no registry to ask”, which a notice
on standard output and a zero status cannot express.
Run aggrega config init to register a registry together with its signature trust policy, then
aggrega registry update to build the local index the search reads.
aggrega registry list and aggrega registry update answer the same situation differently, and
deliberately so. Listing registries when there are none is a complete listing of an empty set,
and an index build with nothing to walk has nothing left to do: both are finished operations, so
both report on standard output and exit zero. Only the search is reporting that it could not do
what it was asked.
The version a search reports
The VERSION column carries the version a resolution would take. A version its publisher has
retracted is not reported, provided the retraction carries a signature this workspace’s trust
policy verifies — the same two conditions that decide whether a retraction affects a pull, so
a search and a pull agree on which version is the answer.
A retraction failing either condition changes nothing about what is reported. A marker at an advisory severity leaves its version selectable, and a marker whose signature does not verify is not a claim this workspace acts on. In both cases the highest published version is reported exactly as it would be with no marker at all.
An entity with a retracted version is still listed. A NOTES column names the versions left
out, and appears only in a result that has something to report. An entity whose every
published version is retracted is reported with (none) as its version and a note saying no
version remains, rather than being dropped from the result — an omitted entity would be
indistinguishable from one that does not exist.
Pass --include-retracted to report the highest published version whatever its retraction
status, which is the answer to “what is published?” rather than “what should I use?”. It
changes only the reported version; the NOTES column names the retracted versions either
way.
What a search reads is the local index that aggrega registry update writes, so it reports
what each registry stated when that index was last built. A version retracted since then is
not yet recorded, and the freshness line written to standard error names the moment each
index was built.
The machine-readable result
--output json carries the same contract in two fields:
versionis the version a resolution would take. It is the empty string when every published version is retracted, which pairs with aretractedlist naming them all.retractedlists the versions left out of that choice, in ascending version order. It is absent when nothing was left out.
A consumer asking which version it would get reads version. Deriving that from the
deprecations array instead means reimplementing the severity and signature conditions, and
a second implementation of those conditions is free to disagree with the one the compiler
applies; retracted reports the outcome those conditions already produced.
Each record also carries published: every version the index recorded, in ascending version
order, each with the manifestDigest its tag resolved to when the index was built and, where
this workspace’s trust policy verified that version’s own signature, its signer — of several
that verify, the one the transparency log recorded earliest. A version with no signer carries
no signature that policy verified, and nothing more is said about it.
A consumer reading one version’s content addresses it by that digest — for example
aggrega inspect oci://<host>/<repository>@<digest> — so what it reads is the bytes the index
recorded, whatever happens to the tag afterwards.
Where anything records when a version was published, its entry also carries publishedAt, an
RFC 3339 timestamp in UTC to the second, and publishedAtSource, which says where it came from.
transparency-log is the time a transparency log recorded the version’s keyless signature,
which this workspace’s trust policy verified together with the log’s signed promise of that
time — the signer’s signature, the earliest of those that verify, so signing a version again
moves neither. publisher is the time the publication stated beside what it published, from the
publishing machine’s own clock, which nothing attests. The two are kept apart so a consumer
sorting by date can still tell an attested time from a stated one. A version with neither
carries no date, and nothing more is said about it; see
aggrega registry update for
when each is recorded.