Install the CLI

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

Updated 2026-11-05View Markdown Agent docs index

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:

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.

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

errata update --check
errata update

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

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:

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

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:

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.

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

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.

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 or CLI reference.