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

# Run commands

> Reference for outerlayer run topics, outerlayer run found-issue and outerlayer run found-nothing, which the agent of a schedule automation's run uses to read its topics and to report.

The agent of a [schedule automation's](https://docs-stg.outerlayer.ai/schedule-automations.md) run reads and reports with these three commands. You do not run them yourself. The runner gives the agent a run key and sets `OUTERLAYER_RUN` to the run's id, and OuterLayer refuses a call with any other key.

The commands only read and report. OuterLayer files the issues after the run ends.

All three commands take `--json`, `--url` and `--app-id`. A failed command prints the reason and exits `1`.

## outerlayer run topics

List the topics that the automation already filed issues for, so the agent can use a topic's exact text when it finds the same problem. Run it before the run reports.

```bash theme={"system"}
outerlayer run topics
```

The command prints one topic on each line, newest first, with at most 50 topics. It prints nothing when the automation has no topics. The list holds open and closed topics. With `--json`, the output is `{"topics": ["<topic>", ...]}`, and `--quiet` prints nothing.

A gateway that has no topics route counts as a gateway with no topics: the command prints nothing and exits `0`.

## outerlayer run found-issue

Report one issue that the run found. Run it once for each issue.

```bash theme={"system"}
outerlayer run found-issue --title <text> --topic <text> (--body <markdown> | --body-file <path>)
```

| Flag | Default | What it does |
| - | - | - |
| `--title <text>` | required | The title of the issue. |
| `--topic <text>` | required | Short text that names what the issue is about. A run can report each topic once. OuterLayer files no issue for a topic while its earlier issue is open. |
| `--body <markdown>` | one of two required | The body of the issue, in Markdown. |
| `--body-file <path>` | one of two required | Read the body from a file. `-` reads standard input. Not with `--body`. |

```bash theme={"system"}
outerlayer run found-issue --title "Flaky test: checkout" --topic "checkout.test.ts" --body "It fails one run in five."
```

The command prints how many more issues the run can report. With `--json`, the output is `{"issuesLeft": <number>}`. When the automation's daily limit leaves none, the command refuses and names the limit.

OuterLayer keeps a report for a topic that it holds back, and it does not count that report. The command then says so: `kept the issue · OuterLayer already has an issue for this topic, so it does not count · 2 more can be reported`. With `--json`, the output is `{"issuesLeft": <number>, "counted": false}`. A run keeps at most 50 reports that do not count. After that, the command refuses the way it refuses at the daily limit.

## outerlayer run found-nothing

Report that the run found nothing to file. Run it instead of `found-issue`, never after it.

```bash theme={"system"}
outerlayer run found-nothing --reason <text>
```

| Flag | Default | What it does |
| - | - | - |
| `--reason <text>` | required | One sentence that says why the run found nothing. The run log shows it. |

```bash theme={"system"}
outerlayer run found-nothing --reason "Every test passed in the last 20 runs."
```

With `--json`, the output is `{"recorded": true}`.


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