CLI overview

invariant is the engine behind the app. The app calls it to read and change your projects, and your coding agent calls it to move a session along. You can use Invariant every day without typing a command; the CLI is there for agents, scripts and people who prefer a terminal.

What it does

For your agent: it hands out the next step of a session, checks every step the agent reports, and refuses the ones that need a person. See Commands your agent runs.
For your project: it installs packages of skills, rules and agents, and writes the context files each harness reads. See Packages from the terminal.
For your machine: it signs in to organisations, runs the local server the app talks to, and keeps itself up to date. See Account and machine.

Every command works on the project of the folder you run it in. Sessions and reviews are plain files under .invariant/, so the CLI works without the app, without a network and without an account.

Install, update, uninstall

The desktop app installs the invariant command for you and keeps it current. Without the app:

# macOS, Linux
curl -fsSL https://invariant.guru/install.sh | sh

# Windows (PowerShell)
irm https://invariant.guru/install.ps1 | iex

# npm, with Node.js 24 or later
npm install -g @invariant.guru/cli

The app and the script install a native build and put invariant on your PATH. It checks for a newer version once a day and updates itself in the background.

invariant version            # the version you run
invariant update --check     # is there a newer one?
invariant update             # install it now
invariant update --rollback  # go back to the previous version (native install)
invariant self uninstall     # remove the native install, keep projects and sign-ins

An npm install tells you when a new version is out; run invariant update or update it with npm. Everything about installing is on Install the app.

Release channels

You follow one of two channels:

stable (the default): tested releases.
canary: every new build first, a little rougher.

invariant update --channel canary
invariant update --channel stable

The choice is remembered, and the desktop app follows it. You can also change it in the app's Settings (Release channel). Canary needs the native install or the desktop app: npm only gets stable releases. To turn off the background updates, run invariant update --auto off.

Find help

Every command and subcommand describes itself:

invariant --help
invariant session --help
invariant session status --help

invariant help <command> does the same. The help lists the commands grouped by what they act on: sessions (session, plan, iterate), reviews (review), the project brain (brain), packages (init, install, add, sync, package…), and the machine (login, daemon, projects, update…).

Most commands accept --json for machine-readable output, so scripts and the app read the same answers you do.

Exit codes

A script, or an agent, can tell outcomes apart by the exit code:

Code	Meaning
`0`	Done.
`1`	Failed. The message says why.
`2`	Wrong usage: a missing argument or an unknown option.
`3`	Not found: no such session, review or project.
`4`	Refused: the step conflicts with the session's state, for example `in-progress` before a person approved the plan.
`5`	The local daemon did not answer.
`6`	Still waiting on a person. Nothing failed; run the command it printed to keep waiting.
`7`	The organisation is locked for billing. An owner fixes it on the web app's billing page.

The local daemon

The daemon is a small local server that serves the app's pages for every registered project and keeps a log of what happens in each. The app starts it for you; invariant daemon status shows it, and Account and machine covers the rest.

Anonymous usage data

The CLI shares anonymous usage data by default. invariant telemetry disable turns it off. What is sent, and what is never sent, is on Telemetry.