aireg init¶

Set up a project (creates .registry/manifest.yml).

Synopsis¶

aireg init [--for <harness>[,<harness>...]] [--force]
aireg init --registry <registry> [--as <name>] [--publish-to <registry>/<namespace>]
           [--watch] [--import <harness>[,<harness>...] | all] [--for <harness>,...] [--force]

Description¶

aireg init writes .registry/manifest.yml in the current folder, recording the harnesses the project installs into. It also writes .registry/.gitignore, which keeps the files of yours that aireg moves aside out of git. It doesn't edit the project's own .gitignore. Commit .registry/ so everyone working on the project installs the same artifacts.

init always writes into the current folder. Run it at the root of the project.

With --registry, init sets up the whole project in one go. It:

Declares the registry, as aireg registry add does.
Installs everything the registry publishes.
Imports the artifacts already in your harness folders, if you pass --import.
Publishes anything you edited locally to the registry, without asking.
Adds a background job that keeps the project in sync every 15 minutes, if you pass --watch.

Your user scope needs no setup: install into it directly with aireg add -g.

Options¶

Option	Description
`--for <harness>[,<harness>...]`	The harnesses the project installs into. Defaults to `claude,codex`.
`--force`	Replace an existing manifest. The registries it declares are kept; the artifacts it lists are not.
`--registry <registry>`	The registry to set the project up from. Takes any address `aireg registry add` does.
`--as <name>`	The name to give the registry. Defaults to the name in its `registry.json`, or the last part of its address for one that can't be read before you sign in. Used with `--registry`.
`--publish-to <registry>/<namespace>`	Where `aireg publish` sends work from this machine when no destination is named. Used with `--registry`. It sets `defaults.namespace` for every project on this machine; clear it with `aireg config unset defaults.namespace`.
`--watch`	Keep the project in sync with the registry in the background, every 15 minutes. Used with `--registry`.
`--adapter <id>`	The adapter that reads the registry, when aireg can't tell from the address. Used with `--registry`.
`--token-stdin`	Read the registry's token from standard input and sign in with it. Used with `--registry`.
`--import <harness>[,<harness>...] \| all`	Copy the artifacts already in these harness folders into the project, so aireg manages them. Each original stays where it is, and its harness keeps loading it from there. An artifact holding a symlink, or a file that may hold credentials, is refused as `publish` refuses it, and nothing is imported. Takes `agents`, `claude`, `codex` or `all`. Needs `--registry`.

JSON output¶

{"ok": true, "data": {"manifest": "/path/to/project/.registry/manifest.yml", "scope": "project", "targets": ["claude", "codex"], "imported": 0, "next": ["aireg registry add <address> --as <name>", "aireg add <name>/<namespace>"]}}

next holds the commands to run next. With --registry, init runs them itself, so the one JSON document it prints has steps in place of next, one entry for each step it took:

{"ok": true, "data": {"manifest": "/path/to/project/.registry/manifest.yml", "scope": "project", "targets": ["claude", "codex"], "imported": 0, "steps": [{"name": "registry", "detail": "acme → github.com/acme/ai-registry"}, {"name": "pulled", "detail": "3 artifacts from acme"}]}}

The steps are signed in, registry, namespace, pulled, imported, published and watching, each only when it happened.

Exit status¶

0: the manifest was written.
1: the manifest already exists (pass --force to replace it).
2: --for names an unknown harness, --as, --import or --publish-to has a value that isn't valid, an argument or -g was passed, init was run in your home folder, or --import has no single registry to import into.

With --registry, init exits with the status of the first step that fails. Run the same command again once it is fixed: while the manifest still installs nothing, init carries on from where it stopped.

Examples¶

Set up a project that installs into Claude Code and Codex:

aireg init

Set up a project that installs into Claude Code and Cursor:

aireg init --for claude,cursor

Set up a project from a team registry and keep it in sync:

aireg init --registry github.com/acme/ai-registry --as acme --watch