aggrega config
Przegląda konfigurację obszaru roboczego i zarządza nią
Składnia
aggrega configOpis
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.Podpolecenia
| Polecenie | Opis |
|---|---|
aggrega config capture | Zamraża w tym obszarze roboczym efektywną konfigurację krytyczną dla kompilacji |
aggrega config init | Tworzy początkową konfigurację roboczą z rejestrem i jego polityką zaufania |
aggrega config show | Pokazuje efektywną konfigurację i źródło każdego ustawienia |
Opis 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.Flagi aggrega config capture
| Flaga | Domyślnie | Opis |
|---|---|---|
--all-plugins | false | Przechwytuje wszystkie gniazda pluginów, w tym bramki governance w roli werdyktu, lintera i importera. Bez tej flagi capture zamraża tylko gniazda, które determinują renderowany wynik (powiązania providerów i dołączenia governance w roli transformacji). |
Opis 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.Flagi aggrega config init
| Flaga | Domyślnie | Opis |
|---|---|---|
--dry-run | false | Wykonuje wszystko poza zapisem: zwraca utworzoną konfigurację jako treść, wskazując plik, którego dotyczy, i niczego nie tworzy ani nie modyfikuje. Każde inne zachowanie jest takie samo jak przy zapisie, więc istniejący plik konfiguracyjny zostaje odrzucony dokładnie tak, jak odrzuca go zapis — aby otrzymać scalenie, które dałby zapis nadpisujący, należy przekazać razem z nią —force. |
--force | false | Nadpisuje istniejący plik konfiguracyjny. Bez tej flagi init odmawia, gdy plik docelowy już istnieje. |
--global | false | Zapisuje wpis w globalnej konfiguracji współdzielonej przez wszystkie obszary robocze. Jest to ustawienie domyślne. |
--registry | hub.aggrega.ai | Host rejestru do zarejestrowania wraz z jego polityką zaufania. Domyślnie oficjalny hub. |
--workspace | false | Zapisuje wpis w konfiguracji obszaru roboczego tego projektu zamiast w konfiguracji globalnej. |
Opis 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.Flagi aggrega config show
| Flaga | Domyślnie | Opis |
|---|---|---|
--global | false | Wypisuje dosłownie bajty globalnego pliku konfiguracyjnego, zachowując jego komentarze i formatowanie. |
--origin | false | Opisuje każde efektywne ustawienie warstwą, z której pochodzi (flaga wiersza poleceń, zmienna środowiskowa, plik konfiguracyjny lub wbudowane wartości domyślne). |
--workspace | false | Wypisuje dosłownie bajty pliku konfiguracyjnego obszaru roboczego tego projektu, zachowując jego komentarze i formatowanie. |
Działanie
Podpolecenia config inicjują, przeglądają i zamrażają konfigurację, która steruje kompilacją. Informacje o tym, w którym pliku powinno znaleźć się dane ustawienie i jak łączą się warstwy, zawiera strona Konfiguracja — zaczyna od dwóch plików potrzebnych większości projektów, a resztę zostawia na dalszą część.
config init — inicjowanie działającej konfiguracji
aggrega config init tworzy konfigurację na nowej maszynie, rejestrując rejestr i jego politykę zaufania do podpisów, dzięki czemu podpisane artefakty są pobierane i weryfikowane bez ręcznej edycji YAML. Domyślnie rejestruje oficjalny hub (hub.aggrega.ai) z wymaganymi podpisami i jego oficjalnymi zaufanymi tożsamościami. Polityka zaufania ogłaszana przez rejestr jest pobierana jednorazowo z jego własnego źródła i przypinana lokalnie (zaufanie przy pierwszym użyciu); gdy hub jest nieosiągalny, niczego nie ogłasza lub obszar roboczy działa offline, zapisywana jest zamiast niej wbudowana oficjalna konfiguracja bazowa, więc init nadal tworzy użyteczną konfigurację offline.
Przede wszystkim init informuje, gdzie co się znajduje. Inicjowanie nowej maszyny z systemem Linux zaczyna się od:
Created the global configuration file at /home/you/.config/aggrega/config.yamlMachine-wide caches are kept in /home/you/.cache/aggregaa nowej maszyny z systemem Windows od:
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\cachePierwszy wiersz podaje plik konfiguracyjny zapisany przez init: Created, gdy pliku nie było, oraz Using, gdy istniał, a --force pozwoliło init do niego zapisać; przy --workspace podaje plik konfiguracyjny obszaru roboczego zamiast globalnego. Drugi podaje katalog, w którym przechowywane są pamięci podręczne całej maszyny — skompilowane wtyczki i ich opisy — czyli miejsce, w którym dana platforma przechowuje pamięci podręczne użytkownika; regułę dla każdej platformy podaje sekcja Które pamięci podręczne należą do tego projektu, a które do maszyny. Każdy wiersz kończy się ścieżką, po której nic już nie ma, więc ścieżkę można skopiować bez zmian. Kolejne wiersze dotyczą samej rejestracji: co znalazło pobieranie polityki zaufania i w którym pliku zarejestrowano rejestr. Odrzucone inicjowanie nie wypisuje żadnego z tych wierszy, ponieważ niczego nie utworzyło; nie wypisuje ich też --dry-run, którego standardowe wyjście zawiera wyłącznie zwracaną treść.
--registry <host>inicjuje inny rejestr — odizolowany od sieci lub prywatny hub — zamiast oficjalnego. Taki rejestr nie ma wbudowanej konfiguracji bazowej, więc gdy niczego nie ogłasza, wpis jest zapisywany bez polityki, a w obszarze roboczym offline jego inicjowanie jest odrzucane (kod skróconyE0310): polityki nie można pobrać, ainitnie przyjmuje--identityani--key, by przypiąć ją ręcznie. Należy zainicjować go raz w trybie online albo dodać go za pomocąaggrega registry addz własną polityką.- Jeśli plik docelowy już istnieje,
initodmawia zamiast go nadpisać;--forcemimo to zapisuje, scalając wpis rejestru z istniejącym plikiem i zachowując pozostałe ustawienia. --dry-runwykonuje wszystko, co robiinit, z wyjątkiem zapisu. Zwraca zainicjowaną konfigurację jako treść, niczego nie tworząc ani nie modyfikując, a odpowiedź podaje plik, dla którego treść jest przeznaczona — co ma tu znaczenie, ponieważ celem jest konfiguracja globalna, chyba że--workspacewybierze własną konfigurację tego projektu. Wywołujący, który utrzymuje własny model dokumentu, na przykład edytor, umieszcza tam treść, gdzie jest ona widoczna przed zapisaniem i można ją poprawić lub cofnąć.- Ponieważ przebieg próbny robi wszystko inne, co robi
init, jego kod wyjścia przewiduje kod wyjścia zapisu. Odrzuca istniejący plik konfiguracyjny dokładnie tak, jak odrzuca go zapis, i z tego samego powodu, więc można go użyć, by sprawdzić, czyinitsię powiedzie, zanim wprowadzi się zmianę. Aby zobaczyć dokument, który utworzyłby zapis nadpisujący, należy przekazać razem z nim--force:--force --dry-runzgłasza wynik scalenia i nadal niczego nie zapisuje. - Rejestr nadal jest odpytywany o ogłaszaną politykę zaufania, ponieważ polityka w zgłaszanej treści jest tą, którą przypiąłby zapis. Przebieg próbny wysyła do własnego źródła tego rejestru to samo pojedyncze nieuwierzytelnione żądanie, które wysyła zapis.
- Przy
--dry-runstandardowe wyjście zawiera tę treść i nic więcej, dzięki czemu pozostaje możliwe do sparsowania. Jedyną rzeczą, której treść nie może wyrazić, jest brak: gdy rejestr nie ogłasza polityki zaufania i jest inicjowany bez niej, komunikat o tym — wraz z poleceniem przypięcia tożsamości za pomocą--identitylub--key— trafia na standardowe wyjście błędów. Dokument konfiguracji bez zaufanych tożsamości wygląda tak samo niezależnie od tego, czy przypięto politykę, która okazała się pusta, czy żadna nie została ogłoszona, dlatego należy czytać oba strumienie; program, który odrzuca standardowe wyjście błędów, nie otrzyma o tym żadnej informacji. Gdy rejestr ogłasza politykę lub w jej miejsce przypinana jest wbudowana konfiguracja bazowa oficjalnego hubu, przypięta polityka znajduje się w samej zgłaszanej treści i osobny komunikat nie jest generowany.
Zainicjowana konfiguracja jest dokumentem, którego właścicielem jest użytkownik i który dalej edytuje, dlatego można ją zwrócić zamiast zapisać. Zamrożenie efektywnej konfiguracji, opisane niżej, tworzy zapis tego, do czego konfiguracja się rozwiązała — stan, który kompilator przechowuje o sobie, a nie treść, którą ktoś tworzy — więc zawsze zapisuje i nie oferuje --dry-run.
config show — przegląd tego, co obowiązuje w tej chwili
aggrega config show zgłasza konfigurację obowiązującą w tej chwili. W widoku domyślnym zaczyna od kaskady plików konfiguracyjnych i nadpisań ze zmiennych środowiskowych, które się do niej przyczyniły, od najniższego priorytetu, a następnie wypisuje efektywną scaloną konfigurację — konfigurację globalną, kaskadę drzewa obszaru roboczego i ewentualną nakładkę środowiskową połączone w jeden wynik. W tej kaskadzie wczytanych plików można potwierdzić, które pliki i nadpisania środowiskowe ukształtowały bieżącą konfigurację.
Dwa ukierunkowane widoki zawężają wyjście:
--globallub--workspacewypisuje dosłownie bajty pliku pojedynczej warstwy, z zachowaniem komentarzy i formatowania; gdy plik tej warstwy nie istnieje, informuje o tym zamiast zakończyć się błędem. Te dwie opcje wzajemnie się wykluczają.--originopisuje każde efektywne ustawienie warstwą, z której pochodzi — flagą wiersza poleceń, zmienną środowiskową, plikiem konfiguracyjnym lub wbudowanymi wartościami domyślnymi, od najwyższego priorytetu. Flaga jest podawana tak, jak ją wpisano, więc ustawienie określone w tym uruchomieniu przez--offlinepodaje--offlinejako swoje źródło; zmienna środowiskowa jest podawana z prefiksemenv:, a plik konfiguracyjny przez swoją ścieżkę bezwzględną.
Przy --origin ustawienie jest przypisywane warstwie o najwyższym priorytecie, która je ustawia, niezależnie od zapisanej przez nią wartości. Dlatego plik projektu zawierający default_registry: hub.aggrega.ai jest podawany dla tego ustawienia, mimo że wbudowana wartość domyślna to ten sam rejestr, a plik projektu powtarzający wartość ustawioną już przez plik globalny jest podawany zamiast pliku globalnego: w obu przypadkach to on utrzymuje wartość i to jego usunięcie zmieni odpowiedź w dniu, w którym zmieni się wartość domyślna lub plik pod nim. Ustawienie, którego nie ustawia żadna warstwa, podaje wbudowane wartości domyślne.
- Co oznacza ustawienie. Plik konfiguracyjny ustawia ustawienie, gdy zawiera jego klucz, a w przypadku ustawienia listowego także wtedy, gdy zawiera towarzyszący liście klucz
_append. Zmienna środowiskowa ustawia swoje ustawienie, gdy jest wyeksportowana z niepustą wartością, a flaga — gdy zostanie wpisana:--offline=falseustawia tryb tak samo jak--offline. - Plik konfiguracyjny należący do potoku jest podawany tylko dla kluczy, dla których jest odczytywany, czyli jego dodatków do list i polityki podpisywania. Klucz, który ignoruje i o którym ostrzega, nigdy nie jest zgłaszany jako źródło wartości.
- Ustawienia listowe i mapowe są przypisywane w całości warstwie o najwyższym priorytecie, która je ustawia; nie jest zgłaszane, która warstwa dodała który element listy.
- Jedynym wyjątkiem jest wymóg podpisywania. Każda warstwa może go włączyć, a żadna nie może go wyłączyć, więc podawana jest pierwsza warstwa, która go włącza. Warstwa zapisująca
required: falseniczego nie włącza, więc gdy żadna warstwa go nie włącza, ustawienie podaje wbudowane wartości domyślne.
config capture — zamrożenie ustawień krytycznych dla budowania
aggrega config capture zapisuje efektywną konfigurację krytyczną dla budowania do pliku konfiguracji przestrzeni roboczej tego projektu, dzięki czemu przestrzeń robocza buduje się identycznie bez polegania na globalnej konfiguracji maszyny. Ustawienia narzędzi obowiązujące w całej maszynie, takie jak polityka zaufania rejestru, nie są przechwytywane; z natury pozostają w konfiguracji globalnej. Ponowne uruchomienie przy niezmienionej konfiguracji zapisuje ten sam plik bajt w bajt.
Przechwytywany podzbiór to zestaw podłączeń do gniazd pluginów oraz katalogi katalogów encji:
- Domyślnie przechwytywanie zamraża tylko gniazda, które określają renderowany wynik — powiązania dostawców oraz podłączenia governance w roli transformacji — ponieważ tylko one muszą podróżować razem z projektem, aby budowania były identyczne bajt w bajt. Katalogi katalogów encji są przechwytywane zawsze.
--all-pluginsrozszerza przechwytywane gniazda o gniazda governance w roli werdyktu, linterów i importerów. Bez tej flagi te trzy mogą się swobodnie różnić w zależności od środowiska.
Przechwytywanie zawsze zapisuje i nie oferuje możliwości otrzymania treści zamiast zapisu. To, co tworzy, jest zapisem tego, do czego rozwiązała się konfiguracja, a nie dokumentem, który ktoś komponuje, więc autor nie ma czego przeglądać ani poprawiać — zwrócenie go zachęcałoby do edytowania migawki rozwiązania.
Przechwytywanie zapisuje wyłącznie w obszarze roboczym. Uruchomione w folderze, który nie leży w żadnym obszarze roboczym, gdy żadnego nie wskazuje --workspace-root ani AGGREGA_WORKSPACE_ROOT, niczego nie zapisuje — zapisany tam plik konfiguracyjny zamieniłby folder w obszar roboczy — i kończy działanie z błędem, który o tym informuje. aggrega config init --workspace najpierw czyni folder obszarem roboczym.
Zobacz także
- configuration.md — w którym pliku należy umieścić dane ustawienie, hierarchia pierwszeństwa oraz mechanizmy, po które sięga większy projekt.
- global-flags.md — flagi
--configi--workspace-root. - environment-variables.md — zmienne
AGGREGA_*, które nadpisują konfigurację w czasie działania. - aggrega-registry.md — bezpośrednie zarządzanie rejestrami i ich polityką zaufania.
- aggrega-cache.md — co faktycznie zawiera katalog wskazywany przez
artifact_cache_diri dlaczego kompilacja nie znajduje znajdującej się tam encji, której nie przypina żaden plik blokady.