Visão geral da CLI
A CLI aggrega é o ponto de entrada do compilador. Todas as interações com o Aggrega — compilar um Aggregate em artefactos implementáveis, inspecionar o catálogo ou o IR, resolver e fixar dependências, publicar entidades de catálogo, verificar a correção com validate, verificar as convenções de publicação com lint e servir um IDE — passam por um subcomando de aggrega. Este conjunto de capítulos aborda as flags, entradas e saídas de cada subcomando.
aggrega validate e aggrega lint são verificadores complementares que espelham os três âmbitos um do outro — todo o catálogo, o fecho de dependências de uma Release ou uma entidade. aggrega validate verifica a correção (esquema, pilares, resolução de referências, extends, capacidade de tipos de entrada do provider e — para uma entidade de renderização — uma renderização isolada); aggrega lint verifica as convenções de publicação (nomenclatura, alinhamento com o diretório de categoria, prefixos de anotações e dimensão do incremento de versão). Nenhum deles emite artefactos; use validate para responder a «isto está correto?» e lint para responder a «isto segue a disciplina de publicação do catálogo?».
aggrega build segue o princípio do ponto de entrada único: a Release é a única entrada de compilação. aggrega build --release release.yaml lê os ponteiros aggregate: e manifest: da Release para localizar o resto da topologia, e produz saída por fronteira em dist/: uma fronteira com nome é renderizada no directory: que declara, ou em dist/boundaries/<boundary-name>/ quando não declara nenhum; uma Release que declare components: de nível superior em vez de fronteiras com nome é renderizada de forma plana em dist/. Todos os componentes que a topologia contém têm de pertencer a uma dessas fronteiras, e um componente que nenhuma delas contenha interrompe o build: um componente chega a uma fronteira ou por ser nomeado sob os components: dessa fronteira, com o ID que tem depois de os sub-Aggregates serem achatados, ou por estar dentro de um sub-Aggregate que a fronteira encaminha sob aggregates:. Um componente que não chegue a nenhuma seria renderizado fora de todas as fronteiras que a Release declara, sem obter de lado nenhum a sua localização de saída, onda de sincronização, anotações e infra: por componente, pelo que o build para e nomeia o componente em vez de emitir artefactos aos quais a configuração de fronteiras da Release nunca foi aplicada. A mesma relação é verificada do lado da Release: uma entrada de fronteira que nomeie um componente que a topologia não contém não configura nada, pelo que também interrompe o build e o diagnóstico indica o ID a que a entrada se dirigia. aggrega pull partilha a forma da Release como entrada; aggrega inspect recebe qualquer entidade — um nome de catálogo, um ficheiro de entidade, uma referência de registo ou uma Release; aggrega push recebe uma entidade de catálogo; aggrega validate e aggrega lint aceitam uma entidade de catálogo, uma Release (via --release) ou todo o catálogo; aggrega serve corre como processo de longa duração. A página de flags globais documenta as flags que se aplicam a todos os subcomandos.
O que uma versão pode alterar nos comandos, nas opções e nas ferramentas do assistente — e o que uma versão de correção nunca altera — está indicado em Compatibilidade.
Referência por comando
aggrega build— o comando de compilação principal. Lê um ponteiro de Release, resolve o Aggregate e o Manifest que referencia e emite artefactos compilados por fronteira.aggrega inspect— uma vista legível de qualquer entidade: uma entidade de catálogo pelo nome, um ficheiro de entidade pelo caminho, uma entidade publicada lida diretamente do seu registo ou uma Release totalmente resolvida, cujo grafo IR--ir-graphescreve em JSON e cujo fecho de dependências--closurereporta.aggrega pull— resolve as dependências de uma Release e escreve um lockfile por Release que fixa todas as dependências; guarda em cache entidades de catálogo e artefactos de origem.aggrega push— publica uma entidade de catálogo num registo OCI, assinando-a opcionalmente no momento do push.aggrega sign— assina um ou mais artefactos já publicados e anexa cada assinatura como referrer OCI.aggrega auth token— obtém interativamente um token de identidade OIDC e imprime-o no stdout, para uma única autenticação num lote de assinaturas keyless.aggrega registry— gere os registos que o workspace conhece e a sua política de confiança de assinaturas: acrescenta, lista e remove entradas, e constrói um índice local pesquisável dos metadados de catálogo publicados comregistry update.aggrega search— pesquisa no índice local dos registos configurados entidades de catálogo publicadas e plugins de CLI instaláveis, fazendo corresponder uma consulta de texto livre e filtros de facetas opcionais.aggrega validate— verifica a correção (esquema, pilares, resolução de referências,extends, capacidade de tipos de entrada, renderização isolada) em todo o catálogo, no fecho de dependências de uma Release (--release) ou numa entidade.aggrega lint— verifica as convenções de publicação em todo o catálogo, no fecho de dependências de uma Release (--release) ou numa entidade;--pre-publishacrescenta a barreira de incremento de versão com conhecimento do registo.aggrega serve— um daemon de compilador como serviço de longa duração (JSON-RPC sobre stdin/stdout) para integração com IDE.aggrega version— imprime a versão da CLI;-o jsonemite um objeto legível por máquina.aggrega get-schema— imprime o JSON Schema canónico de um tipo de entidade ou de contrato;--listnomeia todos os tipos. A forma autoritativa com base na qual escrever um ficheiro.aggrega scaffold— imprime um documento inicial para um tipo de entidade, derivado do esquema desse tipo: os campos obrigatórios, com os fixos preenchidos e um marcador de posição onde quer que seja necessário um valor. O rascunho não escreve nenhum ficheiro; redirecione a saída para onde quiser. Com--example, escreve em vez disso um dos exemplos executáveis da documentação num novo diretório, e--example --listnomeia-os.aggrega mcp— executa um servidor Model Context Protocol, sobre a entrada e saída padrão ou sobre HTTP, para que um cliente compatível com MCP se torne um assistente de autoria que conhece o Aggrega. Ver Escrever ficheiros do Aggrega.aggrega skills— instala a skill que ensina um assistente de IA a instalar e usar o Aggrega na pasta de skills desse assistente, para um projeto ou, com--global, para todos os projetos do utilizador.aggrega cache— inspeciona e mantém as caches em disco: lista o que contêm, recupera entradas da cache de artefactos que nenhum lockfile referencia, reduz a cache de módulos compilados até um limite de tamanho ou apaga todas as caches.aggrega config— inspeciona e gere a configuração que o Aggrega lê: mostra o que se aplica e que camada decidiu cada definição, cria uma configuração funcional e fixa no workspace as definições críticas para o build.aggrega deprecate— anexa um marcador de descontinuação assinado a um artefacto já publicado.aggrega edit-document— aplica a um documento uma única edição estruturada e delimitada, preservando todos os bytes em que não toca.aggrega explain— explica a condição de interrupção que um código nomeia.aggrega import— transforma a descrição de uma fonte externa em rascunhos de ficheiros de autoria do Aggrega.aggrega login— autentica-se num registo OCI e guarda a credencial quepush,pullelint --pre-publishapresentam.aggrega logout— remove uma credencial de registo guardada.aggrega pin— regista as fixações de conteúdo das entradas externas de uma entidade noentity.lockao lado dela.aggrega plugin— lista os plugins Wasm que a CLI consegue resolver, adiciona ou remove uma associação do workspace e verifica um guest antes de ser publicado.aggrega push-artifact— publica um artefacto de dados autónomo, como um pacote de documentação, num registo OCI sob o respetivo espaço de nomesdocs/.- Configuração — a que ficheiro pertence uma definição e como as camadas se combinam. Comece aqui: abre com os dois ficheiros de que a maioria dos projetos precisa e deixa para depois os mecanismos a que um projeto maior recorre.
- Flags globais — flags partilhadas pelos subcomandos (a raiz do workspace, o ficheiro de configuração global, a saída a cores e a saída simples acessível, e a postura offline). O modo offline também está acessível como definição de configuração e como variável de ambiente — ver Configuração, o esquema de configuração e as variáveis de ambiente.
- A fronteira do workspace — o que está dentro de um workspace, o que uma ligação simbólica que sai dele faz a cada tipo de caminho, os caminhos que saem de propósito e o que fazer quando um é recusado.
| Comando | Descrição |
|---|---|
aggrega auth | Gerir a identidade de assinatura |
aggrega build | Compilar um Aggregate e uma Release em artefactos nativos do provider em dist/ na raiz do workspace |
aggrega cache | Inspecionar e manter as caches em disco |
aggrega config | Inspecionar e gerir a configuração do workspace |
aggrega deprecate | Anexar um marcador de descontinuação assinado a um artefacto já publicado |
aggrega edit-document | Aplicar uma edição estruturada delimitada a um documento, preservando todos os bytes em que não toca |
aggrega explain | Explicar a condição de interrupção que um código nomeia |
aggrega get-schema | Imprimir o JSON Schema de um tipo de entidade ou de contrato |
aggrega import | Converter a descrição de uma origem externa em ficheiros de autoria Aggrega em rascunho |
aggrega inspect | Inspecionar uma entidade de catálogo pelo nome, um ficheiro de entidade pelo caminho ou uma entidade publicada pela sua referência de registo |
aggrega lint | Verificar as convenções de publicação do catálogo em todo o catálogo, numa Release ou numa entidade |
aggrega login | Autenticar-se num registo OCI e guardar a credencial |
aggrega logout | Remover uma credencial de registo guardada |
aggrega mcp | Executar um servidor Model Context Protocol sobre a entrada e saída padrão, ou sobre HTTP, para integração com assistentes de IA |
aggrega pin | Registar as fixações de conteúdo das entradas externas de uma entidade no entity.lock ao lado dela |
aggrega plugin | Inspecionar os plugins Wasm que a CLI consegue resolver |
aggrega pull | Resolver as dependências de catálogo e de origem para a cache e escrever o lockfile por Release |
aggrega push | Empacotar e publicar uma entidade de catálogo num registo OCI |
aggrega push-artifact | Publicar um artefacto de dados autónomo (como um pacote de documentação) num registo OCI |
aggrega registry | Gerir registos e a sua política de confiança de assinaturas |
aggrega scaffold | Rascunhar um documento inicial para um tipo de entidade, ou escrever um exemplo executável num novo diretório |
aggrega search | Pesquisar o índice local dos registos configurados |
aggrega serve | Correr como compilador como serviço de longa duração sobre JSON-RPC 2.0 em stdin/stdout |
aggrega sign | Assinar um ou mais artefactos já publicados e anexar as suas assinaturas |
aggrega skills | Instalar a skill do Aggrega num assistente de IA |
aggrega validate | Verificar a correção em todo o catálogo, numa Release ou numa entidade |
aggrega version | Imprimir a versão da CLI aggrega |
Argumentos posicionais e estado de saída
Todos os comandos recusam um argumento posicional de que não precisam, e reportam essa recusa através de um estado de saída diferente de zero em vez de terminarem como se a invocação fosse válida. A regra abrange os comandos que existem apenas para agrupar subcomandos, em que um nome de subcomando mal escrito chega como um posicional não reconhecido: a ajuda do comando é impressa e o estado de saída é diferente de zero, para que um erro de escrita numa superfície automatizada falhe de forma visível em vez de passar por uma execução bem-sucedida. O aggrega invocado com um comando não reconhecido comporta-se da mesma forma e, além disso, nomeia o comando correspondente mais próximo, quando existe um suficientemente próximo.
Um comando não reconhecido indica também como encontrar um plugin de CLI com esse nome. A resposta vem do índice local do registo predefinido que aggrega registry update constrói e aggrega search lê, pelo que chega de imediato e a palavra mal escrita nunca é enviada a um registo, com ou sem ligação. Quando o índice contém um plugin de CLI com esse nome, a mensagem nomeia o comando aggrega plugin add cli <name> que o instala. Quando o índice não contém nenhum, nomeia a pesquisa que procura um, aggrega search <name> --kind plugin --plugin-type cli. Quando ainda não foi construído nenhum índice, nomeia aggrega plugin add cli <name>, que procura o plugin por esse nome no registo e recusa quando nenhum está publicado. Qualquer um dos dois comandos leva o nome entre aspas para a shell quando é necessário.
Quando os posicionais têm significado, a página de referência de cada comando documenta o que aceita. Um plugin de CLI instalado é a exceção deliberada: o seu comando reserva para si a análise dos argumentos, pelo que todo o vetor de argumentos é encaminhado para o plugin, que é o único analisador dos seus próprios argumentos — e o estado de saída do próprio plugin é o que a invocação devolve.
Progresso, e quanto tempo um comando espera por um registo
Um comando que espera indica aquilo por que está à espera. Sempre que um comando espera por um registo, por uma transferência ou pela primeira compilação de um plugin, mostra esse passo na saída de erro padrão, tal como aggrega build e aggrega pull mostram os seus: num terminal, uma linha que nomeia o passo com um indicador giratório e o tempo decorrido até então, assinalada quando o passo termina e deixada por assinalar quando o passo falhou; num terminal que não consegue redesenhar no lugar, ou com --plain, uma linha por passo à medida que termina, com o respetivo tempo. Quando a saída de erro padrão não é um terminal, nada é mostrado, e nada do que um comando escreve na saída padrão muda em qualquer dos casos. Um passo só é mostrado enquanto o comando está realmente à espera dele, pelo que uma execução servida a partir da cache não mostra nada, e a compilação de um plugin só é mostrada quando demora o suficiente para ser uma compilação real e não uma que estava em cache.
Os comandos que mostram os seus passos desta forma, além do 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
Nenhum pedido espera indefinidamente por um servidor. Um pedido espera no máximo 30 segundos que o servidor comece a sua resposta depois de o pedido ter sido enviado na totalidade, e no máximo 30 segundos pela parte seguinte de uma resposta que já está a chegar. Um servidor que faz um pedido esperar mais tempo é recusado com E0376, que indica o servidor e a espera. Só a espera é limitada: uma transferência ou um envio que continua a avançar demora o tempo que demorar. Um chart do Helm que o source: de uma Recipe obtém por HTTPS está sujeito apenas à primeira das duas esperas, e a sua expiração é comunicada nas palavras da própria biblioteca de rede, e não com E0376. Um pedido que um comando já repete quando o tempo se esgota — uma leitura durante aggrega registry update, uma escrita durante uma publicação — é repetido antes de a recusa ser comunicada.
O percurso da listagem completa de repositórios de um registo termina em cinco minutos. Alguns registos reúnem todos os repositórios que contêm antes sequer de responderem a um pedido de listagem, pelo que cada página da listagem é aguardada durante todo o tempo que o percurso pode durar, e não durante 30 segundos; uma listagem que não terminou ao fim de cinco minutos é interrompida e recusada com E0377. aggrega plugin add percorre a listagem apenas quando nenhum plugin tem exatamente o nome que recebeu, para encontrar um cujo nome o contenha, pelo que nomear o plugin exatamente nunca fica à espera do percurso.
Um registo que pede para abrandar é aguardado, até o ter pedido durante cinco minutos sem interrupção. Um comando espera o tempo que esse registo pedir, envia-lhe menos pedidos em simultâneo e mostra a espera juntamente com o resto do seu progresso; um registo que durante cinco minutos não responde mais nada além de «abrande» é recusado com E0378. Um registo que pede para abrandar descreve como.
Os três limites são fixos; não existe nenhuma definição que os altere.
Os caminhos escritos e a fronteira do workspace
Um caminho escrito na linha de comandos — um --release, um --catalog, um --output-dir, um ficheiro a validar, analisar com lint, fixar ou publicar, um --workspace-root — é usado para onde leva, dentro ou fora do workspace, através de qualquer ligação pelo caminho. O que o comando lê e escreve depois por conta própria fica confinado ao workspace, seja quem for que o execute: não lê os ficheiros de configuração do workspace, um documento de catálogo, um documento ao lado de uma Release ou o lockfile de uma Release através de uma ligação que saia do workspace, não segue um caminho que uma Release ou um Manifest escreva para fora dele, nem escreve a sua saída, o seu lockfile ou a sua cache através de uma ligação dessas. Um diretório indicado fora do workspace fica confinado da mesma forma quanto ao que está abaixo dele, e uma Release indicada fora do workspace só chega a ficheiros no seu próprio diretório. aggrega edit-document é o único comando cujo caminho escrito também fica confinado: só edita um documento que o workspace contém. A fronteira do workspace enuncia a regra, os caminhos que saem de propósito e a solução para cada recusa.
Pesquisar o índice do catálogo
aggrega search [query] procura entidades publicadas nos registos que o workspace conhece. O [query] opcional é uma subcadeia, sem distinção entre maiúsculas e minúsculas, comparada com o nome e a descrição de cada entidade. Os filtros de facetas restringem o conjunto de resultados:
--kindrestringe a um ou mais tipos de entidade (component,feature,recipe,featurerecipe,workload,plugin); é repetível e não distingue maiúsculas de minúsculas, e os tipos combinam-se por OU.-l/--selectorfiltra pelas etiquetas de catálogo da entidade. A categoria é uma etiqueta, não uma flag dedicada:-l component.aggrega.ai/category=datastore.--capabilitye--plugin-typefiltram plugins por uma capacidade ou tipo de socket declarado;--capabilityé repetível e combina-se por OU.--registrylimita a pesquisa a um único registo, por host ou alias amigável; por predefinição, são pesquisados todos os registos configurados.--limitlimita o número de resultados.-o/--outputseleciona o formato de saída:table(a predefinição, legível por pessoas),json(um array legível por máquina) ounames(identificadores simples, um por linha).
A pesquisa lê sempre o índice local — o instantâneo offline que aggrega registry update constrói e atualiza. Não contacta nenhuma rede nem obtém nada a pedido. Quando o índice não existe, o comando falha e indica que se execute primeiro aggrega registry update. Cada execução imprime no erro padrão uma linha de atualidade «last updated» por registo, para que a saída json e names na saída padrão se mantenha limpa para scripts.
Conclusão automática da shell
aggrega completion <shell> imprime no stdout um script de conclusão automática para bash, zsh, fish ou powershell. O script é gerado a partir da árvore de comandos ativa da CLI no momento em que é executado, pelo que reflete sempre os comandos e as flags do binário que o produziu — não há nenhum ficheiro estático a regenerar à medida que a CLI cresce.
Para experimentar a conclusão automática na sessão atual sem instalar nada, carregue o script diretamente com source:
source <(aggrega completion bash)Para instalar a conclusão automática de forma permanente, escreva o script no local que a shell lê no arranque.
bash
A conclusão automática do Bash depende do pacote bash-completion; instale-o através do gestor de pacotes do sistema operativo se ainda não estiver presente.
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
Se a conclusão automática ainda não estiver ativada na shell, ative-a uma vez:
echo "autoload -U compinit; compinit" >> ~/.zshrcEm seguida, escreva o script de conclusão automática num diretório do seu 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
Acrescente o script gerado ao perfil do PowerShell para que seja carregado em todas as sessões:
aggrega completion powershell >> $PROFILEInicie uma nova shell para que a conclusão automática instalada tenha efeito.