Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega config

Inspeccionar y gestionar la configuración del espacio de trabajo

Sinopsis

aggrega config

Descripción

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 catalog
directories, its provider bindings, which lint rules it relaxes. It is
committed, 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 the
directory the APPDATA environment variable names. It holds what belongs to the
machine rather than to any one project: the registries you pull from and the
signature trust policy for each, how large the compiled-module store may grow,
any command extension you have installed. It loads automatically when it is
there, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable wins
over both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity token
is never a field in either file; it is supplied by environment variable or flag
at 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 how
you find out which layer each setting came from. "aggrega config init" seeds a
working configuration, and "aggrega config capture" freezes the effective
build-critical settings into this workspace so a build does not depend on a
global file that is not committed.
Larger projects have more to work with. None of it is needed to start, and each
piece 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

ComandoDescripción
aggrega config captureCongela en este workspace la configuración efectiva crítica para la compilación
aggrega config initInicializa una configuración funcional con un registro y su política de confianza
aggrega config showMuestra la configuración efectiva y de dónde procede cada opción

Descripción de aggrega config capture

Write the effective build-critical configuration into this project's workspace
config file, so the workspace builds identically without relying on the
machine's global configuration.
The build-critical subset is the configuration a build participates in: a set of
plugin socket attachments and the catalog directories. By default the captured
sockets are only those that determine the
rendered output — the provider bindings and the transform-role governance attachments — since only those must
travel with the project for byte-identical output. Pass --all-plugins to also
freeze the verdict-role governance, linter, and importer sockets, which otherwise stay free to
vary by environment. Each field is written at its effective value — the value
that resolves right now with the global configuration and the workspace tree
merged together — so a binding that today comes only from the global config is
materialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are not
captured: they stay in the global config by their nature. Capture always writes
this project's workspace config file. Running it again on an unchanged
configuration rewrites the same file byte-for-byte. Run in a folder that is not
inside a workspace, with no --workspace-root naming one, it writes nothing and
exits with an error saying so.

Flags de aggrega config capture

FlagPredeterminadoDescripción
--all-pluginsfalseCaptura todos los sockets de plugins, incluidas las compuertas de gobernanza con rol verdict, de linter y de importer. Sin él, capture congela solo los sockets que determinan la salida renderizada (los enlaces de providers y los anexos de gobernanza con rol transform).

Descripción de aggrega config init

Seed a working configuration by registering a registry and its signature trust
policy, so a fresh machine can pull and verify signed artifacts without editing
YAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signatures
required and the official trusted identities. The registry's advertised trust
policy is fetched once from its own origin and pinned locally — trust-on-first-
use; when the hub is unreachable, advertises nothing, or the workspace is
offline, its built-in official baseline is written instead, so init still
produces 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 no
identities or key to pin by hand, so register it once while online, or add it
with "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace by
default; pass --workspace to write it to this project's workspace config
instead. If the target config file already exists, init refuses rather than
overwrite it — pass --force to write anyway (the registry entry is merged into
the existing file, other settings preserved).
Before anything else, init says where things are: the configuration file it
created — or, under --force, the one already there that it wrote into — and
the directory the machine-wide caches are kept in. On Windows that directory is
aggrega\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 does
everything init does except write: it hands the content back, creating and
modifying nothing. The answer names the file the content is for — which matters
here, because the target is the global config unless --workspace selects this
project'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 registry
is still contacted for its advertised trust policy, because the policy in that
content is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing config
file exactly as a write refuses it, and for the same reason. So its exit code
predicts 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 stays
parseable. A registry seeded with no trust policy, because it advertises none,
still produces its notice, on standard error: read that stream too, or that
configuration arrives without the advice to pin identities by hand. A pinned
policy, whether advertised or the hub's built-in baseline, is in the content
itself and produces no notice.

Flags de aggrega config init

