> ## 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. # Context and tool commands > context emit, context materialize, import, and mcp. ## outerlayer context emit Compile `.outerlayer/` into each configured target's native files. ```bash theme={"system"} outerlayer context emit [--check] [--dir ] [--json] ``` | Flag | Default | What it does | | - | - | - | | `--check` | off | Compute the outputs and compare them with disk. Writes nothing. For CI. | | `--dir ` | current directory | The repository root to read from. | | `--json` | off | Print the result as one JSON document. | Targets come from `targets` in `.outerlayer/config.json`: `claude-code`, `cursor`, `codex`, `copilot`, `factory`. There is no `--target` flag. Bare `outerlayer emit` with no name still runs this, with a deprecation line. A maintained skill (`emitting-evidence`, `amend`, `reporting-findings`, `outerlayer`) whose directory exists is rewritten to the installed CLI's copy. `--check` reports one that differs as drift. Template skills (`spec`, `writing-specs`, `build`) are never rewritten or reported. ```bash theme={"system"} outerlayer context emit outerlayer context emit --check ``` `--check` reports missing files and changed content for every output. It reports an orphaned output only when the file carries the generated-by header. `.mcp.json` and `.cursor/mcp.json` are JSON and carry no header, so they are never reported as orphaned. Exit codes: 0 on success. 1 on drift under `--check`. 1 when `.outerlayer/config.json` is missing or has no targets; the message shows the fix, such as `{"targets": ["claude-code"]}`. See also: [Agent context](/agent-context), [The .outerlayer directory](/reference/outerlayer-directory). ## outerlayer context materialize Fetch this repository's agent instructions from its context source and write them into the working tree: `AGENTS.md`, `.claude/` and `.outerlayer/`. ```bash theme={"system"} outerlayer context materialize [--json] ``` | Flag | Default | What it does | | - | - | - | | `--json` | off | Print the result as one JSON document. | The session-start hook runs this in a governed repository. Run it by hand to retry, or to check before a session. It refuses, writing nothing, while the repository still commits its own `AGENTS.md`, `.claude/` or `.outerlayer/`. ```bash theme={"system"} outerlayer context materialize ``` Exit codes: 0 when it wrote the context, it was already current, or the repository is its own source. 1 in these cases, and the message says which: * Outside a git repository. * On that refusal. * When the source cannot be reached or read. * When the repository is governed but its control plane cannot be identified, for example because the gateway refused the credential. * When the control plane no longer governs the repository. See also: [Share instructions across repositories](/share-instructions-across-repositories). ## outerlayer import ruler Port a `.ruler/` tree into the equivalent `.outerlayer/` tree. ```bash theme={"system"} outerlayer import ruler [--dir ] [--json] ``` | Flag | Default | What it does | | - | - | - | | `--dir ` | current directory | The repository root to read from. | | `--json` | off | Print the result as one JSON document. | It never overwrites an existing `.outerlayer/`. A conflict in any directory stops the whole import before anything is written. ```bash theme={"system"} outerlayer import ruler ``` Exit codes: 0, including when no `.ruler/` exists. 1 when the directory does not exist or an `.outerlayer/` is already there. ## outerlayer import capture Install the maintained skills into `.outerlayer/skills/`: `emitting-evidence`, `amend`, `reporting-findings` and `outerlayer`. ```bash theme={"system"} outerlayer import capture [--dir ] [--json] ``` | Flag | Default | What it does | | - | - | - | | `--dir ` | current directory | The repository root to write into. | | `--json` | off | Print the result as one JSON document. | When `.outerlayer/AGENTS.md` exists, a snippet about `emit artifact` is appended to it. It is never created. A skill that differs from the installed CLI's copy is rewritten, and the output names the file, so local edits to maintained skills do not last. ```bash theme={"system"} outerlayer import capture && outerlayer context emit ``` Exit codes: 0, or 1 when `--dir` does not exist or is not a directory. ## outerlayer mcp install Write or update the `outerlayer` MCP server entry. It writes the entry to `.outerlayer/mcp.json` when that file exists, else `.mcp.json`. It never writes an API key. ```bash theme={"system"} outerlayer mcp install [--transport stdio|http] [--command ] [--url ] [--name ] [--dir ] [--app-id ] [--json] ``` | Flag | Default | What it does | | - | - | - | | `--transport stdio\|http` | `stdio` | `stdio`: the client spawns `outerlayer mcp serve`, which reads the key on each connect. `http`: the entry calls the gateway directly with `${OUTERLAYER_API_KEY}`, which the client resolves from its environment. | | `--command ` | `outerlayer` | Stdio only. The executable the client spawns. Use an absolute or `${HOME}`-relative path when the CLI is not on the client's `PATH`. | | `--url ` | stdio: none; http: the gateway you logged in to, plus `/v1/mcp` | The gateway MCP endpoint. With stdio and no `--url`, `mcp serve` resolves it at connect time. For a self-hosted gateway, pass its origin plus `/v1/mcp`. | | `--name ` | `outerlayer` | The `mcpServers` key to write under. | | `--dir ` | current directory | The repository root to write into. | | `--app-id ` | none | Self-host only. The factory id, sent as `X-Outerlayer-App-Id`. Without it a self-hosted gateway answers 401. | | `--json` | off | Print `path`, `server`, `transport`, `url` and `changed`. | ```bash theme={"system"} outerlayer mcp install outerlayer mcp install --transport http ``` Exit codes: 0 when written or already current. 1 when `--transport` is not `stdio` or `http`, or `--dir` does not exist. 1 with `--transport http` and no gateway: pass `--url` or run `outerlayer login`. 1 when `.mcp.json` is not valid JSON, its top level is not an object, or its `mcpServers` is not an object: fix or remove the file, then rerun. See also: [Use the MCP server](/mcp). ## outerlayer mcp serve Run a stdio MCP server that bridges to the gateway. The stdio `.mcp.json` entry runs this. ```bash theme={"system"} outerlayer mcp serve [--url ] [--app-id ] ``` | Flag | Default | What it does | | - | - | - | | `--url ` | `OUTERLAYER_URL`, or the config file's gateway, plus `/v1/mcp` | The gateway MCP endpoint. | | `--app-id ` | `OUTERLAYER_APP_ID`, then the repository's connection or the config file | The factory id, sent as `X-Outerlayer-App-Id`. | It reads a factory key, or your login, at start-up. See [Credential resolution](/reference/cli#credential-resolution). It exits 1 before reading any input when it cannot connect. The MCP client shows the message as the connect error: | Message | Fix | | - | - | | no API key | Run `outerlayer login`, or set `OUTERLAYER_API_KEY`. | | no gateway URL | Run `outerlayer login`, set `OUTERLAYER_URL`, or pass `--url`. | | logged in, but no factory is chosen | `work` and `emit` commands such as `work build` and `emit artifact` connect automatically when one factory fits, but the MCP server never does. Run `outerlayer connect` in the repository, or pass `--app-id` or set `OUTERLAYER_APP_ID`. See [Automatic connection](/reference/cli-cloud#automatic-connection). | See also: [Use the MCP server](/mcp). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.