CLI Overview
The aggrega CLI is the compiler’s entry point. Every interaction with Aggrega — compiling an Aggregate into deployable artifacts, inspecting the catalog or the IR, resolving and pinning dependencies, publishing catalog entities, checking correctness with validate, checking publishing conventions with lint, and serving an IDE — runs through a subcommand of aggrega. This chapter set covers each subcommand’s flags, inputs, and outputs.
aggrega validate and aggrega lint are complementary checkers that mirror each other’s three scopes — the whole catalog, a Release’s dependency closure, or one entity. aggrega validate checks correctness (schema, pillars, reference resolution, extends, provider input-kind capability, and — for a rendering entity — an isolated render); aggrega lint checks publishing conventions (naming, category-directory alignment, annotation prefixes, and version-bump size). Neither emits artifacts; use validate to answer “is this correct?” and lint to answer “does this follow the catalog’s publishing discipline?”.
aggrega build follows the Single Entry Point Principle: the Release is the sole compilation input. aggrega build --release release.yaml reads the Release’s aggregate: and manifest: pointers to locate the rest of the topology, and produces per-boundary output under dist/: a named boundary renders under its declared directory:, or under dist/boundaries/<boundary-name>/ when it declares none; a Release that declares top-level components: instead of named boundaries renders flat under dist/. Every component the topology holds must belong to one of those boundaries, and a component none of them holds halts the build: a component reaches a boundary either by being named under that boundary’s components:, under the id it carries once sub-Aggregates are flattened, or by sitting inside a sub-Aggregate the boundary routes in under aggregates:. A component reaching neither would render outside every boundary the Release declares, taking its output location, sync wave, annotations and per-component infra: from nowhere, so the build stops and names the component rather than emitting artifacts the Release’s boundary configuration was never applied to. The same relation is checked from the Release’s side: a boundary entry naming a component the topology does not hold configures nothing, so it halts too and the diagnostic reports the id the entry addressed. aggrega pull shares the Release-as-input shape; aggrega inspect takes any entity — a catalog name, an entity file, a registry reference, or a Release; aggrega push takes a catalog entity; aggrega validate and aggrega lint accept a catalog entity, a Release (via --release), or the whole catalog; aggrega serve runs as a long-lived process. The global flags page documents flags that apply across subcommands.
What a release may change in the commands, the flags and the assistant tools — and what a patch release never changes — is stated in Compatibility.
Per-command reference
aggrega build— the primary compile command. Reads a Release pointer, resolves the Aggregate and Manifest it references, and emits per-boundary compiled artifacts.aggrega inspect— a readable view of any entity: a catalog entity by name, an entity file by path, a published entity read straight from its registry, or a fully resolved Release, whose IR Graph--ir-graphwrites as JSON and whose dependency closure--closurereports.aggrega pull— resolve a Release’s dependencies and write a per-Release lockfile pinning every dependency; cache catalog entities and source artifacts.aggrega push— publish a catalog entity to an OCI registry, optionally signing it at push time.aggrega sign— sign one or more already-published artifacts and attach each signature as an OCI referrer.aggrega auth token— acquire an OIDC identity token interactively and print it to stdout, for one authentication across a batch of keyless signs.aggrega registry— manage the registries the workspace knows and their signature trust policy: add, list, and remove entries, and build a local searchable index of published catalog metadata withregistry update.aggrega search— search the local index of configured registries for published catalog entities and installable CLI plugins, matching a free-text query and optional facet filters.aggrega validate— check correctness (schema, pillars, reference resolution,extends, input-kind capability, isolated render) across the whole catalog, a Release’s dependency closure (--release), or one entity.aggrega lint— check publishing conventions across the whole catalog, a Release’s dependency closure (--release), or one entity;--pre-publishadds the registry-aware version-bump gate.aggrega serve— a long-running compiler-as-service daemon (JSON-RPC over stdin/stdout) for IDE integration.aggrega version— print the CLI version;-o jsonemits a machine-readable object.aggrega get-schema— print the canonical JSON Schema for an entity or contract kind;--listnames every kind. The authoritative shape to author a file against.aggrega scaffold— print a starter document for an entity kind, derived from that kind’s schema: the required fields, with the fixed ones filled in and a placeholder everywhere a value is needed. Drafting writes no file; redirect it where you want it. With--exampleit writes one of the documentation’s runnable examples into a new directory instead, and--example --listnames them.aggrega mcp— run a Model Context Protocol server, over standard input and output or over HTTP, so an MCP-capable client becomes an Aggrega-aware authoring assistant. See Authoring Aggrega files.aggrega skills— install the skill that teaches an AI assistant to install and use Aggrega into that assistant’s skill folder, for one project or, with--global, for every project of yours.aggrega cache— inspect and maintain the on-disk caches: list what they hold, reclaim artifact-cache entries no lockfile references, trim the compiled-module cache to a size cap, or wipe every cache.aggrega config— inspect and manage the configuration Aggrega reads: show what applies and which layer decided each setting, seed a working configuration, and freeze the build-critical settings into the workspace.aggrega deprecate— attach a signed deprecation marker to an already-published artifact.aggrega edit-document— apply one bounded structured edit to a document, preserving every byte it does not touch.aggrega explain— explain the halting condition a code names.aggrega import— turn a foreign source description into draft Aggrega authoring files.aggrega login— authenticate to an OCI registry and store the credential thatpush,pullandlint --pre-publishpresent.aggrega logout— remove a stored registry credential.aggrega pin— record the content pins for an entity’s external inputs in theentity.lockbeside it.aggrega plugin— list the Wasm plugins the CLI can resolve, add or remove a workspace binding, and check a guest before you publish it.aggrega push-artifact— publish a standalone data artifact, such as a documentation bundle, to an OCI registry under itsdocs/namespace.- Configuration — which file a setting belongs in, and how the layers combine. Start here: it opens with the two files most projects need and keeps the mechanisms a larger project reaches for behind that.
- Global flags — flags shared across subcommands (the workspace root, the global configuration file, color and plain accessible output, and the offline posture). Offline is reachable as a configuration setting and an environment variable too — see Configuration, the configuration schema and environment variables.
- The workspace boundary — what lies inside a workspace, what a symbolic link leading out of it does to each kind of path, the paths that reach outside on purpose, and what to do when one is refused.
| Command | Description |
|---|---|
aggrega auth | Manage the signing identity |
aggrega build | Compile an Aggregate and Release into provider-native artifacts under dist/ at the workspace root |
aggrega cache | Inspect and maintain the on-disk caches |
aggrega config | Inspect and manage the workspace configuration |
aggrega deprecate | Attach a signed deprecation marker to an already-published artifact |
aggrega edit-document | Apply one bounded structured edit to a document, preserving every byte it does not touch |
aggrega explain | Explain the halting condition a code names |
aggrega get-schema | Print the JSON Schema for an entity or contract kind |
aggrega import | Turn a foreign source description into draft Aggrega authoring files |
aggrega inspect | Inspect a catalog entity by name, an entity file by path, or a published entity by its registry reference |
aggrega lint | Check catalog publishing conventions across the catalog, a Release, or one entity |
aggrega login | Authenticate to an OCI registry and store the credential |
aggrega logout | Remove a stored registry credential |
aggrega mcp | Run a Model Context Protocol server over standard input and output, or over HTTP, for AI-assistant integration |
aggrega pin | Record the content pins for an entity’s external inputs in the entity.lock beside it |
aggrega plugin | Inspect the Wasm plugins the CLI can resolve |
aggrega pull | Resolve catalog and source dependencies into the cache and write the per-Release lockfile |
aggrega push | Bundle and publish a catalog entity to an OCI registry |
aggrega push-artifact | Publish a standalone data artifact (such as a documentation bundle) to an OCI registry |
aggrega registry | Manage registries and their signature trust policy |
aggrega scaffold | Draft a starter document for an entity kind, or write a runnable example into a new directory |
aggrega search | Search the local index of configured registries |
aggrega serve | Run as a long-running compiler-as-service over JSON-RPC 2.0 on stdin/stdout |
aggrega sign | Sign one or more already-published artifacts and attach their signatures |
aggrega skills | Install the Aggrega skill into an AI assistant |
aggrega validate | Check correctness across the catalog, a Release, or one entity |
aggrega version | Print the aggrega CLI version |
Positional arguments and exit status
Every command refuses a positional argument it has no use for, and reports that refusal through a non-zero exit status rather than completing as though the invocation were valid. The rule covers the commands that exist only to group subcommands, where a mistyped subcommand name arrives as an unrecognised positional: the command’s help is printed and the exit status is non-zero, so a typo on a scripted surface fails loudly instead of reading as a successful run. aggrega invoked with an unrecognised command behaves the same way and additionally names the closest matching command, where one is close.
An unrecognised command also says how to find a CLI plugin of that name. The answer comes from the local index of the default registry that aggrega registry update builds and aggrega search reads, so it returns at once and the mistyped word is never sent to a registry, online or offline. Where the index holds a CLI plugin of that name, the message names the aggrega plugin add cli <name> command that installs it. Where the index holds none, it names the search that looks for one, aggrega search <name> --kind plugin --plugin-type cli. Where no index has been built yet, it names aggrega plugin add cli <name>, which looks the plugin up by that name at the registry and refuses where none is published. Either command carries the name quoted for the shell where it needs to be.
Where positionals are meaningful, each command’s own reference page documents what it accepts. An installed CLI plugin is the deliberate exception: its command keeps argument parsing to itself, so the whole argument vector is forwarded to the plugin, which is the sole parser of its own arguments — and the plugin’s own exit status is what the invocation returns.
Progress, and how long a command waits on a registry
A command that waits says what it is waiting on. Wherever a command waits on a registry, on a download or on compiling a plugin for the first time, it shows that step on standard error, the way aggrega build and aggrega pull show theirs: on a terminal, a row naming the step with a spinner and the time it has taken so far, ticked once the step is done and left unticked where the step failed; on a terminal that cannot redraw in place, or under --plain, one line per step as it ends, with its time. Where standard error is not a terminal, nothing is shown, and nothing a command prints on standard output changes either way. A step is shown only while the command actually waits on it, so a run served from the cache shows nothing at all, and compiling a plugin is shown only when it takes long enough to be a real compile rather than a cached one.
The commands that show their steps this way, besides the command of every installed CLI plugin:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
No request waits on a server without end. A request waits at most 30 seconds for the server to begin its answer once the request has been sent in full, and at most 30 seconds for the next part of an answer already arriving. A server that keeps a request waiting longer is refused under E0376, naming the server and the wait. Only waiting is bounded: a download or an upload that keeps moving takes as long as it takes. A Helm chart a Recipe’s source: fetches over HTTPS is held to the first of the two waits only, and its expiry is reported in the network library’s own words rather than under E0376. A request a command already asks again when it times out — a read during aggrega registry update, a write during a publication — is asked again before the refusal is reported.
A walk of a registry’s whole repository listing ends within five minutes. Some registries gather every repository they hold before answering a listing request at all, so each page of the listing is waited on for as long as the walk may run rather than for 30 seconds; a listing that has not ended after five minutes is stopped and refused under E0377. aggrega plugin add walks the listing only when no plugin carries exactly the name it was given, to find one whose name contains it, so naming the plugin exactly never waits on the walk.
A registry that asks to slow down is waited out, until it has asked for five minutes without a break. A command waits as long as such a registry asks, sends it fewer requests at once, and shows the wait with its other progress; a registry that answers nothing but “slow down” for five minutes is refused under E0378. A registry that asks to slow down describes how.
The three bounds are fixed; there is no setting that changes them.
Paths you type, and the workspace boundary
A path you type on the command line — a --release, a --catalog, an --output-dir, a file to validate, lint, pin or publish, a --workspace-root — is used where it leads, inside the workspace or outside it, through any link on the way. What the command then reads and writes on its own account is held to the workspace whoever runs it: it does not read the workspace’s configuration files, a catalog document, a document beside a Release or a Release’s lockfile through a link leading out of the workspace, follow a path a Release or a Manifest writes out of it, or write its output, its lockfile or its cache through such a link. A directory you name outside the workspace is held the same way for what lies beneath it, and a Release you name outside the workspace reaches only files in its own directory. aggrega edit-document is the one command whose typed path is held as well: it edits only a document the workspace carries. The workspace boundary states the rule, the paths that reach outside on purpose, and the remedy for each refusal.
Searching the catalog index
aggrega search [query] looks up published entities across the registries the workspace knows. The optional [query] is a case-insensitive substring matched against each entity’s name and description. Facet filters narrow the result set:
--kindrestricts to one or more entity kinds (component,feature,recipe,featurerecipe,workload,plugin); it is repeatable and case-insensitive, and the kinds combine as OR.-l/--selectorfilters on the entity’s catalog labels. Category is a label, not a dedicated flag:-l component.aggrega.ai/category=datastore.--capabilityand--plugin-typefilter plugins by a declared capability or socket type;--capabilityis repeatable and combines as OR.--registryscopes the search to a single registry by host or friendly alias; by default every configured registry is searched.--limitcaps the number of results.-o/--outputselects the output format:table(the default, human-readable),json(a machine-readable array), ornames(bare identifiers, one per line).
Search always reads the local index — the offline snapshot that aggrega registry update builds and refreshes. It contacts no network and fetches nothing on demand. When the index is absent, the command fails and tells you to run aggrega registry update first. Every run prints a per-registry “last updated” freshness line to standard error, so the json and names output on standard out stays clean for scripting.
Shell completion
aggrega completion <shell> prints a completion script to stdout for bash, zsh, fish, or powershell. The script is generated from the CLI’s live command tree at the moment you run it, so it always reflects the commands and flags of the binary that produced it — there is no static file to regenerate as the CLI grows.
To try completion in your current session without installing anything, source the script directly:
source <(aggrega completion bash)To install completion permanently, write the script to the location your shell reads on startup.
bash
Bash completion relies on the bash-completion package; install it through your OS package manager if it is not already present.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
If completion is not yet enabled in your shell, enable it once:
echo "autoload -U compinit; compinit" >> ~/.zshrcThen write the completion script into a directory on your fpath:
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
Append the generated script to your PowerShell profile so it loads in every session:
aggrega completion powershell >> $PROFILEStart a new shell for the installed completion to take effect.