FlagPredeterminadoDescripción
--dry-runfalseHace todo excepto escribir: devuelve la configuración inicializada como contenido, nombrando el archivo al que está destinada, y no crea ni modifica nada. Todo lo demás se comporta como la escritura, de modo que un archivo de configuración existente se rechaza exactamente igual que lo rechaza una escritura — pasa —force junto con él para obtener la fusión que produciría una escritura con sobrescritura.
--forcefalseSobrescribe un archivo de configuración existente. Sin él, init se niega cuando el archivo de destino ya existe.
--globalfalseEscribe la entrada en la configuración global compartida por todos los workspaces. Es el comportamiento predeterminado.
--registryhub.aggrega.aiHost del registro que se inicializa con su política de confianza. De forma predeterminada, el hub oficial.
--workspacefalseEscribe la entrada en la configuración del workspace de este proyecto en lugar de en la configuración global.

Descripción de aggrega config show

Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overrides
that contributed, lowest precedence first, then prints the effective merged
configuration — the global config, the workspace-tree cascade, and any
environment 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 it
says 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-in
defaults, highest precedence first. A flag is named as the reader typed it, so
a setting a flag decided reports that flag as its source. A setting is
attributed to the highest-precedence layer that sets it, whatever value that
layer writes: a file restating the default is the file named, not the built-in
defaults. List and map settings are attributed as a whole. The signing
requirement is the one exception: any layer may turn it on and none can turn it
off, so it names the first layer that turns it on.

Flags de aggrega config show

FlagPredeterminadoDescripción
--globalfalseImprime literalmente los bytes del archivo de configuración global, conservando sus comentarios y su formato.
--originfalseAnota cada opción efectiva con la capa de la que procede (un flag de la línea de comandos, una variable de entorno, un archivo de configuración o los valores predeterminados integrados).
--workspacefalseImprime literalmente los bytes del archivo de configuración del workspace de este proyecto, conservando sus comentarios y su formato.

Qué hace

Los subcomandos config inicializan, inspeccionan y congelan la configuración que rige una compilación. Para saber en qué archivo va una opción y cómo se combinan las capas, consulta Configuración — empieza por los dos archivos que necesitan la mayoría de los proyectos y deja el resto para después.

config init — inicializar una configuración funcional

aggrega config init inicializa una configuración en una máquina nueva registrando un registro y su política de confianza de firmas, de modo que los artefactos firmados se descargan y verifican sin editar YAML a mano. De forma predeterminada registra el hub oficial (hub.aggrega.ai) con firmas obligatorias y sus identidades de confianza oficiales. La política de confianza anunciada por el registro se obtiene una vez desde su propio origen y se fija localmente (trust-on-first-use); cuando el hub no está accesible, no anuncia nada o el workspace está sin conexión, se escribe en su lugar su línea base oficial integrada, de modo que init sigue produciendo una configuración utilizable sin conexión.

Antes que nada, init indica dónde están las cosas. La inicialización de una máquina Linux nueva comienza con:

Created the global configuration file at /home/you/.config/aggrega/config.yaml
Machine-wide caches are kept in /home/you/.cache/aggrega

y la de una máquina Windows nueva con:

Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yaml
Machine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache

