# Install the CLI

Requirements, release channels, workspace files, and daemon lifecycle.

Source: https://inerrata.ai/docs/install-the-cli
Updated: 2026-11-05

The npm package is `@inerrata-corporation/errata`. Its executable is `errata`. Use the scoped package name when installing; `npx errata` names a different npm package.

## Requirements and installation

Install Node.js 22 or newer, then:

~~~sh
npm install -g @inerrata-corporation/errata
errata --version
errata --help
~~~

The published package is a bundled CLI with no npm postinstall step. A successful install does not verify your agent's hooks or cloud connection; use the [quickstart checks](/docs/quickstart).

If `errata` is not found, reopen your terminal and check npm's global executable directory is on `PATH`. On Windows, `errata.cmd` can help distinguish a PowerShell script-policy issue from a missing installation.

### Upgrading over an older install

`errata init`, `errata start`, and `errata doctor` look for older copies on the machine and say what they found:

| Found | What happens |
| --- | --- |
| A running daemon older than this install | `start` restarts it onto the new version (`init` tells you it will) |
| Another `errata` earlier on your `PATH` | Reported with its path and version — remove it, or your agent's hooks may run the old one |
| The pre-npm `%LOCALAPPDATA%\errata` bundle (Windows) | Reported; `install.ps1` removes it |
| A logon autostart that launches a different copy (Windows) | Repointed at this install |

Only a newer install replaces an older daemon, never the reverse, and a daemon you started from a local build is never replaced; it is reported instead. An agent's MCP connection reports an older daemon but leaves it running until you run `errata start`.

## Release channels

| Channel | Install | Use |
| --- | --- | --- |
| `latest` | `npm install -g @inerrata-corporation/errata` | Published release |
| `dev` | `npm install -g @inerrata-corporation/errata@dev` | Development prerelease; may differ from the release |

~~~sh
errata update --check
errata update
~~~

Switch channels with `errata update --channel dev` or `errata update --channel latest`. After updating, restart the daemon:

~~~sh
errata stop
errata start
~~~

There is one daemon per machine. Stopping it affects every workspace it watches. Re-run `errata install-hooks <harness>` after an agent upgrade or when hook formats change.

## Initialize a workspace

From the project root:

~~~sh
errata init
~~~

This detects the profile, registers the workspace, signs you in, links the repository to its project in the Console (where you choose what it shares), and installs supported harness configuration. Use `--skip-hooks` to manage harness configuration yourself.

On a machine without a browser, sign in with a key from the Console's **Connect** page instead: `errata init --no-login`, then `errata login --token <key>`. A non-interactive `errata init` without credentials exits with that hint.

| File | Purpose |
| --- | --- |
| `.errata/workspace.json` | Workspace identity and detected stack |
| `.errata/castalia.db` | Local graph, created when the engine starts |
| `.errata/context.md` | Live context; maintained as the daemon processes the workspace |
| `.errata/report.html` | Snapshot generated by `errata report` |
| Agent configuration | See [Connect your agent](/docs/connect-your-agent) |

Keep `.errata/` runtime state out of version control. Review agent configuration and instruction-file changes before committing them.

## Run the daemon

The local MCP connection starts the daemon automatically: when your client launches `errata mcp`, it checks for the singleton and starts it if absent. Usually you only need to verify it:

~~~sh
errata status
errata projects
~~~

For hooks-only or shell-only use, or if automatic startup failed, run `errata start`. It attaches the workspace to the existing singleton or starts it in the background. `init` alone does not launch the daemon, and the Codex hook installer adds no MCP entry.

`errata dash` runs the multi-workspace daemon in the foreground; it does not launch a second copy while the singleton is running. The default hook port is `7891`.

## Sign in

`errata init` signs you in. To sign in again, switch accounts, or sign in a machine that was set up with `--no-login`:

~~~sh
errata login
~~~

The default flow prints a verification URL and one-time code and opens the browser. Approve it in the Console, then inspect `errata whoami`.

| Command | Purpose |
| --- | --- |
| `errata login --browser` | Browser authorization with a local loopback callback |
| `errata login --device --installation <uuid>` | Device authorization for a Console installation |
| `errata login --token <key>` | Install a Console-issued key; take care with shell history |
| `errata doctor --json` | Diagnose installation, credentials, renewal, endpoint, and authentication |
| `errata logout` | Clear local cloud credentials |

Never place credentials in prompts or committed configuration. Use current client-specific instructions in [Console Connect](https://console.inerrata.ai).

## Cloud endpoint overrides

`ERRATA_CLOUD_URL` overrides the gateway base URL. Release and development builds have different defaults; `errata status` prints the effective URL and channel. Changing a URL does not create credentials for that environment.

Continue with [Your first session](/docs/your-first-session) or [CLI reference](/docs/cli-reference).