Visão geral da CLI
A CLI aggrega é o ponto de entrada do compilador. Toda interação com o Aggrega — compilar um Aggregate em artefatos implantáveis, inspecionar o catálogo ou a 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 atender a uma IDE — passa por um subcomando de aggrega. Este conjunto de capítulos aborda as flags, as entradas e as saídas de cada subcomando.
aggrega validate e aggrega lint são verificadores complementares cujos três escopos espelham um ao outro — o catálogo inteiro, o fechamento de dependências de uma Release ou uma única entidade. aggrega validate verifica a correção (schema, pilares, resolução de referências, extends, capacidade do provider para o tipo de entrada 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ção e tamanho do incremento de versão). Nenhum dos dois emite artefatos; use validate para responder “isto está correto?” e lint para responder “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 restante da topologia e produz saída por fronteira sob dist/: uma fronteira nomeada é gerada sob o directory: declarado, ou sob dist/boundaries/<boundary-name>/ quando não declara nenhum; uma Release que declara components: de nível superior em vez de fronteiras nomeadas é gerada de forma plana sob dist/. Todo componente da topologia precisa pertencer a uma dessas fronteiras, e um componente que nenhuma delas contém interrompe o build: um componente chega a uma fronteira ou por ser nomeado sob os components: dessa fronteira, com o id que carrega depois que os sub-Aggregates são achatados, ou por estar dentro de um sub-Aggregate que a fronteira encaminha sob aggregates:. Um componente que não chega por nenhum dos dois caminhos seria gerado fora de toda fronteira declarada pela Release, sem nenhuma origem para seu local de saída, sua sync wave, suas anotações e seu infra: por componente; por isso o build para e nomeia o componente em vez de emitir artefatos 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 nomeia um componente que a topologia não contém não configura nada, então também interrompe o build, e o diagnóstico informa o id que a entrada endereçava. aggrega pull compartilha a forma com a Release como entrada; aggrega inspect recebe qualquer entidade — um nome de catálogo, um arquivo de entidade, uma referência de registry 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 o catálogo inteiro; aggrega serve é executado como um processo de longa duração. A página de flags globais documenta as flags que se aplicam a todos os subcomandos.
O que uma release pode mudar nos comandos, nas flags e nas ferramentas do assistente — e o que uma release de patch nunca muda — está descrito em Compatibilidade.
Referência por comando
aggrega build— o comando de compilação principal. Lê um ponteiro para uma Release, resolve o Aggregate e o Manifest que ela referencia e emite artefatos compilados por fronteira.aggrega inspect— uma visão legível de qualquer entidade: uma entidade de catálogo por nome, um arquivo de entidade por caminho, uma entidade publicada lida diretamente do seu registry ou uma Release totalmente resolvida, cujo IR Graph--ir-graphgrava como JSON e cujo fechamento de dependências--closureinforma.aggrega pull— resolve as dependências de uma Release e escreve um lockfile por Release que fixa cada dependência; armazena em cache entidades de catálogo e artefatos de origem.aggrega push— publica uma entidade de catálogo em um registry OCI, opcionalmente assinando-a no momento do push.aggrega sign— assina um ou mais artefatos já publicados e anexa cada assinatura como referrer OCI.aggrega auth token— obtém de forma interativa um token de identidade OIDC e o imprime em stdout, para uma única autenticação válida para um lote de assinaturas keyless.aggrega registry— gerencia os registries que o workspace conhece e sua política de confiança de assinaturas: adiciona, lista e remove entradas, e constrói comregistry updateum índice local pesquisável dos metadados de catálogo publicados.aggrega search— pesquisa no índice local dos registries configurados entidades de catálogo publicadas e plugins de CLI instaláveis, com base em uma consulta de texto livre e filtros de facetas opcionais.aggrega validate— verifica a correção (schema, pilares, resolução de referências,extends, capacidade para o tipo de entrada, renderização isolada) no catálogo inteiro, no fechamento de dependências de uma Release (--release) ou em uma única entidade.aggrega lint— verifica as convenções de publicação no catálogo inteiro, no fechamento de dependências de uma Release (--release) ou em uma única entidade;--pre-publishadiciona a verificação do incremento de versão que consulta o registry.aggrega serve— um daemon de longa duração que oferece o compilador como serviço (JSON-RPC sobre stdin/stdout) para integração com IDEs.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 de referência com base na qual se escreve um arquivo.aggrega scaffold— imprime um documento inicial para um tipo de entidade, derivado do schema desse tipo: os campos obrigatórios, com os fixos já preenchidos e um placeholder onde quer que um valor seja necessário. O rascunho não grava nenhum arquivo; redirecione a saída para onde quiser. Com--example, ele grava em vez disso um dos exemplos executáveis da documentação em um novo diretório, e--example --listos nomeia.aggrega mcp— executa um servidor Model Context Protocol, sobre a entrada e a saída padrão ou sobre HTTP, para que um cliente compatível com MCP se torne um assistente de escrita que conhece o Aggrega. Veja Escrever arquivos 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 seus projetos.aggrega cache— inspeciona e mantém os caches em disco: lista o que eles contêm, recupera entradas do cache de artefatos que nenhum lockfile referencia, reduz o cache de módulos compilados até um limite de tamanho ou apaga todos os caches.aggrega config— inspeciona e gerencia a configuração que o Aggrega lê: mostra o que se aplica e qual camada decidiu cada configuração, cria uma configuração funcional e congela no workspace as configurações críticas para o build.aggrega deprecate— anexa um marcador de descontinuação assinado a um artefato já publicado.aggrega edit-document— aplica a um documento uma única edição estruturada e delimitada, preservando cada byte 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 arquivos de autoria do Aggrega.aggrega login— autentica-se em um registry OCI e armazena a credencial quepush,pullelint --pre-publishapresentam.aggrega logout— remove uma credencial de registry armazenada.aggrega pin— registra os pins 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 um vínculo do workspace e verifica um guest antes que você o publique.aggrega push-artifact— publica um artefato de dados independente, como um pacote de documentação, em um registry OCI sob o namespacedocs/dele.- Configuração — em qual arquivo uma configuração deve ficar, e como as camadas se combinam. Comece por aqui: a página abre com os dois arquivos de que a maioria dos projetos precisa e deixa para depois os mecanismos a que um projeto maior recorre.
- Flags globais — flags compartilhadas entre os subcomandos (a raiz do workspace, o arquivo de configuração global, a saída colorida e a saída simples acessível, e o modo offline). O modo offline também está disponível como configuração e como variável de ambiente — veja Configuração, o schema de configuração e as variáveis de ambiente.
- A fronteira do workspace — o que fica dentro de um workspace, o que um link simbólico que sai dele faz com cada tipo de caminho, os caminhos que saem de propósito e o que fazer quando um deles é recusado.
| Comando | Descrição |
|---|---|
aggrega auth | Gerenciar a identidade de assinatura |
aggrega build | Compilar um Aggregate e uma Release em artefatos nativos do provider sob dist/ na raiz do workspace |
aggrega cache | Inspecionar e manter os caches em disco |
aggrega config | Inspecionar e gerenciar a configuração do workspace |
aggrega deprecate | Anexar um marcador de descontinuação assinado a um artefato já publicado |
aggrega edit-document | Aplicar a um documento uma edição estruturada e delimitada, preservando cada byte que ela 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 | Transformar a descrição de uma fonte externa em rascunhos de arquivos de escrita do Aggrega |
aggrega inspect | Inspecionar uma entidade de catálogo pelo nome, um arquivo de entidade pelo caminho ou uma entidade publicada pela sua referência de registry |
aggrega lint | Verificar as convenções de publicação do catálogo no catálogo, em uma Release ou em uma única entidade |
aggrega login | Autenticar-se em um registry OCI e armazenar a credencial |
aggrega logout | Remover uma credencial de registry armazenada |
aggrega mcp | Executar um servidor Model Context Protocol sobre a entrada e a saída padrão, ou sobre HTTP, para integração com assistentes de IA |
aggrega pin | Registrar os pins 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 no cache e escrever o lockfile por Release |
aggrega push | Empacotar e publicar uma entidade de catálogo em um registry OCI |
aggrega push-artifact | Publicar um artefato de dados independente (como um pacote de documentação) em um registry OCI |
aggrega registry | Gerenciar registries e sua política de confiança de assinaturas |
aggrega scaffold | Rascunhar um documento inicial para um tipo de entidade, ou gravar um exemplo executável em um novo diretório |
aggrega search | Pesquisar no índice local dos registries configurados |
aggrega serve | Executar como compilador-como-serviço de longa duração sobre JSON-RPC 2.0 em stdin/stdout |
aggrega sign | Assinar um ou mais artefatos já publicados e anexar suas assinaturas |
aggrega skills | Instalar a skill do Aggrega em um assistente de IA |
aggrega validate | Verificar a correção no catálogo, em uma Release ou em uma única entidade |
aggrega version | Imprimir a versão da CLI aggrega |
Argumentos posicionais e status de saída
Todo comando recusa um argumento posicional que não tem uso para ele e informa essa recusa por meio de um status de saída diferente de zero, em vez de concluir como se a invocação fosse válida. A regra abrange os comandos que existem apenas para agrupar subcomandos, nos quais um nome de subcomando digitado errado chega como um argumento posicional não reconhecido: a ajuda do comando é exibida e o status de saída é diferente de zero, de modo que um erro de digitação em um script falha de forma visível em vez de parecer uma execução bem-sucedida. aggrega invocado com um comando não reconhecido se comporta da mesma forma e, além disso, indica o comando mais parecido, quando há um suficientemente parecido.
Um comando não reconhecido também diz como encontrar um plugin de CLI com esse nome. A resposta vem do índice local do registry padrão que aggrega registry update constrói e aggrega search lê, então ela chega na hora e a palavra digitada errado nunca é enviada a um registry, online ou offline. Quando o índice contém um plugin de CLI com esse nome, a mensagem indica o comando aggrega plugin add cli <name> que o instala. Quando o índice não contém nenhum, indica a busca que procura um, aggrega search <name> --kind plugin --plugin-type cli. Quando nenhum índice foi construído ainda, indica aggrega plugin add cli <name>, que procura o plugin por esse nome no registry e recusa quando nenhum está publicado. Qualquer um dos dois comandos traz o nome entre aspas para o shell quando necessário.
Onde os argumentos posicionais têm significado, a página de referência de cada comando documenta o que ele aceita. Um plugin de CLI instalado é a exceção deliberada: seu comando reserva para si a análise dos argumentos, de modo que todo o vetor de argumentos é repassado ao plugin, que é o único a analisar seus próprios argumentos — e o status de saída do próprio plugin é o que a invocação retorna.
Progresso e quanto tempo um comando espera por um registry
Um comando que espera diz pelo que está esperando. Sempre que um comando espera por um registry, por um download ou pela primeira compilação de um plugin, ele mostra essa etapa na saída de erro padrão, da mesma forma que aggrega build e aggrega pull mostram as suas: em um terminal, uma linha que nomeia a etapa com um indicador giratório e o tempo decorrido até então, marcada quando a etapa termina e deixada sem marca quando a etapa falha; em um terminal que não consegue redesenhar no lugar, ou com --plain, uma linha por etapa quando ela termina, com seu tempo. Quando a saída de erro padrão não é um terminal, nada é mostrado, e nada do que um comando imprime na saída padrão muda em nenhum dos casos. Uma etapa só é mostrada enquanto o comando realmente espera por ela, então uma execução atendida pelo 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 em cache.
Os comandos que mostram suas etapas dessa 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
Nenhuma requisição espera por um servidor indefinidamente. Uma requisição espera no máximo 30 segundos para que o servidor comece sua resposta depois que a requisição foi enviada por completo, e no máximo 30 segundos pela próxima parte de uma resposta que já está chegando. Um servidor que deixa uma requisição esperando por mais tempo é recusado com E0376, que nomeia o servidor e a espera. Só a espera é limitada: um download ou um upload que continua avançando leva o tempo que levar. Um chart do Helm que o source: de uma Recipe busca por HTTPS está sujeito apenas à primeira das duas esperas, e sua expiração é informada com as palavras da própria biblioteca de rede, e não com E0376. Uma requisição que um comando já repete quando o tempo se esgota — uma leitura durante aggrega registry update, uma escrita durante uma publicação — é repetida antes que a recusa seja informada.
A varredura da lista completa de repositórios de um registry termina em até cinco minutos. Alguns registries reúnem todos os repositórios que contêm antes mesmo de responder a uma requisição de listagem, então cada página da listagem é aguardada pelo tempo que a varredura pode levar, e não por 30 segundos; uma listagem que não terminou após cinco minutos é interrompida e recusada com E0377. aggrega plugin add percorre a listagem somente quando nenhum plugin tem exatamente o nome que recebeu, para encontrar um cujo nome o contenha; por isso, nomear o plugin exatamente nunca espera pela varredura.
Um registry que pede para desacelerar é aguardado, até que tenha pedido isso por cinco minutos sem interrupção. Um comando aguarda o tempo que esse registry pedir, envia a ele menos requisições ao mesmo tempo e mostra a espera junto com o restante do seu progresso; um registry que por cinco minutos não responde nada além de “desacelere” é recusado com E0378. Um registry que pede para desacelerar descreve como.
Os três limites são fixos; não há configuração que os altere.
Os caminhos que você digita e o limite do workspace
Um caminho que você digita na linha de comando — um --release, um --catalog, um --output-dir, um arquivo a validar, analisar com o linter, fixar ou publicar, um --workspace-root — é usado onde ele leva, dentro ou fora do workspace, passando por qualquer link no caminho. O que o comando então lê e grava por conta própria fica restrito ao workspace, seja quem for que o execute: ele não lê os arquivos de configuração do workspace, um documento do catálogo, um documento ao lado de uma Release nem o lockfile de uma Release por meio de um link que sai do workspace, não segue um caminho que uma Release ou um Manifest grava fora dele, nem grava sua saída, seu lockfile ou seu cache por meio de um link assim. Um diretório que você indica fora do workspace fica restrito da mesma forma quanto ao que está abaixo dele, e uma Release que você indica fora do workspace alcança apenas arquivos em seu próprio diretório. aggrega edit-document é o único comando cujo caminho digitado também fica restrito: ele edita apenas um documento contido no workspace. O limite do workspace apresenta a regra, os caminhos que saem de propósito e a solução para cada recusa.
Pesquisar no índice do catálogo
aggrega search [query] procura entidades publicadas nos registries que o workspace conhece. O parâmetro opcional [query] é uma substring, sem distinção entre maiúsculas e minúsculas, comparada com o nome e a descrição de cada entidade. Filtros de faceta restringem o conjunto de resultados:
--kindrestringe a um ou mais tipos de entidade (component,feature,recipe,featurerecipe,workload,plugin); pode ser repetido, não diferencia maiúsculas de minúsculas, e os tipos se combinam com OR.-l/--selectorfiltra pelos rótulos de catálogo da entidade. A categoria é um rótulo, não um flag dedicado:-l component.aggrega.ai/category=datastore.--capabilitye--plugin-typefiltram plugins por uma capacidade declarada ou por tipo de socket;--capabilitypode ser repetido e se combina com OR.--registrylimita a pesquisa a um único registry, indicado por host ou por um alias; por padrão, todos os registries configurados são pesquisados.--limitlimita o número de resultados.-o/--outputseleciona o formato de saída:table(o padrão, legível por pessoas),json(um array legível por máquina) ounames(apenas identificadores, um por linha).
A pesquisa sempre lê o índice local — o snapshot offline que aggrega registry update cria e atualiza. Ela não acessa nenhuma rede e não busca nada sob demanda. Quando o índice não existe, o comando falha e pede que você execute primeiro aggrega registry update. Cada execução imprime na saída de erro padrão, para cada registry, uma linha de atualização “last updated”, de modo que a saída json e names na saída padrão permanece limpa para scripts.
Autocompletar do shell
aggrega completion <shell> imprime no stdout um script de autocompletar para bash, zsh, fish ou powershell. O script é gerado a partir da árvore de comandos ativa da CLI no momento em que você o executa, então ele sempre reflete os comandos e flags do binário que o produziu — não há nenhum arquivo estático para gerar novamente à medida que a CLI cresce.
Para experimentar o autocompletar na sua sessão atual sem instalar nada, carregue o script diretamente com source:
source <(aggrega completion bash)Para instalar o autocompletar de forma permanente, grave o script no local que o seu shell lê ao iniciar.
bash
O autocompletar do Bash depende do pacote bash-completion; instale-o pelo gerenciador de pacotes do seu sistema operacional se ele 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 o autocompletar ainda não estiver habilitado no seu shell, habilite-o uma vez:
echo "autoload -U compinit; compinit" >> ~/.zshrcDepois, grave o script de autocompletar em um 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 seu perfil do PowerShell para que ele seja carregado em todas as sessões:
aggrega completion powershell >> $PROFILEInicie um novo shell para que o autocompletar instalado entre em vigor.