CLI, installation, and reconciliation

The CLI operates on the current working directory. Run repository commands from the directory whose stack you intend to manage. Detection can report multiple targets in a monorepo; reconciliation chooses the target matching the current directory, falling back to the first detected target. It does not apply a separate stack to every discovered workspace in one invocation.

Installation and source checkout

You need Git, Node.js, and Yarn before running the installation commands below. The package declares Node.js >=22.18.0; its development runtime is pinned to Node.js 26.5.0, with Yarn 4.17.0. For reproducing the development environment, use those pinned versions. Node.js provides the JavaScript runtime, and Yarn installs the dependencies needed to build and run the CLI.

Install Node.js from its download page and configure Yarn using its installation guide.

Once published, the package can be installed under its @sabinmarcu/ai name:

yarn add @sabinmarcu/ai

pnpm add @sabinmarcu/ai

npm install @sabinmarcu/ai

The package is not yet published to npm, but will be soon. Until publication, clone and build the CLI from source:

git clone https://github.com/sabinmarcu/ai.git ai-lib
cd ai-lib
yarn install
yarn build
export PATH="$PWD/bin:$PATH"

The PATH change exposes ai in the current shell. Add the checkout's absolute bin path to your shell configuration for a persistent installation. Rebuild after updating the source, because the launcher executes dist/cli.js, not the TypeScript entrypoint.

The launcher is a POSIX shell script, so this setup assumes a Unix-like shell. It detects a Yarn Plug'n'Play checkout and supplies the corresponding loader while preserving the target working directory. Invoking bin/ai by absolute path is also supported.

Move into the repository you want to configure before initializing it. The following path is a placeholder for that repository:

cd /path/to/target-repository
ai --help
ai detect
ai init
ai status -v

detect is read-only. init is not: it detects applicable modules, resolves the stack, writes managed assets and stack state, and adds the root AGENTS.md reference. Review existing AI files and keep a recoverable copy of local changes before initialization. It is not an empty-file scaffolder or a dry run.

Select a preset or additional modules

Presets express reusable bundles. The catalog's node-web preset combines web application, React, TypeScript, Yarn, platform, and styling guidance. For a repository that actually needs that combination:

ai init --preset node-web

Both --preset and --module may be repeated. Their short forms are -p and -m. Initialization runs reconciliation, so modules with detectors are reconsidered using repository evidence; an explicit module argument is not a permanent override of its detector. Preset selections are retained.

Use init for initial setup and reconcile for subsequent repository changes. Initialization constructs a new stack with a new creation timestamp; it is not an operation that simply appends options to the existing selection.

Inspect the installation

status returns a nonzero exit code for unknown selected modules or presets, or for managed-file issues. With no stack, it reports that absence and returns zero. Do not use that exit code alone to prove that a repository has been initialized.

verify is narrower than its name might suggest: it does not inspect installed file contents or perform the full saved-stack resolution used by status. It is not a substitute for checking drift or incompatible selections.

Review before reconciling

After adding or removing tools, changing dependencies, or updating the catalog used by the CLI:

ai reconcile

Without flags, this prints a plan and makes no changes. The plan reports modules, mixins, and managed-file diagnostics:

The preview returns zero even when its diagnostics contain errors; it is a review command, not a strict CI gate.

Detection refreshes detector-backed selections, preserves selected presets, and retains explicitly selected modules that have no detector. Dependencies and mixins are then recalculated from the proposed stack.

When the proposed changes are appropriate and no blocking issues remain:

ai reconcile --apply

This applies the assets, removes eligible stale files, writes the proposed stack, and ensures the root entrypoint link exists. It then creates another plan to check for unresolved changes or issues. Missing or outdated files can be handled by this normal path; edited files and unknown selected modules require attention first.

Understand file diagnostics

Inspection compares three things: the desired catalog content, the previously recorded file hash, and the current file content.

reconcile --apply blocks on drifted, stale-drifted, and untracked files. It also blocks when selected module IDs have disappeared from the catalog. Preserve useful edits and move repository-specific changes into the applicable override location before deciding to replace managed files.

Repair deliberately

ai reconcile --repair

Repair is a force operation. It can overwrite local content at managed paths, remove edited stale files, and drop unknown explicitly selected module IDs. It does not merge those edits or back them up. Review the preview and preserve anything you need before using it.

--apply and --repair are mutually exclusive. Repair is rejected when there are no blocking errors; ordinary missing or outdated files should use --apply. Unknown presets are not covered by the selected-module repair step.

There is also a lower-level operation:

ai apply

This materializes the existing saved selection without redetecting the repository. Unlike reconcile --apply, it can overwrite edited files already recorded as managed. It still refuses to overwrite a differing untracked file or remove an edited stale file. Use it when restoring the current stack is intentional, not as a synonym for a read-only status check or guarded reconciliation.

Browse modules interactively

ai interactive

This requires an existing stack and an interactive terminal. It shows effective modules, dependency relationships, and reasons a module is selected. Search with /, move with the arrow keys or j and k, switch grouping with t, and quit with q.

The current interface is a browser, not a selection editor. Searching, navigating, and grouping do not change the saved stack or apply files.

Source mode

For a repository that contains the catalog it consumes:

ai init --asset-mode source

Source mode loads the local catalog directory and links directly to its assets from .ai/AGENTS.md. The assets must be contained in the target repository. Only the entrypoint is materialized in this mode; catalog instructions and the reconciliation skill remain source links.

Normal consumers should use the default materialized mode. It copies the guidance into the repository and does not depend on keeping a separate catalog checkout available to the coding agent.