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

# Emit commands

> Record a named check, upload a proof artifact, record findings, or record a work item's acceptance criteria.

Every command on this page also takes `--url <url>` and `--app-id <id>`. Their defaults are in [Credential resolution](/reference/cli#credential-resolution). Each exits 0 on success and 1 with the reason on stderr otherwise. In CI, set the credential variables instead of running `login`. See [In CI](/reference/environment-variables#in-ci).

## outerlayer emit (a named check)

Record one named check's outcome on a work item.

```bash theme={"system"}
outerlayer emit <name> --item <number> [--result pass|fail]
                       [--link <url>] [--body <text> | --body-file <path>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--item <number>` | required | The work item, by its number on the factory. Required inside a recorded session too. |
| `--result <outcome>` | `pass` | `pass` or `fail`. |
| `--link <url>` | none | Proof link, usually the CI run URL. An `http://` or `https://` URL with no whitespace, at most 500 characters. |
| `--body <text>` | none | One sentence recording your judgment. At most 2,000 characters. |
| `--body-file <path>` | none | Read the sentence from a file. `-` reads standard input. Pass `--body` or `--body-file`, not both. |
| `--json` | off | Machine-readable output. |

The name starts with a lowercase letter, then lowercase letters, digits, `.`, `-` or `_`, up to 64 characters. A fail needs `--link` or a body. A pass needs neither. The command prints the recorded check's id.

```bash theme={"system"}
outerlayer emit smoke.pass --item 412 --link https://ci.example.com/run/42
outerlayer emit code-review --result fail --item 412 --body "The button should be red."
```

Inside a recorded session, the check is stored as the session's. A session cannot record over a person's fail. A session not launched with `OUTERLAYER_WORK` is refused. A person's own pass or fail on one criterion's proof goes on that criterion's thread instead: see `outerlayer work comment` in [Work commands](/reference/cli-work).

Exit codes: 0 recorded, 1 refused or invalid.

See also: [Record a check](/record-a-check).

## outerlayer emit artifact

Upload a proof artifact with a caption.

```bash theme={"system"}
outerlayer emit artifact <file> --caption <text> [--for <criterion-id>]
                                [--test <name[=path:line]>]...
                                [--replaces <ids>] [--pr <number>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--caption <text>` | required | One sentence saying what the artifact shows. At most 500 characters. |
| `--for <criterion-id>` | none | The acceptance criterion this proves. Its declared proof form must match the artifact's kind. |
| `--test <name[=path:line]>` | every test | With a JUnit XML file and `--for`, bind only this test, by name. Repeat it for each test. |
| `--replaces <ids>` | none | Retire earlier artifacts. One id, or up to 20 comma-separated. |
| `--pr <number>` | none | Pull request to anchor to when running outside a session and outside CI. |
| `--json` | off | Machine-readable output. |

```bash theme={"system"}
outerlayer emit artifact shot.png --caption "The login page shows the error banner" --for LOGIN-01
```

More on `--test`:

* `--test` needs `--for` and an `.xml` file. Without either, the command exits 1.
* A name several tests share binds all of them, with a warning.
* `<name>=<path>:<line>` gives the test's location when the runner's file does not carry it, as in `--test "renders the banner=src/login.test.ts:42"`.
* The command exits 1 on a name the file does not hold, or on a location that is absolute or leaves the repository.

The kind comes from the file type: see the table in [Attach evidence](/attach-evidence). Files cap at 8 MiB. A `.xml` file whose root is `<testsuites>` or `<testsuite>` is a `test` artifact. With `--for`, the command reads the XML first and exits 1 on a malformed file before sending anything. Without `--for`, the CLI sends an `.xml` file without checking it. The command prints the artifact's id, for a later `--replaces`.

Inside a recorded session, the artifact is queued and uploads on the next `outerlayer sync`. A session not launched with `OUTERLAYER_WORK` is refused. Outside a session, it uploads at once, anchored to `--pr`, CI's pull request, or the current git checkout. With nothing to attach it to, it is refused.

A `--replaces` target already uploaded is hidden everywhere. One target still in the local queue is cancelled, so it never uploads. If you name several ids and one is still queued, the command is refused: run `outerlayer sync` first, then retry.

Exit codes: 0 recorded or queued, 1 refused or invalid.

See also: [Attach evidence](/attach-evidence).

## outerlayer emit finding

Record one problem you hit in the factory.

```bash theme={"system"}
outerlayer emit finding --id <id> --category <category> --title <text> --file <path> --where <label>
                        [--line <number>] [--item <number>]
                        [--rule-path <path> --rule-relation <relation> [--rule-quote <text>] [--rule-line <number>]]
                        [--trace-id <id>] [--turn <number>] [--round <number>]
                        [--head-sha <sha>] [--context-source-sha <sha>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--id <id>` | required | Your own key, 1 to 64 characters of `A-Z a-z 0-9 . _ -`. Recording the same id on the item again replaces it. |
| `--category <category>` | required | `context`, `flaky-test`, `tooling`, `environment`, `defect` or `other`. |
| `--title <text>` | required | One sentence. At most 200 characters. |
| `--file <path>` | required | The file the problem is in, or the instruction's own path for a `context` finding. |
| `--where <label>` | required | Where this was recorded, such as `"build session"`. At most 200 characters. |
| `--line <number>` | none | Line number in `--file`. |
| `--rule-path <path>` | none | The instruction a `context` finding is about. Required for `context`. |
| `--rule-relation <relation>` | none | How the instruction fails: `wrong`, `broken` or `missing`. Required for `context`. |
| `--rule-quote <text>` | none | The instruction's sentence, quoted. Required unless the relation is `missing`. At most 500 characters. |
| `--rule-line <number>` | none | Line number in `--rule-path`. |
| `--trace-id <id>` | none | The session's trace id, when there is one. |
| `--turn <number>` | none | The turn within the session where you hit it. |
| `--round <number>` | none | The round number, when your process has rounds. |
| `--head-sha <sha>` | none | The commit you were working on. |
| `--context-source-sha <sha>` | the recorded session's instructions commit | The commit of the instructions you were working from. |
| `--item <number>` | the recorded session's item | The work item. Required outside a recorded session. |
| `--json` | off | Machine-readable output. |

```bash theme={"system"}
outerlayer emit finding --id gate-skip --category tooling \
  --title "The pre-push gate prints green when a step was skipped" \
  --file scripts/git/pre-push-checks.mjs --where "build session"
```

A refused finding names the field to fix. The old flags `--subject`, `--kind`, `--severity`, `--verdict`, `--fixed` and `--source` are refused by name. Use `--category` instead.

Exit codes: 0 recorded, 1 refused or invalid.

See also: [Findings](/findings).

## outerlayer emit findings

Record a batch of findings from a JSON file.

```bash theme={"system"}
outerlayer emit findings <file> [--item <number>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--item <number>` | the recorded session's item | The work item. Required outside a recorded session. |
| `--json` | off | Machine-readable output. |

```bash theme={"system"}
outerlayer emit findings review.json --item 412
```

The file holds `"schemaVersion": 2`, optional `headSha` and `contextSourceSha`, and 1 to 500 `findings` with the same fields and rules as `emit finding`. `-` reads standard input. The whole batch is checked before anything is sent. A `schemaVersion: 1` file is refused. Give each finding a `category` and set `schemaVersion: 2`.

Exit codes: 0 recorded, 1 refused or invalid.

See also: [Findings](/findings).

## outerlayer emit criteria

Record a work item's acceptance criteria as one list. The Criteria tab, its count and the item's status read this list. Nothing reads criteria out of the issue.

```bash theme={"system"}
outerlayer emit criteria <file> [--item <number>] [--json]
```

| Flag | Default | What it does |
| - | - | - |
| `--item <number>` | the recorded session's item | The work item, by its number on the factory. Required outside a recorded session. |
| `--json` | off | Machine-readable output. |

```bash theme={"system"}
outerlayer emit criteria criteria.json --item 412
```

The file is JSON. `-` reads standard input.

```json theme={"system"}
{
  "criteria": [
    { "id": "AC-724-01", "text": "Given a signed-in user, when they log out, then the session ends.", "proof": null },
    { "id": "login.redirect", "text": "Login redirects to the page the user asked for.", "proof": "screenshot" }
  ]
}
```

| Field | Meaning |
| - | - |
| `id` | Your own id, 1 to 64 characters from `A-Z a-z 0-9 . _ : -`. It is the id `outerlayer emit artifact --for` and `outerlayer work comment --criterion` take. No two criteria may share one. |
| `text` | The criterion as your team wrote it. 1 to 2,000 characters. |
| `proof` | The artifact kind that proves it: `video`, `screenshot`, `report`, `log`, `test` or `file`. `test` is met by bound JUnit results in which every bound test passed. `null` means any artifact bound to the id proves it. |

The list holds 1 to 200 criteria. The command checks the file before it sends anything, and names the id or value it refuses.

Every list you record is kept, with who recorded it and when. The newest is the item's current list.

**Only a person can replace a recorded list.** Anyone with the permission, an agent session included, can record an item's first list. After that, a replacement from an agent session, or from a factory key that belongs to no person (such as a CI or host key), is refused with `409` and the command exits 1. Run the command outside the session, with your own login. To let agent sessions replace a list too, set `criteria.replace: anyone` in `.outerlayer/policy.yaml`. See [Policy and validators](/policy-and-validators#the-policy-file).

Recording a list asks for a new evaluation of the item's linked pull requests. An item with no linked pull request gets none, but its Criteria tab shows the list at once. An item with no recorded list shows no criteria.

Exit codes: 0 recorded, 1 refused or invalid.

See also: [Review the work](/review-the-work), [Attach evidence](/attach-evidence).


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