aggrega config
Inspecionar e gerenciar a configuração do workspace
Sinopse
aggrega configDescrição
Inspect and manage the configuration Aggrega reads.
Most projects need two files.
One .aggrega-config.yaml at your project root, carrying a "workspace:" block —that block is what marks the root — holds how this project builds: its catalogdirectories, its provider bindings, which lint rules it relaxes. It iscommitted, so a teammate who clones the project builds it the same way.
One global file is shared across every workspace on this machine:~/.config/aggrega/config.yaml, or on Windows aggrega\config.yaml inside thedirectory the APPDATA environment variable names. It holds what belongs to themachine rather than to any one project: the registries you pull from and thesignature trust policy for each, how large the compiled-module store may grow,any command extension you have installed. It loads automatically when it isthere, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable winsover both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity tokenis never a field in either file; it is supplied by environment variable or flagat the moment it is needed.
Because the effective configuration is assembled rather than written anywhere,"aggrega config show" is how you see what actually applies, and --origin is howyou find out which layer each setting came from. "aggrega config init" seeds aworking configuration, and "aggrega config capture" freezes the effectivebuild-critical settings into this workspace so a build does not depend on aglobal file that is not committed.
Larger projects have more to work with. None of it is needed to start, and eachpiece exists for the shape it solves:
More than one file inside a project. Every .aggrega-config.yaml from the project root down to the directory you run in contributes, a nearer file overriding a farther one. Only a file carrying "workspace:" marks the root; one without it contributes settings without anchoring anything.
Extending a list instead of replacing it. A nearer file's list replaces the farther one's. The companions catalog_dirs_append, governance_append, linter_append, importer_append and providers_append concatenate onto the resolved list at each layer instead of shadowing it.
A file your pipeline owns. .aggrega-config-append-ci.yaml may sit beside the hand-authored file in any of those directories, so automation can overwrite it wholesale without touching what a person wrote. It is additive only: it removes nothing and overrides no scalar, and a scalar key written in it is ignored and named in a warning. It never marks a root.
A relative path anchors to the file that declared it. A catalog directory, a local plugin path, or an entry under a plugin's with.sources resolves against the directory of the config file it was written in — not the project root, and not the directory you ran the command from. So the same "./catalog" names a different directory depending on which file carries it. Two settings sit outside this rule: artifact_cache_dir is interpreted relative to the project root wherever you run from, and AGGREGA_CATALOG_DIRS has no declaring file at all, so supply absolute paths in it.
The other root markers. A "workspace:" block wins outright at whatever depth it sits. Failing one, the nearest .aggrega/ directory or aggregate*.yaml, release*.yaml or manifest*.yaml file anchors the root, in that order within a directory; failing everything, your working directory is used. --workspace-root skips discovery entirely.
Naming the global file. --config <path> wins over the AGGREGA_CONFIG environment variable, which wins over the default location. Both name a file deliberately, so a path either gives that does not exist is a loud error rather than a silent fallback. Whichever file resolves is also the one a config-writing command writes when it writes globally.Subcomandos
| Comando | Descrição |
|---|---|
aggrega config capture | Congela neste workspace a configuração efetiva crítica para o build |
aggrega config init | Inicializa uma configuração funcional com um registry e sua política de confiança |
aggrega config show | Mostra a configuração efetiva e de onde veio cada configuração |
Descrição de aggrega config capture
Write the effective build-critical configuration into this project's workspaceconfig file, so the workspace builds identically without relying on themachine's global configuration.
The build-critical subset is the configuration a build participates in: a set ofplugin socket attachments and the catalog directories. By default the capturedsockets are only those that determine therendered output — the provider bindings and the transform-role governance attachments — since only those musttravel with the project for byte-identical output. Pass --all-plugins to alsofreeze the verdict-role governance, linter, and importer sockets, which otherwise stay free tovary by environment. Each field is written at its effective value — the valuethat resolves right now with the global configuration and the workspace treemerged together — so a binding that today comes only from the global config ismaterialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are notcaptured: they stay in the global config by their nature. Capture always writesthis project's workspace config file. Running it again on an unchangedconfiguration rewrites the same file byte-for-byte. Run in a folder that is notinside a workspace, with no --workspace-root naming one, it writes nothing andexits with an error saying so.Flags de aggrega config capture
| Flag | Padrão | Descrição |
|---|---|---|
--all-plugins | false | Captura todos os sockets de plugins, incluindo os controles de governança com papel verdict, de linter e de importer. Sem ela, capture congela apenas os sockets que determinam a saída renderizada (as vinculações de providers e os anexos de governança com papel transform). |
Descrição de aggrega config init
Seed a working configuration by registering a registry and its signature trustpolicy, so a fresh machine can pull and verify signed artifacts without editingYAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signaturesrequired and the official trusted identities. The registry's advertised trustpolicy is fetched once from its own origin and pinned locally — trust-on-first-use; when the hub is unreachable, advertises nothing, or the workspace isoffline, its built-in official baseline is written instead, so init stillproduces a usable config offline. Pass --registry to seed a different registry(for an air-gapped or private hub). Such a registry has no built-in baseline,so seeding it while the workspace is offline is refused: init takes noidentities or key to pin by hand, so register it once while online, or add itwith "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace bydefault; pass --workspace to write it to this project's workspace configinstead. If the target config file already exists, init refuses rather thanoverwrite it — pass --force to write anyway (the registry entry is merged intothe existing file, other settings preserved).
Before anything else, init says where things are: the configuration file itcreated — or, under --force, the one already there that it wrote into — andthe directory the machine-wide caches are kept in. On Windows that directory isaggrega\cache inside the directory the LOCALAPPDATA environment variable names;elsewhere it is a directory named aggrega under the per-user cache directory:~/.cache/aggrega on Linux unless XDG_CACHE_HOME names another, and~/Library/Caches/aggrega on macOS.
A seeded configuration is a document you own and go on editing, so --dry-run doeseverything init does except write: it hands the content back, creating andmodifying nothing. The answer names the file the content is for — which mattershere, because the target is the global config unless --workspace selects thisproject's own. A caller that keeps its own document model puts the content there,where it is visible before it is saved and can be amended or undone. The registryis still contacted for its advertised trust policy, because the policy in thatcontent is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing configfile exactly as a write refuses it, and for the same reason. So its exit codepredicts the write's: if the dry run refuses, init would have refused. Pass--force alongside it to see the merge an overwriting write would produce.
Under --dry-run standard output carries that content and nothing else, so it staysparseable. A registry seeded with no trust policy, because it advertises none,still produces its notice, on standard error: read that stream too, or thatconfiguration arrives without the advice to pin identities by hand. A pinnedpolicy, whether advertised or the hub's built-in baseline, is in the contentitself and produces no notice.Flags de aggrega config init
| Flag | Padrão | Descrição |
|---|---|---|
--dry-run | false | Faz tudo exceto gravar: devolve a configuração inicializada como conteúdo, nomeando o arquivo a que ela se destina, e não cria nem modifica nada. Todo o restante do comportamento é o da gravação, então um arquivo de configuração existente é recusado exatamente como uma gravação o recusa — passe —force junto para obter a mesclagem que uma gravação com sobrescrita produziria. |
--force | false | Sobrescreve um arquivo de configuração existente. Sem ela, init recusa quando o arquivo de destino já existe. |
--global | false | Grava a entrada na configuração global compartilhada por todos os workspaces. Este é o padrão. |
--registry | hub.aggrega.ai | Host do registry a ser inicializado com sua política de confiança. O padrão é o hub oficial. |
--workspace | false | Grava a entrada na configuração do workspace deste projeto em vez da configuração global. |
Descrição de aggrega config show
Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overridesthat contributed, lowest precedence first, then prints the effective mergedconfiguration — the global config, the workspace-tree cascade, and anyenvironment override combined into what applies right now.
Pass --global or --workspace to print a single layer's own file bytes verbatim,preserving its comments and formatting; when that layer's file does not exist itsays so rather than failing. The two are mutually exclusive.
Pass --origin to annotate each effective setting with the layer it came from —a command-line flag, an environment variable, a config file, or the built-indefaults, highest precedence first. A flag is named as the reader typed it, soa setting a flag decided reports that flag as its source. A setting isattributed to the highest-precedence layer that sets it, whatever value thatlayer writes: a file restating the default is the file named, not the built-indefaults. List and map settings are attributed as a whole. The signingrequirement is the one exception: any layer may turn it on and none can turn itoff, so it names the first layer that turns it on.Flags de aggrega config show
| Flag | Padrão | Descrição |
|---|---|---|
--global | false | Imprime literalmente os bytes do arquivo de configuração global, preservando seus comentários e sua formatação. |
--origin | false | Anota cada configuração efetiva com a camada de onde veio (uma flag de linha de comando, uma variável de ambiente, um arquivo de configuração ou os padrões integrados). |
--workspace | false | Imprime literalmente os bytes do arquivo de configuração do workspace deste projeto, preservando seus comentários e sua formatação. |
O que ele faz
Os subcomandos config inicializam, inspecionam e congelam a configuração que rege um build. Para saber em qual arquivo uma configuração deve ficar e como as camadas se combinam, consulte Configuração — ela começa pelos dois arquivos de que a maioria dos projetos precisa e deixa o restante para depois.
config init — inicializar uma configuração funcional
aggrega config init inicializa uma configuração em uma máquina nova registrando um registry e sua política de confiança de assinaturas, para que artefatos assinados sejam baixados e verificados sem editar YAML manualmente. Por padrão, registra o hub oficial (hub.aggrega.ai) com assinaturas obrigatórias e suas identidades confiáveis oficiais. A política de confiança anunciada pelo registry é buscada uma vez na própria origem e fixada localmente (trust-on-first-use); quando o hub está inacessível, não anuncia nada ou o workspace está offline, sua linha de base oficial integrada é gravada em vez disso, de modo que init ainda produz uma configuração utilizável offline.
Antes de qualquer outra coisa, init diz onde as coisas estão. A inicialização de uma máquina Linux nova começa com:
Created the global configuration file at /home/you/.config/aggrega/config.yamlMachine-wide caches are kept in /home/you/.cache/aggregae a de uma máquina Windows nova com:
Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yamlMachine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cacheA primeira linha nomeia o arquivo de configuração que init gravou: Created quando o arquivo não existia, e Using quando existia e --force permitiu que init gravasse nele; com --workspace, ela nomeia o arquivo de configuração do workspace em vez do global. A segunda nomeia o diretório em que os caches de toda a máquina — plugins compilados e suas descrições — são mantidos, que é onde cada plataforma mantém os caches de um usuário; Quais caches pertencem a este projeto e quais à máquina apresenta a regra por plataforma. Cada linha termina com seu caminho e nada depois dele, para que o caminho possa ser copiado como está. As linhas seguintes são as do próprio registro: o que a busca da política de confiança encontrou e em qual arquivo o registry foi registrado. Uma inicialização recusada não imprime nenhuma das duas linhas, já que não criou nada, e --dry-run também não, cuja saída padrão contém apenas o conteúdo que ele devolve.
--registry <host>inicializa um registry diferente — um hub isolado (air-gapped) ou privado — em vez do oficial. Um registry assim não tem linha de base integrada, então, quando ele não anuncia nada, a entrada é gravada sem política, e em um workspace offline sua inicialização é recusada (código curtoE0310): a política não pode ser buscada, einitnão aceita--identitynem--keypara fixar uma manualmente. Inicialize-o uma vez enquanto estiver online, ou adicione-o comaggrega registry adde uma política fornecida por você.- Se o arquivo de destino já existe,
initrecusa em vez de sobrescrevê-lo;--forcegrava mesmo assim, mesclando a entrada do registry no arquivo existente e preservando as demais configurações. --dry-runfaz tudo o queinitfaz, exceto gravar. Ele devolve a configuração inicializada como conteúdo, sem criar nem modificar nada, e a resposta nomeia o arquivo a que o conteúdo se destina — o que importa aqui, porque o destino é a configuração global, a menos que--workspaceselecione a deste projeto. Um chamador que mantém o próprio modelo de documento, como um editor, coloca o conteúdo ali, onde ele fica visível antes de ser salvo e pode ser alterado ou desfeito.- Como um dry run faz todo o restante do que
initfaz, seu código de saída antecipa o da gravação. Ele recusa um arquivo de configuração existente exatamente como uma gravação o recusa, e pelo mesmo motivo, então você pode usá-lo para perguntar seinitteria sucesso antes de se comprometer com a alteração. Para ver o documento que uma gravação com sobrescrita produziria, passe--forcejunto:--force --dry-runinforma a mesclagem e continua sem gravar nada. - O registry ainda é contatado para obter sua política de confiança anunciada, porque a política no conteúdo informado é a política que uma gravação teria fixado. Um dry run faz à própria origem desse registry a mesma única solicitação não autenticada que uma gravação faz.
- Com
--dry-run, a saída padrão contém esse conteúdo e nada mais, para continuar podendo ser analisada. A única coisa que o conteúdo não consegue expressar é uma ausência: quando um registry não anuncia nenhuma política de confiança e é inicializado sem nenhuma, o aviso que informa isso — e que diz para você fixar identidades com--identityou--key— vai para a saída de erro padrão. Um documento de configuração sem identidades confiáveis tem a mesma aparência tanto se uma política foi fixada e estava vazia quanto se nenhuma foi anunciada, então leia os dois fluxos; um programa que descarta a saída de erro padrão não é informado de nada. Quando o registry anuncia uma política, ou a linha de base integrada do hub oficial é fixada em seu lugar, a política fixada está no próprio conteúdo informado e nenhum aviso separado é produzido.
Uma configuração inicializada é um documento seu, que você continua editando, e é por isso que ela pode ser devolvida em vez de gravada. Congelar a configuração efetiva, abaixo, produz um registro daquilo em que a configuração se resolveu — estado que o compilador mantém sobre si mesmo, e não conteúdo que alguém compõe —, então sempre grava e não oferece --dry-run.
config show — inspecionar o que se aplica agora
aggrega config show informa a configuração que se aplica agora. Na visualização padrão, começa pela cascata de arquivos de configuração e substituições de ambiente que contribuíram, da menor precedência para a maior, e depois imprime a configuração efetiva mesclada — a configuração global, a cascata da árvore do workspace e qualquer sobreposição de ambiente, combinadas em um único resultado. Essa cascata de arquivos carregados é onde você confirma quais arquivos e substituições de ambiente moldaram a configuração atual.
Duas visualizações específicas restringem a saída:
--globalou--workspaceimprime literalmente os bytes do arquivo de uma única camada, com comentários e formatação preservados; quando o arquivo dessa camada não existe, ele informa isso em vez de falhar. As duas são mutuamente exclusivas.--originanota cada configuração efetiva com a camada de onde veio — uma flag de linha de comando, uma variável de ambiente, um arquivo de configuração ou os padrões integrados, da maior precedência para a menor. Uma flag é nomeada como você a digitou, então uma configuração que--offlinedecidiu nesta execução informa--offlinecomo origem; uma variável de ambiente é nomeada após um prefixoenv:e um arquivo de configuração pelo seu caminho absoluto.
Com --origin, uma configuração é atribuída à camada de maior precedência que a define, qualquer que seja o valor que essa camada grave. Assim, um arquivo de projeto que grava default_registry: hub.aggrega.ai é nomeado para essa configuração mesmo que o padrão integrado seja o mesmo registry, e um arquivo de projeto que repete um valor que o arquivo global já define é nomeado em vez do arquivo global: nos dois casos, é o arquivo que mantém o valor no lugar, e aquele cuja remoção muda a resposta no dia em que o padrão ou o arquivo abaixo dele mudar. Uma configuração que nenhuma camada define informa os padrões integrados.
- O que conta como defini-la. Um arquivo de configuração define uma configuração quando contém a chave dessa configuração, e uma configuração de lista também quando contém o complemento
_appendda lista. Uma variável de ambiente define sua configuração quando é exportada com um valor não vazio, e uma flag quando você a digita —--offline=falsedefine o modo com a mesma certeza que--offline. - Um arquivo de configuração que pertence ao seu pipeline é nomeado apenas para as chaves para as quais é lido, que são suas adições a listas e a política de assinatura. Uma chave que ele ignora, e sobre a qual emite um aviso, nunca é informada como origem de um valor.
- As configurações de lista e mapa são atribuídas como um todo, à camada de maior precedência que as define; qual camada contribuiu com qual entrada de uma lista não é informado.
- O requisito de assinatura é a única exceção. Qualquer camada pode ativá-lo e nenhuma pode desativá-lo, então ele nomeia a primeira camada que o ativa. Uma camada que grava
required: falsenão ativa nada, então, quando nenhuma camada o ativa, a configuração informa os padrões integrados.
config capture — congelar configurações críticas para o build
aggrega config capture grava a configuração efetiva crítica para o build no arquivo de configuração do workspace deste projeto, para que o workspace faça builds idênticos sem depender da configuração global da máquina. Configurações de ferramentas de toda a máquina, como a política de confiança de um registry, não são capturadas; por sua natureza, permanecem na configuração global. Executá-lo novamente em uma configuração inalterada regrava o mesmo arquivo byte a byte.
O subconjunto capturado é um conjunto de anexos a sockets de plugins e os diretórios do catálogo:
- Por padrão, capture congela apenas os sockets que determinam a saída renderizada — as vinculações de providers e os anexos de governança com papel transform —, já que somente eles precisam acompanhar o projeto para builds idênticos byte a byte. Os diretórios do catálogo são sempre capturados.
--all-pluginsamplia os sockets capturados para incluir também os sockets de governança com papel verdict, de linter e de importer. Sem ela, esses três ficam livres para variar conforme o ambiente.
Capture sempre grava e não oferece nenhuma forma de receber o conteúdo em vez disso. O que ele produz é um registro daquilo em que a configuração se resolveu, não um documento que alguém compõe, então não há nada para um autor revisar e alterar — devolvê-lo convidaria a editar um snapshot de uma resolução.
A captura grava apenas dentro de um workspace. Executada em uma pasta que não está dentro de nenhum, sem --workspace-root nem AGGREGA_WORKSPACE_ROOT nomeando um, ela não grava nada — um arquivo de configuração gravado ali transformaria a pasta em um workspace — e termina com um erro informando isso. aggrega config init --workspace transforma antes a pasta em um workspace.
Veja também
- configuration.md — em qual arquivo uma configuração deve ficar, a escala de precedência e os mecanismos a que um projeto maior recorre.
- global-flags.md — as flags
--confige--workspace-root. - environment-variables.md — as variáveis
AGGREGA_*que substituem a configuração em tempo de execução. - aggrega-registry.md — gerenciar registries e sua política de confiança diretamente.
- aggrega-cache.md — o que o diretório que
artifact_cache_dirnomeia realmente contém, e por que uma entidade que está ali e que nenhum lockfile fixa não é encontrada por um build.