La primera línea nombra el archivo de configuración que escribió init: Created cuando el archivo no existía, y Using cuando existía y --force permitió a init escribir en él; con --workspace nombra el archivo de configuración del workspace en lugar del global. La segunda nombra el directorio en el que se guardan las cachés de toda la máquina — los plugins compilados y sus descripciones —, que es donde cada plataforma guarda las cachés de un usuario; Qué cachés pertenecen a este proyecto y cuáles a la máquina da la regla por plataforma. Cada línea termina con su ruta y nada después, de modo que la ruta se puede copiar tal cual. Las líneas siguientes son las del propio registro: lo que encontró la obtención de la política de confianza y en qué archivo se registró el registro. Una inicialización rechazada no imprime ninguna de las dos líneas, ya que no creó nada, y tampoco lo hace --dry-run, cuya salida estándar contiene solo el contenido que devuelve.

  • --registry <host> inicializa un registro distinto — un hub aislado (air-gapped) o privado — en lugar del oficial. Un registro así no tiene una línea base integrada, de modo que, cuando no anuncia nada, la entrada se escribe sin política, y en un workspace sin conexión su inicialización se rechaza (código corto E0310): la política no se puede obtener, e init no admite --identity ni --key para fijar una a mano. Inicialízalo una vez mientras tengas conexión, o añádelo con aggrega registry add y una política que proporciones tú.
  • Si el archivo de destino ya existe, init se niega en lugar de sobrescribirlo; --force escribe de todos modos, fusionando la entrada del registro en el archivo existente y conservando las demás opciones.
  • --dry-run hace todo lo que hace init excepto escribir. Devuelve la configuración inicializada como contenido, sin crear ni modificar nada, y la respuesta nombra el archivo al que está destinado el contenido — lo cual importa aquí, porque el destino es la configuración global a menos que --workspace seleccione la de este proyecto. Un llamador que mantiene su propio modelo de documento, como un editor, coloca allí el contenido, donde es visible antes de guardarse y se puede modificar o deshacer.
  • Como una ejecución de prueba hace todo lo demás que hace init, su código de salida anticipa el de la escritura. Rechaza un archivo de configuración existente exactamente igual que lo rechaza una escritura, y por el mismo motivo, así que puedes usarla para preguntar si init tendría éxito antes de comprometerte con el cambio. Para ver el documento que produciría una escritura con sobrescritura, pasa --force junto con ella: --force --dry-run informa de la fusión y sigue sin escribir nada.
  • El registro se sigue consultando para obtener su política de confianza anunciada, porque la política del contenido devuelto es la que habría fijado una escritura. Una ejecución de prueba realiza al propio origen de ese registro la misma única solicitud no autenticada que realiza una escritura.
  • Con --dry-run, la salida estándar contiene ese contenido y nada más, de modo que sigue siendo analizable. Lo único que el contenido no puede expresar es una ausencia: cuando un registro no anuncia ninguna política de confianza y se inicializa sin ella, el aviso que lo indica — y que te dice que fijes identidades con --identity o --key — va a la salida de error estándar. Un documento de configuración sin identidades de confianza tiene el mismo aspecto tanto si se fijó una política que resultó estar vacía como si no se anunció ninguna, así que lee ambos flujos; un programa que descarta la salida de error estándar no recibe ninguna información al respecto. Cuando el registro sí anuncia una política, o se fija en su lugar la línea base integrada del hub oficial, la política fijada está en el propio contenido devuelto y no se produce ningún aviso aparte.

Una configuración inicializada es un documento que te pertenece y que sigues editando, por eso se puede devolver en lugar de escribir. Congelar la configuración efectiva, más abajo, produce un registro de aquello en lo que se resolvió la configuración — estado que el compilador guarda sobre sí mismo y no contenido que alguien redacta —, por lo que siempre escribe y no ofrece --dry-run.

config show — inspeccionar lo que se aplica ahora mismo

aggrega config show informa de la configuración que se aplica ahora mismo. En su vista predeterminada empieza por la cascada de archivos de configuración y anulaciones de entorno que contribuyeron, de menor a mayor prioridad, y luego imprime la configuración efectiva fusionada — la configuración global, la cascada del árbol del workspace y cualquier capa de entorno, combinadas en un único resultado. Esta cascada de archivos cargados es donde confirmas qué archivos y anulaciones de entorno dieron forma a la configuración actual.

Dos vistas específicas acotan la salida:

  • --global o --workspace imprime literalmente los bytes del archivo de una sola capa, con los comentarios y el formato conservados; cuando el archivo de esa capa no existe, lo indica en lugar de fallar. Ambos son mutuamente excluyentes.
  • --origin anota cada opción efectiva con la capa de la que procede — un flag de la línea de comandos, una variable de entorno, un archivo de configuración o los valores predeterminados integrados, de mayor a menor prioridad. Un flag se nombra tal como lo escribiste, de modo que una opción que decidió --offline en esta ejecución indica --offline como su origen; una variable de entorno se nombra tras un prefijo env: y un archivo de configuración por su ruta absoluta.

