Flags globais
Flags disponíveis em todo subcomando de aggrega.
--workspace-root <path>
Usa <path> como raiz do workspace, pulando a descoberta por completo. Quando a flag é omitida, aggrega descobre a raiz subindo a partir do diretório atual — ou, onde essa busca não encontra nada e o comando indica sua Release ou seu documento por um caminho absoluto, subindo em vez disso a partir da pasta desse arquivo; veja Configuração para saber o que ancora uma raiz, em que ordem, e quais comandos indicam um arquivo assim.
AGGREGA_WORKSPACE_ROOT é o equivalente no ambiente: quando --workspace-root não é dada, a variável fornece a raiz. A flag prevalece quando definida.
A raiz é a raiz onde quer que seja dada, incluindo os servidores: uma requisição a aggrega mcp que não indica um workspace próprio é respondida nela, sem que nada acima seja pesquisado. Uma raiz que não seja uma pasta existente — um caminho que não indica nada, ou que indica um arquivo — é recusada por todo comando que lê seu workspace, antes que o comando faça qualquer outra coisa; aggrega serve e um listener de aggrega mcp se recusam a iniciar com ela, e aggrega mcp sobre a entrada e saída padrão inicia mesmo assim e responde com a recusa a toda chamada que atua nesse workspace. A recusa nomeia qual dos dois a forneceu, --workspace-root ou AGGREGA_WORKSPACE_ROOT, com o valor exatamente como foi dado. Um comando que não lê nenhum workspace, como aggrega version, também não lê a raiz e não é recusado por causa dela.
Onde nenhum dos dois é dado e a descoberta não ancora nada, a pasta em que o comando roda é a raiz, e um comando que lê seu workspace avisa isso em uma linha na saída de erro padrão, indicando essa pasta e esta flag; veja Configuração, que também explica por que nada é gravado em um cache de artefatos em uma pasta assim.
Arquivo de configuração global
--config <path> indica explicitamente o arquivo de configuração global para uma invocação. Ela prevalece sobre a variável de ambiente AGGREGA_CONFIG, que por sua vez prevalece sobre o local padrão — e como ambas indicam um arquivo deliberadamente, um caminho que não existe é um erro visível em vez de uma alternativa silenciosa. Diferentemente das variáveis de configuração AGGREGA_*, nenhuma das duas substitui uma única configuração; elas selecionam qual arquivo se aplica. Seja qual for o arquivo resolvido, os arquivos de configuração do próprio projeto continuam se sobrepondo a ele. Configuração traz a ordem de resolução e o que deve ficar nesse arquivo.
--config e a variável de ambiente AGGREGA_CONFIG selecionam o destino de gravação assim como a fonte de leitura: um comando executado com --config <path> lê sua configuração desse arquivo e aplica sua alteração a esse mesmo arquivo, então o que um comando grava é o que o próximo comando com a mesma forma de invocação lê de volta.
Os comandos que alteram a configuração escolhem em qual arquivo gravar pela natureza da configuração: a configuração de ferramentas de toda a máquina (um registro) vai por padrão para o arquivo global, enquanto a configuração que participa do build (um vínculo de provider ou uma conexão a um socket de governança/linter/importador) vai por padrão para o arquivo commitado do projeto. Passe --global ou --workspace para mudar isso, e o comando imprime onde gravou.
Para inicializar uma configuração global em uma máquina nova — registrando um registro e sua política de confiança de assinaturas para que artefatos assinados sejam baixados e verificados sem editar YAML à mão —, execute aggrega config init. Para ver o que se aplica agora, e com --origin qual camada decidiu cada configuração, execute aggrega config show.
--offline
Recusa todo acesso à rede nesta execução.
Offline é uma postura do workspace, e não um modo de um único comando, e pode ser ativada a partir de três lugares: esta flag, AGGREGA_OFFLINE e a chave de nível superior offline em um arquivo de configuração. Eles significam a mesma coisa e seguem a ordem de sempre — a flag prevalece sobre a variável, que prevalece sobre o arquivo.
Desativar é tanto tarefa da flag quanto ativar. --offline=false permite a rede para um comando onde um arquivo de configuração commitado ou uma variável exportada ativou a postura. Isso importa quando não cabe a você editar o arquivo: um projeto cujo .aggrega-config.yaml traz offline: true recusa uma publicação para qualquer pessoa que o clone, e passar --offline=false é a única resposta que não exige nem um commit nem uma variável exportada.
O que é recusado e o que não é
A linha divisória é o que o trabalho precisa, e não qual comando foi digitado.
Recusado, porque não pode ser verdadeiro sem alcançar um registro:
--upgrade, onde quer que apareça. Ele resolve de novo cada dependência e leva cada uma à versão mais alta que um registro oferece atualmente, e “a mais alta disponível” é uma afirmação sobre o que um registro serve neste momento. Executá-lo contra um cache já preenchido fixaria o que por acaso estivesse em cache enquanto informa que passou para a mais recente, o que é pior do que uma parada.- Os comandos cujo próprio trabalho é uma ida e volta pela rede:
aggrega push,aggrega push-artifacteaggrega registry update. Eles avisam isso antes de ler sua entidade ou percorrer seus repositórios, e a recusa nomeia qual dos três lugares definiu a postura, para que alguém que não digitou nenhuma flag saiba onde procurar.
Não recusado, porque a máquina pode já ser capaz de atendê-lo:
- Um
aggrega pullcomum, eaggrega build --auto-pull. Ambos respeitam os pins já registrados e resolvem apenas o que não tem nenhum, então um workspace cujas referências estão todas em cache ou presentes em um catálogo decatalog_dirsé concluído sem acessar nada externo. Onde uma execução assim realmente precisa buscar algo, ela é recusada nesse ponto e informada de qual referência não pôde atender. aggrega buildcom um lockfile preenchido, que lê todo o seu fechamento a partir do cache. O único acesso que ele tem é um reparo: onde a cópia no armazenamento de uma entrada externa fixada sumiu, essa entrada é buscada de novo pelo digest que o lockfile já registra. Sob a postura não há transporte nem para isso, então a cópia ausente para o build em vez disso, nomeando a postura.- Uma publicação com
--dry-run. Todo o seu comportamento é informar o que publicaria sem chamar nada, o que a torna a forma de publicar segura offline, e não uma contradição da postura.
Uma máquina isolada da rede que guarda uma cópia local do seu catálogo e dos seus artefatos é o caso que esta divisão existe para manter funcionando: um workspace assim está offline, e quase tudo o que ele faz continua podendo ser atendido.
Precedência da configuração
Uma flag prevalece sobre tudo: sobre uma variável de ambiente, sobre os arquivos de configuração e sobre o padrão embutido. Configuração traz a escala completa, e environment-variables.md a lista de variáveis com o prefixo AGGREGA_.
aggrega config show --origin informa qual dessas camadas decidiu cada configuração, e uma flag que você digitou é informada como a flag — então, quando uma recusa nomeia uma camada que você não esperava, é com esse comando que você confirma.
Veja também
- configuration.md — em qual arquivo uma configuração deve ficar, e o modelo de precedência completo.
- environment-variables.md — a referência completa das variáveis
AGGREGA_*. - aggrega-serve.md — o daemon resolve seu workspace pelo mesmo caminho de descoberta da raiz.
| Flag | Padrão | Descrição |
|---|---|---|
--config | — | caminho para o arquivo de configuração global, substituindo a variável de ambiente AGGREGA_CONFIG e o local padrão. Os arquivos de configuração da árvore do workspace continuam se sobrepondo |
--no-color | false | Desativa a cor ANSI em toda a saída. Também respeitado pela variável de ambiente NO_COLOR |
--offline | false | Recusa todo acesso à rede nesta execução: a postura offline, ativada sem editar a configuração. Passe —offline=false para desativá-la em uma execução onde o arquivo de configuração ou AGGREGA_OFFLINE já a ativa. É recusado o que não pode ser verdadeiro sem um registro: —upgrade, cuja única tarefa é levar cada dependência à versão mais alta que um registro oferece atualmente, e os comandos cujo próprio trabalho é uma ida e volta pela rede — push, push-artifact e registry update. Continua rodando tudo o que a máquina já consegue atender: um build com um lockfile preenchido, —auto-pull sobre referências já em cache ou presentes em um catálogo local, e um dry run, que informa o que publicaria sem chamar nada |
--plain | false | Modo acessível: desativa a cor e desenha linhas de progresso simples e estáticas, sem animação de spinner nem redesenho do cursor, mesmo em um terminal. Pensado para leitores de tela |
--workspace-root | — | caminho absoluto a ser usado como raiz do workspace (pula a descoberta) |