> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Every user-facing outerlayer command, grouped by what it touches.

Install nothing. Run the CLI with `npx @outerlayer/cli <command>`. It needs Node.js 22 or later.

These pages write `outerlayer <command>` for short. Unless you installed the CLI with `npm install -g @outerlayer/cli`, type `npx @outerlayer/cli` in its place.

How upgrades reach the hooks:

* Run through `npx`, `init` copies the CLI to `~/.outerlayer/cli`. The hooks and the status line run that copy, so clearing npm's cache does not break them.
* To upgrade that copy, run `npx @outerlayer/cli@latest init --local`. It points every hook at the new copy and makes no network call.
* A plain `init` upgrades the copy too, and also runs the connect step.
* With `npm install -g`, the hooks run the global install. Upgrading it upgrades them.

Restart a running `outerlayer daemon` or `outerlayer runner start` after an upgrade so it runs the new version.

## Commands

| Group | Commands | Page |
| - | - | - |
| Capture | `init`, `doctor`, `daemon`, `hooks status`, `hooks wrap`, `hooks unwrap`, `hooks install-git` | [Capture](/reference/cli-capture) |
| Cloud | `login`, `logout`, `connect`, `sync` | [Cloud](/reference/cli-cloud) |
| Work items | `work build`, `work link-session`, `work remove`, `work status`, `work list`, `work comment`, `work threads`, `work pr`, `work open-pr`, `work claim`, `work renew`, `work release` | [Work](/reference/cli-work) |
| Evidence | `emit <name>`, `emit artifact`, `emit finding`, `emit findings`, `emit criteria` | [Emit](/reference/cli-emit) |
| Runner | `runner start`, `runner stop`, `runner status`, `runner check`, `runner init`, `runner install`, `runner uninstall`, `runner image`, `runner logs` | [Runner](/reference/cli-runner) |
| Context | `context emit`, `context materialize`, `import ruler`, `import capture`, `mcp install`, `mcp serve` | [Context and tools](/reference/cli-context) |

`outerlayer <command> --help` (or `-h`) prints every flag of a command.

## Conventions every command follows

* **`--json`** makes stdout one JSON document and nothing else. Most commands that report a result take it. These do not: `logout`, `runner init`, `runner install`, `runner uninstall`, `runner check`, `runner stop`, `runner logs`, `hooks install-git`, `hooks wrap` and `hooks unwrap`. Neither do the long-running `daemon`, `runner start` and `mcp serve`. On `connect`, `--json` moves the text to stderr instead of dropping it.
* **`--no-color`** strips escape codes. Color is off on its own when stdout is not a terminal, when `NO_COLOR` is set, or when `TERM` is `dumb`. `FORCE_COLOR=1` turns it on for a pipe.
* **`--url` and `--app-id`** override the saved config on `sync`, every `work` and `emit` command, and `mcp install` and `mcp serve`. `connect`, `logout` and `doctor` take neither. There is no default gateway. A command with no URL from a flag, the environment or the config file refuses and says so. The API key is never a flag. It comes from `login`, or from `OUTERLAYER_API_KEY`.
* **`login` is the exception to `--url` and `--app-id`.** They apply only when a key is piped on stdin. Without a piped key, `login` signs in by browser, refuses both flags and exits 2. Browser login takes its gateway address from the dashboard, and `--dashboard <address>` picks the dashboard. See [Cloud](/reference/cli-cloud#outerlayer-login).
* **`--no-input`** makes `login` and `hooks wrap` fail instead of waiting on a person. They are the only commands that take it. `connect` asks only on a terminal.
* **`--version`** (or `-V`) prints the package version and, when the build carries one, its build id.

## Credential resolution

A cloud command sends one credential and names one factory. It picks a factory key over a login whenever a key exists, so CI and runners always act as their key.

**With a factory key.** The first hit wins for each value:

1. The key: `OUTERLAYER_API_KEY`, then `apiKey` in `~/.outerlayer/config.json`. It is never a flag.
2. The gateway: `--url`, then `OUTERLAYER_URL`, then `url` in the config file.
3. The factory: `--app-id`, then `OUTERLAYER_APP_ID`, then `appId` in the config file.

**With a login,** used only when no factory key exists:

1. The token: `accountToken` in the config file, written by `outerlayer login`.
2. The gateway: `--url`, then `OUTERLAYER_URL`, then `url` in the config file.
3. The factory: `--app-id`, then `OUTERLAYER_APP_ID`, then the repository's saved connection from [`outerlayer connect`](/reference/cli-cloud#outerlayer-connect). A login never uses `appId` from the config file, which belongs to a factory key.

A value still missing after its list makes the command refuse, naming the flag or variable that would supply it. Outside a repository, a login has no factory unless you pass `--app-id` or set `OUTERLAYER_APP_ID`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.