Skip to content
AggregaAggrega
Select language: English

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 a
free-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; search
reads it and contacts no network. Run 'aggrega registry update' first, and again
whenever you want to pick up newly published entities. A freshness line naming
each searched registry and when its index was last updated is written to standard
error, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched against
each 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 catalog
category 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 the
results are merged. With --registry (a host or a friendly alias), only that
registry's index is searched.
A search needs at least one configured registry. With none configured there is
nowhere 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 what
lets a caller tell a search that ran and matched nothing from a search that
could not be performed. Run 'aggrega config init' to register a registry with
its signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: a
version a publisher has retracted, where the retraction carries a signature
this workspace's trust policy verifies, is not reported. Such an entity is
still listed, and the versions left out are named in a NOTES column, so an
entity whose every published version is retracted is reported as existing with
no version to take rather than disappearing from the result. Pass
--include-retracted to report the highest published version whatever its
retraction status; the NOTES column names the retracted versions either way.
The same holds for 'aggrega search -o json', where the 'version' field carries
the version a resolution would take and a 'retracted' array names the versions
left out.

Flags

FlagDefaultDescription
--capability[]Plugin capability to match. Repeatable; a record declaring any one is kept.
--include-retractedfalseReport 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.
--limit0Cap the number of results (0 means no cap).
--output, -otableOutput 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:

  • version is the version a resolution would take. It is the empty string when every published version is retracted, which pairs with a retracted list naming them all.
  • retracted lists 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.