Vue d’ensemble de la CLI
La CLI aggrega est le point d’entrée du compilateur. Chaque interaction avec Aggrega — compiler un Aggregate en artefacts déployables, inspecter le catalogue ou l’IR, résoudre et épingler les dépendances, publier des entités de catalogue, vérifier la correction avec validate, vérifier les conventions de publication avec lint et servir un IDE — passe par une sous-commande de aggrega. Cet ensemble de chapitres couvre les flags, les entrées et les sorties de chaque sous-commande.
aggrega validate et aggrega lint sont des vérificateurs complémentaires dont les trois portées se reflètent mutuellement — le catalogue entier, la fermeture des dépendances d’une Release, ou une seule entité. aggrega validate vérifie la correction (schéma, piliers, résolution des références, extends, capacité du provider pour le type d’entrée et — pour une entité de rendu — un rendu isolé) ; aggrega lint vérifie les conventions de publication (nommage, alignement sur le répertoire de catégorie, préfixes d’annotation et ampleur de l’incrément de version). Aucun des deux n’émet d’artefacts ; utilisez validate pour répondre à « est-ce correct ? » et lint pour répondre à « cela suit-il la discipline de publication du catalogue ? ».
aggrega build suit le principe du point d’entrée unique : la Release est la seule entrée de compilation. aggrega build --release release.yaml lit les pointeurs aggregate: et manifest: de la Release pour localiser le reste de la topologie, et produit une sortie par frontière sous dist/ : une frontière nommée est produite sous son directory: déclaré, ou sous dist/boundaries/<boundary-name>/ lorsqu’elle n’en déclare aucun ; une Release qui déclare des components: de premier niveau au lieu de frontières nommées est produite à plat sous dist/. Chaque composant de la topologie doit appartenir à l’une de ces frontières, et un composant qu’aucune d’elles ne contient arrête le build : un composant rejoint une frontière soit en étant nommé sous les components: de cette frontière, sous l’id qu’il porte une fois les sous-Aggregates aplatis, soit en se trouvant dans un sous-Aggregate que la frontière achemine sous aggregates:. Un composant qui ne rejoint ni l’une ni l’autre serait produit en dehors de toute frontière déclarée par la Release, sans aucune source pour son emplacement de sortie, sa sync wave, ses annotations et son infra: par composant ; le build s’arrête donc et nomme le composant au lieu d’émettre des artefacts auxquels la configuration des frontières de la Release n’a jamais été appliquée. La même relation est vérifiée du côté de la Release : une entrée de frontière qui nomme un composant que la topologie ne contient pas ne configure rien ; elle arrête donc aussi le build, et le diagnostic indique l’id que l’entrée désignait. aggrega pull partage la forme avec la Release comme entrée ; aggrega inspect prend n’importe quelle entité — un nom de catalogue, un fichier d’entité, une référence de registre ou une Release ; aggrega push prend une entité de catalogue ; aggrega validate et aggrega lint acceptent une entité de catalogue, une Release (via --release) ou le catalogue entier ; aggrega serve s’exécute comme un processus de longue durée. La page des flags globaux documente les flags qui s’appliquent à toutes les sous-commandes.
Ce qu’une release peut changer dans les commandes, les options et les outils de l’assistant — et ce qu’une release de correctif ne change jamais — est indiqué dans Compatibilité.
Référence par commande
aggrega build— la commande de compilation principale. Lit un pointeur de Release, résout l’Aggregate et le Manifest qu’il référence, et émet des artefacts compilés par frontière.aggrega inspect— une vue lisible de n’importe quelle entité : une entité de catalogue par son nom, un fichier d’entité par son chemin, une entité publiée lue directement depuis son registry, ou une Release entièrement résolue, dont--ir-graphécrit l’IR Graph en JSON et dont--closurerapporte la fermeture des dépendances.aggrega pull— résout les dépendances d’une Release et écrit un lockfile par Release qui épingle chaque dépendance ; met en cache les entités de catalogue et les artefacts source.aggrega push— publie une entité de catalogue dans un registry OCI, en la signant éventuellement au moment du push.aggrega sign— signe un ou plusieurs artefacts déjà publiés et attache chaque signature en tant que referrer OCI.aggrega auth token— obtient de manière interactive un jeton d’identité OIDC et l’affiche sur stdout, pour une seule authentification valable pour un lot de signatures keyless.aggrega registry— gère les registries connus du workspace et leur politique de confiance des signatures : ajouter, lister et supprimer des entrées, et construire avecregistry updateun index local consultable des métadonnées de catalogue publiées.aggrega search— recherche dans l’index local des registries configurés les entités de catalogue publiées et les plugins CLI installables, à partir d’une requête en texte libre et de filtres de facettes facultatifs.aggrega validate— vérifie la correction (schéma, piliers, résolution des références,extends, capacité pour le type d’entrée, rendu isolé) sur le catalogue entier, la fermeture des dépendances d’une Release (--release) ou une seule entité.aggrega lint— vérifie les conventions de publication sur le catalogue entier, la fermeture des dépendances d’une Release (--release) ou une seule entité ;--pre-publishajoute le contrôle de l’incrément de version qui interroge le registry.aggrega serve— un démon de longue durée exposant le compilateur comme service (JSON-RPC sur stdin/stdout) pour l’intégration aux IDE.aggrega version— affiche la version de la CLI ;-o jsonémet un objet lisible par machine.aggrega get-schema— affiche le JSON Schema canonique d’un type d’entité ou de contrat ;--listnomme chaque type. La forme de référence par rapport à laquelle écrire un fichier.aggrega scaffold— affiche un document de départ pour un type d’entité, dérivé du schéma de ce type : les champs obligatoires, les champs fixes déjà renseignés et un espace réservé partout où une valeur est nécessaire. La rédaction n’écrit aucun fichier ; redirigez la sortie là où vous le souhaitez. Avec--example, la commande écrit à la place l’un des exemples exécutables de la documentation dans un nouveau répertoire, et--example --listles nomme.aggrega mcp— exécute un serveur Model Context Protocol, sur l’entrée et la sortie standard ou sur HTTP, afin qu’un client compatible MCP devienne un assistant d’écriture qui connaît Aggrega. Voir Écrire des fichiers Aggrega.aggrega skills— installe la skill qui apprend à un assistant IA à installer et utiliser Aggrega dans le dossier de skills de cet assistant, pour un projet ou, avec--global, pour tous vos projets.aggrega cache— inspecte et entretient les caches sur disque : liste ce qu’ils contiennent, récupère les entrées du cache d’artefacts qu’aucun lockfile ne référence, réduit le cache des modules compilés à une taille maximale ou efface tous les caches.aggrega config— inspecte et gère la configuration que lit Aggrega : montre ce qui s’applique et quelle couche a décidé chaque réglage, initialise une configuration fonctionnelle et fige dans le workspace les réglages critiques pour le build.aggrega deprecate— attache un marqueur de dépréciation signé à un artefact déjà publié.aggrega edit-document— applique une modification structurée et délimitée à un document, en préservant chaque octet qu’elle ne touche pas.aggrega explain— explique la condition d’arrêt que nomme un code.aggrega import— transforme une description de source étrangère en brouillons de fichiers de rédaction Aggrega.aggrega login— s’authentifie auprès d’un registre OCI et stocke l’identifiant que présententpush,pulletlint --pre-publish.aggrega logout— supprime un identifiant de registre stocké.aggrega pin— enregistre les épinglages de contenu des entrées externes d’une entité dans l’entity.lockplacé à côté.aggrega plugin— liste les plugins Wasm que la CLI peut résoudre, ajoute ou supprime une liaison de workspace et vérifie un guest avant que vous le publiiez.aggrega push-artifact— publie un artefact de données autonome, tel qu’un bundle de documentation, sur un registre OCI sous son espace de nomsdocs/.- Configuration — dans quel fichier placer un réglage, et comment les couches se combinent. Commencez ici : la page s’ouvre sur les deux fichiers dont la plupart des projets ont besoin et garde pour la suite les mécanismes auxquels recourt un projet plus important.
- Flags globaux — flags partagés entre les sous-commandes (la racine du workspace, le fichier de configuration global, la sortie en couleur et la sortie simple accessible, et le mode hors ligne). Le mode hors ligne est aussi accessible comme réglage de configuration et comme variable d’environnement — voir Configuration, le schéma de configuration et les variables d’environnement.
- La frontière du workspace — ce qui se trouve à l’intérieur d’un workspace, l’effet d’un lien symbolique qui en sort sur chaque type de chemin, les chemins qui sortent délibérément, et que faire lorsque l’un d’eux est refusé.
| Commande | Description |
|---|---|
aggrega auth | Gérer l’identité de signature |
aggrega build | Compiler un Aggregate et une Release en artefacts natifs du provider sous dist/ à la racine du workspace |
aggrega cache | Inspecter et entretenir les caches sur disque |
aggrega config | Inspecter et gérer la configuration du workspace |
aggrega deprecate | Attacher un marqueur de dépréciation signé à un artefact déjà publié |
aggrega edit-document | Appliquer à un document une modification structurée et circonscrite, en préservant chaque octet qu’elle ne touche pas |
aggrega explain | Expliquer la condition d’arrêt que nomme un code |
aggrega get-schema | Afficher le JSON Schema d’un type d’entité ou de contrat |
aggrega import | Transformer la description d’une source externe en brouillons de fichiers d’écriture Aggrega |
aggrega inspect | Inspecter une entité de catalogue par son nom, un fichier d’entité par son chemin ou une entité publiée par sa référence de registry |
aggrega lint | Vérifier les conventions de publication du catalogue sur le catalogue, une Release ou une seule entité |
aggrega login | S’authentifier auprès d’un registry OCI et stocker l’identifiant |
aggrega logout | Supprimer un identifiant de registry stocké |
aggrega mcp | Exécuter un serveur Model Context Protocol sur l’entrée et la sortie standard, ou sur HTTP, pour l’intégration d’assistants IA |
aggrega pin | Enregistrer les épinglages de contenu des entrées externes d’une entité dans l’entity.lock situé à côté |
aggrega plugin | Inspecter les plugins Wasm que la CLI peut résoudre |
aggrega pull | Résoudre les dépendances de catalogue et de source dans le cache et écrire le lockfile par Release |
aggrega push | Empaqueter et publier une entité de catalogue dans un registry OCI |
aggrega push-artifact | Publier un artefact de données autonome (tel qu’un lot de documentation) dans un registry OCI |
aggrega registry | Gérer les registries et leur politique de confiance des signatures |
aggrega scaffold | Rédiger un document de départ pour un type d’entité, ou écrire un exemple exécutable dans un nouveau répertoire |
aggrega search | Rechercher dans l’index local des registries configurés |
aggrega serve | S’exécuter comme compilateur-service de longue durée via JSON-RPC 2.0 sur stdin/stdout |
aggrega sign | Signer un ou plusieurs artefacts déjà publiés et y attacher leurs signatures |
aggrega skills | Installer la skill Aggrega dans un assistant IA |
aggrega validate | Vérifier la correction sur le catalogue, une Release ou une seule entité |
aggrega version | Afficher la version de la CLI aggrega |
Arguments positionnels et code de sortie
Chaque commande refuse un argument positionnel dont elle n’a pas l’usage, et signale ce refus par un code de sortie non nul au lieu de se terminer comme si l’invocation était valide. La règle couvre les commandes qui n’existent que pour regrouper des sous-commandes, où un nom de sous-commande mal saisi arrive comme un argument positionnel non reconnu : l’aide de la commande est affichée et le code de sortie est non nul, de sorte qu’une faute de frappe dans un script échoue de façon visible au lieu de passer pour une exécution réussie. aggrega invoqué avec une commande non reconnue se comporte de la même façon et nomme en plus la commande la plus proche, lorsqu’il y en a une suffisamment proche.
Une commande non reconnue indique aussi comment trouver un plugin de CLI portant ce nom. La réponse vient de l’index local du registre par défaut que aggrega registry update construit et que aggrega search lit ; elle arrive donc immédiatement et le mot mal saisi n’est jamais envoyé à un registre, en ligne ou hors ligne. Lorsque l’index contient un plugin de CLI portant ce nom, le message nomme la commande aggrega plugin add cli <name> qui l’installe. Lorsque l’index n’en contient aucun, il nomme la recherche qui en cherche un, aggrega search <name> --kind plugin --plugin-type cli. Lorsqu’aucun index n’a encore été construit, il nomme aggrega plugin add cli <name>, qui recherche le plugin sous ce nom dans le registre et refuse lorsqu’aucun n’est publié. Chacune de ces commandes porte le nom mis entre guillemets pour le shell lorsque c’est nécessaire.
Là où les arguments positionnels ont un sens, la page de référence de chaque commande documente ce qu’elle accepte. Un plugin de CLI installé est l’exception délibérée : sa commande se réserve l’analyse des arguments, de sorte que le vecteur d’arguments entier est transmis au plugin, seul à analyser ses propres arguments — et le code de sortie du plugin lui-même est ce que renvoie l’invocation.
Progression, et durée d’attente d’une commande auprès d’un registre
Une commande qui attend indique ce qu’elle attend. Partout où une commande attend un registre, un téléchargement ou la première compilation d’un plugin, elle affiche cette étape sur la sortie d’erreur standard, comme aggrega build et aggrega pull affichent les leurs : sur un terminal, une ligne nommant l’étape avec un indicateur rotatif et le temps écoulé jusque-là, cochée une fois l’étape terminée et laissée non cochée lorsque l’étape a échoué ; sur un terminal qui ne peut pas redessiner sur place, ou avec --plain, une ligne par étape à la fin de celle-ci, avec sa durée. Lorsque la sortie d’erreur standard n’est pas un terminal, rien n’est affiché, et rien de ce qu’une commande écrit sur la sortie standard ne change dans un cas comme dans l’autre. Une étape n’est affichée que pendant que la commande l’attend réellement : une exécution servie depuis le cache n’affiche donc rien du tout, et la compilation d’un plugin n’est affichée que lorsqu’elle dure assez longtemps pour être une véritable compilation plutôt qu’une compilation mise en cache.
Les commandes qui affichent leurs étapes de cette manière, en plus de la commande de chaque plugin de CLI installé :
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
Aucune requête n’attend un serveur indéfiniment. Une requête attend au plus 30 secondes que le serveur commence sa réponse une fois la requête entièrement envoyée, et au plus 30 secondes la partie suivante d’une réponse qui arrive déjà. Un serveur qui fait attendre une requête plus longtemps est refusé sous E0376, avec le nom du serveur et la durée d’attente. Seule l’attente est bornée : un téléchargement ou un envoi qui continue de progresser prend le temps qu’il faut. Un chart Helm que le source: d’une Recipe récupère en HTTPS n’est soumis qu’à la première des deux attentes, et son expiration est signalée dans les termes propres de la bibliothèque réseau plutôt que sous E0376. Une requête qu’une commande renvoie déjà lorsqu’elle expire — une lecture pendant aggrega registry update, une écriture pendant une publication — est renvoyée avant que le refus ne soit signalé.
Le parcours de la liste complète des dépôts d’un registre se termine en cinq minutes au plus. Certains registres rassemblent tous les dépôts qu’ils contiennent avant même de répondre à une requête de liste ; chaque page de la liste est donc attendue aussi longtemps que le parcours peut durer plutôt que 30 secondes ; une liste qui n’est pas terminée au bout de cinq minutes est interrompue et refusée sous E0377. aggrega plugin add ne parcourt la liste que lorsqu’aucun plugin ne porte exactement le nom qu’il a reçu, afin d’en trouver un dont le nom le contient ; nommer le plugin exactement n’attend donc jamais le parcours.
Un registre qui demande de ralentir est attendu, jusqu’à ce qu’il l’ait demandé pendant cinq minutes sans interruption. Une commande attend aussi longtemps qu’un tel registre le demande, lui envoie moins de requêtes à la fois et affiche l’attente avec le reste de sa progression ; un registre qui ne répond rien d’autre que « ralentissez » pendant cinq minutes est refusé avec E0378. Un registre qui demande de ralentir décrit comment.
Les trois limites sont fixes ; aucun paramètre ne les modifie.
Les chemins que vous saisissez, et la frontière du workspace
Un chemin que vous saisissez sur la ligne de commande — un --release, un --catalog, un --output-dir, un fichier à valider, à analyser avec le linter, à épingler ou à publier, un --workspace-root — est utilisé là où il mène, dans le workspace ou en dehors, à travers tout lien rencontré en chemin. Ce que la commande lit et écrit ensuite pour son propre compte reste confiné au workspace, quel que soit l’utilisateur qui l’exécute : elle ne lit pas les fichiers de configuration du workspace, un document du catalogue, un document à côté d’une Release ou le fichier de verrouillage d’une Release à travers un lien qui sort du workspace, ne suit pas un chemin qu’une Release ou un Manifest écrit hors de celui-ci, et n’écrit pas sa sortie, son fichier de verrouillage ou son cache à travers un tel lien. Un répertoire que vous désignez hors du workspace est confiné de la même façon pour ce qu’il contient, et une Release que vous désignez hors du workspace n’atteint que les fichiers de son propre répertoire. aggrega edit-document est la seule commande dont le chemin saisi est lui aussi confiné : elle ne modifie qu’un document que contient le workspace. La frontière du workspace énonce la règle, les chemins qui sortent volontairement, et le remède à chaque refus.
Rechercher dans l’index du catalogue
aggrega search [query] recherche les entités publiées dans les registres que connaît le workspace. Le paramètre facultatif [query] est une sous-chaîne, insensible à la casse, comparée au nom et à la description de chaque entité. Des filtres par facette restreignent l’ensemble des résultats :
--kindrestreint à un ou plusieurs types d’entité (component,feature,recipe,featurerecipe,workload,plugin) ; il est répétable et insensible à la casse, et les types se combinent en OU.-l/--selectorfiltre sur les labels de catalogue de l’entité. La catégorie est un label, pas un flag dédié :-l component.aggrega.ai/category=datastore.--capabilityet--plugin-typefiltrent les plugins par capacité déclarée ou par type de socket ;--capabilityest répétable et se combine en OU.--registrylimite la recherche à un seul registre, désigné par son hôte ou par un alias ; par défaut, tous les registres configurés sont interrogés.--limitplafonne le nombre de résultats.-o/--outputsélectionne le format de sortie :table(par défaut, lisible par un humain),json(un tableau lisible par une machine) ounames(identifiants seuls, un par ligne).
La recherche lit toujours l’index local — l’instantané hors ligne que aggrega registry update construit et actualise. Elle ne contacte aucun réseau et ne récupère rien à la demande. Lorsque l’index est absent, la commande échoue et vous indique d’exécuter d’abord aggrega registry update. Chaque exécution affiche sur la sortie d’erreur standard, pour chaque registre, une ligne de fraîcheur « last updated », de sorte que la sortie json et names sur la sortie standard reste propre pour les scripts.
Complétion du shell
aggrega completion <shell> affiche sur stdout un script de complétion pour bash, zsh, fish ou powershell. Le script est généré à partir de l’arborescence de commandes active de la CLI au moment où vous l’exécutez, il reflète donc toujours les commandes et les flags du binaire qui l’a produit — il n’y a aucun fichier statique à régénérer à mesure que la CLI évolue.
Pour essayer la complétion dans votre session actuelle sans rien installer, chargez directement le script avec source :
source <(aggrega completion bash)Pour installer la complétion de façon permanente, écrivez le script à l’emplacement que votre shell lit au démarrage.
bash
La complétion Bash repose sur le paquet bash-completion ; installez-le avec le gestionnaire de paquets de votre système d’exploitation s’il n’est pas déjà présent.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Si la complétion n’est pas encore activée dans votre shell, activez-la une fois :
echo "autoload -U compinit; compinit" >> ~/.zshrcÉcrivez ensuite le script de complétion dans un répertoire de votre 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
Ajoutez le script généré à votre profil PowerShell pour qu’il soit chargé dans chaque session :
aggrega completion powershell >> $PROFILEDémarrez un nouveau shell pour que la complétion installée prenne effet.