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

# Record a check

> Record a named pass or fail on a work item from CI or a terminal.

A named check is one pass or fail recorded on a work item under a name you choose, such as `ui-review` or `e2e`. Record one from CI or a terminal with [`outerlayer emit <name>`](/reference/cli-emit#outerlayer-emit-a-named-check).

A check counts only once a validator in `.outerlayer/validators/` declares its name. Until then it is stored, but shown nowhere and blocks nothing. See [Checks that run in CI](/policy-and-validators#checks-that-run-in-ci).

Say what is wrong in one sentence:

```bash theme={"system"}
outerlayer emit ui-review --result fail --item 412 \
  --body "The button should be the destructive red, not grey."
```

Read the sentence from a file, or from standard input with `-`:

```bash theme={"system"}
echo "The button should be the destructive red, not grey." \
  | outerlayer emit ui-review --result fail --item 412 --body-file -
```

Record a pass once the work is right. `--result` defaults to `pass`:

```bash theme={"system"}
outerlayer emit ui-review --item 412
```

A check with a run to point at carries its URL instead of a sentence:

```bash theme={"system"}
outerlayer emit e2e --result pass --item 412 --link "$RUN_URL"
```

## Rules

* **`--item` is always required.** A check is recorded on the work item, not on one pull request, so it holds across every pull request the item has.
* **A fail needs a link or a sentence.** A pass needs neither.
* **A session records checks on its own item.** Inside a recorded session, a check on the item that session was launched for is stored as the session's.
* **Only a person can record over a person's fail.** A session or a machine key is refused.
* **Your key decides who recorded the check, not the request.** A key bound to you records as you. A key with no person behind it, such as one for CI, records as a machine. Inside a recorded session the session records it, even with your own key.
* **Every row says who recorded it.** The Checks tab and the pull request comment name CI, a machine key, the person, the build session, or the host that ran it.
  A review of the whole item is not a named check. Record it on the item page, or with `outerlayer work comment`. See [Review and merge](/review-the-work#threads-and-waiting-on). The Quality chart on the Metrics → Overview dashboard reads reviews only, never named checks.

## Permissions

The caller needs **Emit evidence**. See [API keys](/api-keys).

A browser `outerlayer login` holds **Emit evidence** only when your role can create factory keys. The owner, admin and write roles can. Otherwise, use a factory key bound to you.


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