Visión general de la CLI
La CLI aggrega es el punto de entrada del compilador. Toda interacción con Aggrega — compilar un Aggregate en artefactos desplegables, inspeccionar el catálogo o la IR, resolver y fijar dependencias, publicar entidades de catálogo, comprobar la corrección con validate, comprobar las convenciones de publicación con lint y dar servicio a un IDE — pasa por un subcomando de aggrega. Este conjunto de capítulos cubre los flags, las entradas y las salidas de cada subcomando.
aggrega validate y aggrega lint son comprobadores complementarios cuyos tres ámbitos se corresponden entre sí: el catálogo completo, el cierre de dependencias de una Release o una sola entidad. aggrega validate comprueba la corrección (esquema, pilares, resolución de referencias, extends, capacidad del provider para el tipo de entrada y — para una entidad de renderizado — un renderizado aislado); aggrega lint comprueba las convenciones de publicación (nomenclatura, alineación con el directorio de categoría, prefijos de anotación y magnitud del incremento de versión). Ninguno emite artefactos; usa validate para responder a «¿es correcto?» y lint para responder a «¿sigue la disciplina de publicación del catálogo?».
aggrega build sigue el principio del punto de entrada único: la Release es la única entrada de compilación. aggrega build --release release.yaml lee los punteros aggregate: y manifest: de la Release para localizar el resto de la topología, y produce una salida por límite bajo dist/: un límite con nombre se genera bajo su directory: declarado, o bajo dist/boundaries/<boundary-name>/ cuando no declara ninguno; una Release que declara components: de primer nivel en lugar de límites con nombre se genera de forma plana bajo dist/. Todo componente de la topología debe pertenecer a uno de esos límites, y un componente que ninguno de ellos contiene detiene la build: un componente llega a un límite o bien por estar nombrado bajo los components: de ese límite, con el id que lleva una vez aplanados los sub-Aggregates, o bien por estar dentro de un sub-Aggregate que el límite enruta bajo aggregates:. Un componente que no llega por ninguna de las dos vías se generaría fuera de todo límite que declara la Release, sin ninguna fuente para su ubicación de salida, su sync wave, sus anotaciones y su infra: por componente, así que la build se detiene y nombra el componente en lugar de emitir artefactos a los que nunca se aplicó la configuración de límites de la Release. La misma relación se comprueba desde el lado de la Release: una entrada de límite que nombra un componente que la topología no contiene no configura nada, así que también detiene la build y el diagnóstico informa del id al que se dirigía la entrada. aggrega pull comparte la forma con la Release como entrada; aggrega inspect recibe cualquier entidad — un nombre de catálogo, un archivo de entidad, una referencia de registry o una Release; aggrega push recibe una entidad de catálogo; aggrega validate y aggrega lint aceptan una entidad de catálogo, una Release (mediante --release) o el catálogo completo; aggrega serve se ejecuta como un proceso de larga duración. La página de flags globales documenta los flags que se aplican a todos los subcomandos.
Lo que una release puede cambiar en los comandos, las opciones y las herramientas del asistente —y lo que una release de parche nunca cambia— se indica en Compatibilidad.
Referencia por comando
aggrega build— el comando de compilación principal. Lee un puntero a una Release, resuelve el Aggregate y el Manifest a los que hace referencia y emite artefactos compilados por límite.aggrega inspect— una vista legible de cualquier entidad: una entidad de catálogo por nombre, un archivo de entidad por ruta, una entidad publicada leída directamente desde su registry o una Release completamente resuelta, cuyo IR Graph escribe--ir-graphcomo JSON y cuyo cierre de dependencias informa--closure.aggrega pull— resuelve las dependencias de una Release y escribe un lockfile por Release que fija cada dependencia; almacena en caché las entidades de catálogo y los artefactos de origen.aggrega push— publica una entidad de catálogo en un registry OCI y, opcionalmente, la firma en el momento del push.aggrega sign— firma uno o más artefactos ya publicados y adjunta cada firma como referrer OCI.aggrega auth token— obtiene de forma interactiva un token de identidad OIDC y lo imprime en stdout, para una única autenticación válida para un lote de firmas keyless.aggrega registry— gestiona los registries que conoce el espacio de trabajo y su política de confianza de firmas: añade, enumera y elimina entradas, y construye conregistry updateun índice local consultable de los metadatos de catálogo publicados.aggrega search— busca en el índice local de los registries configurados entidades de catálogo publicadas y plugins de CLI instalables, a partir de una consulta de texto libre y filtros de facetas opcionales.aggrega validate— comprueba la corrección (esquema, pilares, resolución de referencias,extends, capacidad para el tipo de entrada, renderizado aislado) en el catálogo completo, en el cierre de dependencias de una Release (--release) o en una sola entidad.aggrega lint— comprueba las convenciones de publicación en el catálogo completo, en el cierre de dependencias de una Release (--release) o en una sola entidad;--pre-publishañade la verificación del incremento de versión que consulta el registry.aggrega serve— un daemon de larga duración que ofrece el compilador como servicio (JSON-RPC sobre stdin/stdout) para la integración con IDE.aggrega version— imprime la versión de la CLI;-o jsonemite un objeto legible por máquina.aggrega get-schema— imprime el JSON Schema canónico de un tipo de entidad o de contrato;--listnombra todos los tipos. La forma de referencia con la que escribir un archivo.aggrega scaffold— imprime un documento inicial para un tipo de entidad, derivado del esquema de ese tipo: los campos obligatorios, con los fijos ya completados y un marcador de posición allí donde se necesite un valor. La redacción no escribe ningún archivo; redirige la salida adonde la quieras. Con--example, en cambio, escribe uno de los ejemplos ejecutables de la documentación en un directorio nuevo, y--example --listlos nombra.aggrega mcp— ejecuta un servidor Model Context Protocol, sobre la entrada y salida estándar o sobre HTTP, para que un cliente compatible con MCP se convierta en un asistente de escritura que conoce Aggrega. Consulta Escribir archivos de Aggrega.aggrega skills— instala la skill que enseña a un asistente de IA a instalar y usar Aggrega en la carpeta de skills de ese asistente, para un proyecto o, con--global, para todos tus proyectos.aggrega cache— inspecciona y mantiene las cachés en disco: lista lo que contienen, recupera las entradas de la caché de artefactos a las que no hace referencia ningún lockfile, recorta la caché de módulos compilados hasta un límite de tamaño o vacía todas las cachés.aggrega config— inspecciona y gestiona la configuración que lee Aggrega: muestra lo que se aplica y qué capa decidió cada ajuste, prepara una configuración funcional y congela en el workspace los ajustes críticos para la build.aggrega deprecate— adjunta un marcador de obsolescencia firmado a un artefacto ya publicado.aggrega edit-document— aplica a un documento una única edición estructurada y acotada, conservando cada byte que no toca.aggrega explain— explica la condición de detención que nombra un código.aggrega import— convierte la descripción de una fuente externa en borradores de archivos de autoría de Aggrega.aggrega login— se autentica en un registry OCI y almacena la credencial que presentanpush,pullylint --pre-publish.aggrega logout— elimina una credencial de registry almacenada.aggrega pin— registra los pines de contenido de las entradas externas de una entidad en elentity.locksituado junto a ella.aggrega plugin— lista los plugins Wasm que la CLI puede resolver, añade o elimina un enlace del workspace y comprueba un guest antes de que lo publiques.aggrega push-artifact— publica un artefacto de datos independiente, como un paquete de documentación, en un registry OCI bajo su espacio de nombresdocs/.- Configuración — a qué archivo pertenece un ajuste y cómo se combinan las capas. Empieza aquí: se abre con los dos archivos que necesitan la mayoría de los proyectos y deja para después los mecanismos a los que recurre un proyecto más grande.
- Flags globales — flags compartidos entre subcomandos (la raíz del espacio de trabajo, el archivo de configuración global, la salida en color y la salida simple accesible, y el modo sin conexión). El modo sin conexión también está disponible como ajuste de configuración y como variable de entorno; consulta Configuración, el esquema de configuración y las variables de entorno.
- El límite del espacio de trabajo — qué queda dentro de un espacio de trabajo, qué efecto tiene en cada tipo de ruta un enlace simbólico que sale de él, las rutas que salen a propósito y qué hacer cuando se rechaza una.
| Comando | Descripción |
|---|---|
aggrega auth | Gestionar la identidad de firma |
aggrega build | Compilar un Aggregate y una Release en artefactos nativos del provider bajo dist/ en la raíz del espacio de trabajo |
aggrega cache | Inspeccionar y mantener las cachés en disco |
aggrega config | Inspeccionar y gestionar la configuración del espacio de trabajo |
aggrega deprecate | Adjuntar un marcador de obsolescencia firmado a un artefacto ya publicado |
aggrega edit-document | Aplicar a un documento una edición estructurada y acotada, conservando cada byte que no toca |
aggrega explain | Explicar la condición de detención que nombra un código |
aggrega get-schema | Imprimir el JSON Schema de un tipo de entidad o de contrato |
aggrega import | Convertir la descripción de una fuente externa en borradores de archivos de escritura de Aggrega |
aggrega inspect | Inspeccionar una entidad de catálogo por nombre, un archivo de entidad por ruta o una entidad publicada por su referencia de registry |
aggrega lint | Comprobar las convenciones de publicación del catálogo en el catálogo, una Release o una sola entidad |
aggrega login | Autenticarse en un registry OCI y almacenar la credencial |
aggrega logout | Eliminar una credencial de registry almacenada |
aggrega mcp | Ejecutar un servidor Model Context Protocol sobre la entrada y salida estándar, o sobre HTTP, para la integración con asistentes de IA |
aggrega pin | Registrar los pines de contenido de las entradas externas de una entidad en el entity.lock situado junto a ella |
aggrega plugin | Inspeccionar los plugins Wasm que la CLI puede resolver |
aggrega pull | Resolver las dependencias de catálogo y de origen en la caché y escribir el lockfile por Release |
aggrega push | Empaquetar y publicar una entidad de catálogo en un registry OCI |
aggrega push-artifact | Publicar un artefacto de datos independiente (como un paquete de documentación) en un registry OCI |
aggrega registry | Gestionar los registries y su política de confianza de firmas |
aggrega scaffold | Redactar un documento inicial para un tipo de entidad, o escribir un ejemplo ejecutable en un directorio nuevo |
aggrega search | Buscar en el índice local de los registries configurados |
aggrega serve | Ejecutarse como compilador-como-servicio de larga duración sobre JSON-RPC 2.0 en stdin/stdout |
aggrega sign | Firmar uno o más artefactos ya publicados y adjuntar sus firmas |
aggrega skills | Instalar la skill de Aggrega en un asistente de IA |
aggrega validate | Comprobar la corrección en el catálogo, una Release o una sola entidad |
aggrega version | Imprimir la versión de la CLI aggrega |
Argumentos posicionales y código de salida
Todo comando rechaza un argumento posicional que no le sirve, y comunica ese rechazo mediante un código de salida distinto de cero en lugar de completarse como si la invocación fuera válida. La regla abarca los comandos que solo existen para agrupar subcomandos, donde un nombre de subcomando mal escrito llega como un argumento posicional no reconocido: se imprime la ayuda del comando y el código de salida es distinto de cero, de modo que un error tipográfico en un script falla de forma visible en lugar de parecer una ejecución correcta. aggrega invocado con un comando no reconocido se comporta igual y además indica el comando más parecido, cuando hay uno lo bastante parecido.
Un comando no reconocido también indica cómo encontrar un plugin de CLI con ese nombre. La respuesta procede del índice local del registro predeterminado que aggrega registry update construye y aggrega search lee, así que llega al instante y la palabra mal escrita nunca se envía a un registro, ni en línea ni sin conexión. Cuando el índice contiene un plugin de CLI con ese nombre, el mensaje indica el comando aggrega plugin add cli <name> que lo instala. Cuando el índice no contiene ninguno, indica la búsqueda que busca uno, aggrega search <name> --kind plugin --plugin-type cli. Cuando todavía no se ha construido ningún índice, indica aggrega plugin add cli <name>, que busca el plugin por ese nombre en el registro y lo rechaza si no hay ninguno publicado. Cualquiera de los dos comandos lleva el nombre entrecomillado para el shell cuando hace falta.
Donde los argumentos posicionales tienen sentido, la página de referencia de cada comando documenta lo que acepta. Un plugin de la CLI instalado es la excepción deliberada: su comando se reserva el análisis de los argumentos, de modo que el vector de argumentos completo se reenvía al plugin, que es el único que analiza sus propios argumentos — y el código de salida del propio plugin es lo que devuelve la invocación.
Progreso, y cuánto espera un comando a un registro
Un comando que espera indica qué está esperando. Siempre que un comando espera a un registro, a una descarga o a la primera compilación de un plugin, muestra ese paso en la salida de error estándar, como aggrega build y aggrega pull muestran los suyos: en un terminal, una fila que nombra el paso con un indicador giratorio y el tiempo transcurrido hasta el momento, marcada una vez terminado el paso y sin marcar cuando el paso falló; en un terminal que no puede redibujar en el sitio, o con --plain, una línea por paso al terminar, con su tiempo. Cuando la salida de error estándar no es un terminal, no se muestra nada, y en ningún caso cambia nada de lo que un comando imprime en la salida estándar. Un paso se muestra solo mientras el comando lo espera de verdad, así que una ejecución servida desde la caché no muestra nada en absoluto, y la compilación de un plugin solo se muestra cuando tarda lo suficiente como para ser una compilación real y no una almacenada en caché.
Los comandos que muestran sus pasos de esta forma, además del comando de cada plugin de CLI instalado:
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
Ninguna solicitud espera a un servidor indefinidamente. Una solicitud espera como máximo 30 segundos a que el servidor empiece su respuesta una vez enviada la solicitud por completo, y como máximo 30 segundos a la siguiente parte de una respuesta que ya está llegando. Un servidor que hace esperar una solicitud más tiempo se rechaza con E0376, que nombra el servidor y la espera. Solo la espera está acotada: una descarga o una subida que sigue avanzando tarda lo que tarde. Un chart de Helm que el source: de una Recipe obtiene por HTTPS está sujeto solo a la primera de las dos esperas, y su vencimiento se informa con las propias palabras de la biblioteca de red en lugar de con E0376. Una solicitud que un comando ya repite cuando se agota el tiempo — una lectura durante aggrega registry update, una escritura durante una publicación — se repite antes de que se informe el rechazo.
El recorrido de toda la lista de repositorios de un registro termina en cinco minutos. Algunos registros reúnen todos los repositorios que contienen antes siquiera de responder a una solicitud de lista, así que cada página de la lista se espera durante todo el tiempo que puede durar el recorrido en lugar de 30 segundos; una lista que no ha terminado tras cinco minutos se detiene y se rechaza con E0377. aggrega plugin add recorre la lista solo cuando ningún plugin lleva exactamente el nombre que recibió, para encontrar uno cuyo nombre lo contenga, así que nombrar el plugin con exactitud nunca espera al recorrido.
A un registro que pide ir más despacio se le espera, hasta que lo ha pedido durante cinco minutos sin pausa. Un comando espera lo que pida ese registro, le envía menos solicitudes a la vez y muestra la espera junto con el resto de su progreso; un registro que durante cinco minutos no responde otra cosa que «más despacio» se rechaza con E0378. Un registro que pide ir más despacio describe cómo.
Los tres límites son fijos; no hay ningún ajuste que los cambie.
Las rutas que escribes y el límite del workspace
Una ruta que escribes en la línea de comandos — un --release, un --catalog, un --output-dir, un archivo para validar, analizar con el linter, fijar o publicar, un --workspace-root — se usa allí adonde lleva, dentro o fuera del workspace, a través de cualquier enlace en el camino. Lo que el comando lee y escribe después por su propia cuenta queda confinado al workspace, quienquiera que lo ejecute: no lee los archivos de configuración del workspace, un documento del catálogo, un documento junto a una Release ni el lockfile de una Release a través de un enlace que sale del workspace, no sigue una ruta que una Release o un Manifest escribe fuera de él, ni escribe su salida, su lockfile o su caché a través de un enlace así. Un directorio que indicas fuera del workspace queda confinado de la misma manera para lo que contiene, y una Release que indicas fuera del workspace solo alcanza archivos de su propio directorio. aggrega edit-document es el único comando cuya ruta escrita también queda confinada: solo edita un documento que contiene el workspace. El límite del workspace expone la regla, las rutas que salen a propósito y la solución para cada rechazo.
Buscar en el índice del catálogo
aggrega search [query] busca entidades publicadas en los registries que conoce el workspace. El parámetro opcional [query] es una subcadena, sin distinción entre mayúsculas y minúsculas, que se compara con el nombre y la descripción de cada entidad. Los filtros de faceta acotan el conjunto de resultados:
--kindrestringe a uno o más tipos de entidad (component,feature,recipe,featurerecipe,workload,plugin); se puede repetir, no distingue entre mayúsculas y minúsculas, y los tipos se combinan con OR.-l/--selectorfiltra por las etiquetas de catálogo de la entidad. La categoría es una etiqueta, no un flag dedicado:-l component.aggrega.ai/category=datastore.--capabilityy--plugin-typefiltran los plugins por una capacidad declarada o por tipo de socket;--capabilityse puede repetir y se combina con OR.--registrylimita la búsqueda a un único registry, indicado por host o por un alias; de forma predeterminada se busca en todos los registries configurados.--limitlimita el número de resultados.-o/--outputselecciona el formato de salida:table(el predeterminado, legible por personas),json(un array legible por máquinas) onames(identificadores sin más, uno por línea).
La búsqueda siempre lee el índice local — la instantánea sin conexión que aggrega registry update crea y actualiza. No contacta con ninguna red ni descarga nada bajo demanda. Cuando el índice no existe, el comando falla y te indica que ejecutes primero aggrega registry update. Cada ejecución imprime en la salida de error estándar, para cada registry, una línea de actualidad «last updated», de modo que la salida json y names en la salida estándar se mantiene limpia para scripts.
Autocompletado del shell
aggrega completion <shell> imprime en stdout un script de autocompletado para bash, zsh, fish o powershell. El script se genera a partir del árbol de comandos activo de la CLI en el momento en que lo ejecutas, así que siempre refleja los comandos y flags del binario que lo produjo — no hay ningún archivo estático que regenerar a medida que la CLI crece.
Para probar el autocompletado en tu sesión actual sin instalar nada, carga el script directamente con source:
source <(aggrega completion bash)Para instalar el autocompletado de forma permanente, escribe el script en la ubicación que tu shell lee al iniciarse.
bash
El autocompletado de Bash depende del paquete bash-completion; instálalo con el gestor de paquetes de tu sistema operativo si aún no está presente.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Si el autocompletado aún no está habilitado en tu shell, habilítalo una vez:
echo "autoload -U compinit; compinit" >> ~/.zshrcDespués escribe el script de autocompletado en un directorio de tu 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
Añade el script generado a tu perfil de PowerShell para que se cargue en cada sesión:
aggrega completion powershell >> $PROFILEInicia un shell nuevo para que el autocompletado instalado surta efecto.