Skip to main content
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

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.
  • --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. 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.