# Install and Repair Commands

This is the complete direct-user CLI surface for normal AIWG setup and
recovery. Everything after a working installation should normally happen in
the agent conversation.

For the guided path, provider names, prerequisites, and success checks, follow
[Install, Connect, and Verify](../getting-started/install-connect-verify.md).

## Install AIWG

In a terminal:

```bash
npm install -g aiwg
```

Then open the intended project in your agent and ask:

```text
Set up AIWG for this project. Detect the provider, preview the files you will
create or update, preserve existing work, ask before material changes, and
verify that AIWG is active when you finish.
```

If no working agent can complete project setup, the
[complete CLI reference](reference.md) provides the supported `aiwg wizard`
and `aiwg use` fallback commands.

## Check or repair the installation

Start in the agent conversation:

```text
Check whether AIWG is installed and active in this project. Diagnose any
installation or provider wiring problem, explain the proposed repair, ask
before changing files, and verify the result.
```

If the agent cannot run, these recovery commands are safe direct-user entry
points:

```bash
aiwg status
aiwg doctor
aiwg refresh
aiwg installation show
```

- `status` reports what AIWG can see without changing the installation.
- `doctor` diagnoses installation and provider wiring problems.
- `refresh` updates and redeploys managed AIWG context. Review its plan before
  approving changes when prompted.
- `installation show` reports the provider-neutral canonical installation,
  the package-manager executable used for updates, the currently executing
  installation, and any drift between them.

When the recorded installation and the executing one disagree, the read-only
diagnostics keep working and print the drift on stderr first: `version`,
`status` (including `--probe --json`), `doctor`, `runtime-info`, `discover`,
`show`, and `index query|deps|stats`. Everything that writes — `update`,
`refresh`, `use`, deployment, channel switching, `index build` — stays blocked
until you run `aiwg installation adopt` or `aiwg installation switch`. So a
drifted install still answers `aiwg doctor` and
`aiwg discover --backend local "<need>"`; it just refuses to change anything.

## Canonical installation and recovery

AIWG records the first resolved global installation in `installation.json`
under the global user-config directory. The directory follows the standard
resolution contract: `AIWG_CONFIG`, an existing `~/.aiwg`, an existing
`~/.config/aiwg`, then `~/.aiwg`. Provider directories and project `.aiwg/`
directories never own this record.

Updates use the recorded method and executable. For example, an AIWG installed
by npm under nvm continues using that npm even if Homebrew later appears first
on `PATH`. AIWG stops with a diagnostic if another package root handles the
command; it does not silently change ownership.

After intentionally reinstalling or changing Node managers, adopt the
installation that currently handles the command:

```bash
aiwg installation show
aiwg installation adopt --manager /absolute/path/to/npm
```

To select a different known installation explicitly:

```bash
aiwg installation switch \
  --root /absolute/path/to/aiwg \
  --method npm \
  --manager /absolute/path/to/npm
```

Use `--method web` for the signed lightweight web CLI and `--method source
--run-mode development` for a source checkout. `show`, `adopt`, and `switch`
remain available when drift blocks ordinary commands. Existing `channel.json`
state is migrated on first use, including channel, development path, and
update-check timestamps.

### Duplicate npm and nvm copies

`aiwg doctor` lists executable copies on `PATH` and in other nvm Node versions,
including versions outside the current `PATH`. It checks the default `~/.nvm`
home, `NVM_DIR`, and custom nvm homes identified by `NVM_BIN`, PATH entries, or
the running/registered installation. Copies are inspected without executing them.
The identity diagnostic names both the running and registered package roots.

An equal package version does not automatically register another copy. To use
that copy deliberately, invoke its executable by absolute path and adopt it:

```bash
/absolute/node-prefix/bin/aiwg installation adopt --method npm \
  --manager /absolute/node-prefix/bin/npm --yes
/absolute/node-prefix/bin/aiwg installation show
```

Adoption updates the registration only; it does not change `PATH` or remove any
copies. To retain the existing registration, put its executable first on the
caller's `PATH` (including cron's PATH), or use its absolute executable path.
Remove an unwanted nvm-global copy by selecting that Node version and running
`npm uninstall -g aiwg` with that version's npm. Check each Node version that
doctor reports. Doctor diagnoses these copies; it does not adopt or remove them,
and `doctor --fix` is not an installation-identity repair command.

Exact flags, machine-readable output, and automation contracts belong in the
[agent and automation CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/cli/reference.md), not in ordinary user
journeys.

## Update notifications

Eligible interactive CLI invocations check a local cache at startup and may
write an update notice to stderr before command output. The notice identifies
the installed and available versions, routes every installation type through
`aiwg update`, and asks you to rerun the prior command without echoing its
arguments. The foreground command never contacts the registry: a detached,
timeout-bounded child refreshes the cache for a later invocation.

Notices and background refreshes are suppressed for non-TTY use, `CI`,
`GITHUB_ACTIONS`, `GITLAB_CI`, `NO_UPDATE_NOTIFIER`,
`AIWG_NO_UPDATE_CHECK`, and installations with `checkOnStartup: false`.
Successful notices and refresh attempts are rate-limited by the installation's
`updateCheckInterval` (24 hours by default). Fast help/version and channel
commands participate in the same bootstrap behavior; notifier failures remain
best-effort and never change the requested command's exit status.

The bootstrap depends on the packaged notifier module. If `dist/` itself is
missing or incomplete, the CLI emits the existing build/reinstall diagnostic
first because no notifier implementation is available to load; this recovery
exception never performs a network request.