Con --origin, una opción se atribuye a la capa de mayor prioridad que la establece, sea cual sea el valor que escriba esa capa. Así, un archivo de proyecto que escribe default_registry: hub.aggrega.ai se nombra para esa opción aunque el valor predeterminado integrado sea el mismo registro, y un archivo de proyecto que repite un valor que el archivo global ya establece se nombra en lugar del archivo global: en ambos casos es el archivo que mantiene el valor en su sitio, y aquel cuya eliminación cambia la respuesta el día en que cambie el valor predeterminado o el archivo que está debajo. Una opción que ninguna capa establece indica los valores predeterminados integrados.

  • Qué cuenta como establecerla. Un archivo de configuración establece una opción cuando contiene la clave de esa opción, y una opción de tipo lista también cuando contiene el compañero _append de la lista. Una variable de entorno establece su opción cuando se exporta con un valor no vacío, y un flag cuando lo escribes — --offline=false establece el modo con la misma certeza que --offline.
  • Un archivo de configuración que pertenece a tu pipeline se nombra solo para las claves por las que se lee, que son sus adiciones a listas y la política de firma. Una clave que ignora, y sobre la que advierte, nunca se indica como origen de un valor.
  • Las opciones de tipo lista y mapa se atribuyen en su conjunto, a la capa de mayor prioridad que las establece; no se indica qué capa aportó cada entrada de una lista.
  • El requisito de firma es la única excepción. Cualquier capa puede activarlo y ninguna puede desactivarlo, por lo que nombra la primera capa que lo activa. Una capa que escribe required: false no activa nada, de modo que, cuando ninguna capa lo activa, la opción indica los valores predeterminados integrados.

config capture — congelar las opciones críticas para la compilación

aggrega config capture escribe la configuración efectiva crítica para la compilación en el archivo de configuración del workspace de este proyecto, de modo que el workspace compila de forma idéntica sin depender de la configuración global de la máquina. Las opciones de herramientas de toda la máquina, como la política de confianza de un registro, no se capturan; permanecen por su naturaleza en la configuración global. Volver a ejecutarlo sobre una configuración sin cambios reescribe el mismo archivo byte a byte.

El subconjunto capturado es un conjunto de anexos a sockets de plugins y los directorios del catálogo:

  • De forma predeterminada, capture congela solo los sockets que determinan la salida renderizada — los enlaces de providers y los anexos de gobernanza con rol transform —, ya que solo esos deben viajar con el proyecto para obtener compilaciones idénticas byte a byte. Los directorios del catálogo siempre se capturan.
  • --all-plugins amplía los sockets capturados para incluir también los sockets de gobernanza con rol verdict, de linter y de importer. Sin él, esos tres pueden variar libremente según el entorno.

Capture siempre escribe y no ofrece ninguna forma de recibir el contenido en su lugar. Lo que produce es un registro de aquello en lo que se resolvió la configuración, no un documento que alguien redacta, de modo que no hay nada que un autor deba revisar y modificar — devolverlo invitaría a editar una instantánea de una resolución.

La captura solo escribe dentro de un workspace. Ejecutada en una carpeta que no está dentro de ninguno, sin --workspace-root ni AGGREGA_WORKSPACE_ROOT que nombre uno, no escribe nada — un archivo de configuración escrito allí convertiría la carpeta en un workspace — y termina con un error que lo indica. aggrega config init --workspace convierte primero la carpeta en un workspace.

Véase también

  • configuration.md — en qué archivo va una opción, la escala de prioridades y los mecanismos a los que recurre un proyecto más grande.
  • global-flags.md — los flags --config y --workspace-root.
  • environment-variables.md — las variables AGGREGA_* que anulan la configuración en tiempo de ejecución.
  • aggrega-registry.md — gestionar directamente los registros y su política de confianza.
  • aggrega-cache.md — qué contiene realmente el directorio que nombra artifact_cache_dir, y por qué una compilación no encuentra una entidad que está allí y que ningún lockfile fija.