> ## Documentation Index
> Fetch the complete documentation index at: https://ade-ac1c6011-ade-im-seeing-error-messag-eright-58df792e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & CLI

> Install local capture prerequisites and learn the `ade proof` commands agents use to record intentional evidence.

## Prerequisites

On macOS, `ade proof` reuses a handful of built-in command-line tools to capture screenshots and short recordings:

* `screencapture` — bundled with macOS; takes PNG/JPEG screenshots
* `osascript` — used to coordinate permission prompts
* `open` — used to surface captures in Finder

No extra install is required on a standard Mac. Agents that need richer browser-level evidence (DOM traces, console logs) should use a browser automation tool of their choice and pipe the results into ADE via `ade proof ingest` — ADE does not bundle its own browser.

<Note>
  The first time `ade proof capture` runs, macOS asks for **Screen Recording** permission. Grant it in **System Settings → Privacy & Security → Screen Recording**, then restart ADE. macOS requires the process to restart after granting screen recording permission.
</Note>

***

## The `ade proof` CLI

All proof flow happens through the `ade` CLI. Agents call these commands from terminal sessions inside a lane, and the results are stored in `.ade/artifacts/computer-use/` and linked to the lane, chat session, PR, or Linear issue they originated from.

| Command                                 | What it does                                                                           |
| --------------------------------------- | -------------------------------------------------------------------------------------- |
| `ade proof status --text`               | Show which local backends are available and their capability matrix                    |
| `ade proof list --text`                 | List captured proofs for the current scope                                             |
| `ade proof screenshot`                  | Capture a screenshot artifact                                                          |
| `ade proof record --seconds 20`         | Capture a short screen recording                                                       |
| `ade proof ingest --input-json '{...}'` | Ingest proofs produced by external tools (browser traces, verifications, console logs) |

`ade proof` accepts the same `--lane`, `--chat-session`, `--pr`, and `--linear-issue` owner flags as the rest of the ADE CLI, so agents can attach the captured proof to one or more owners in a single call.

### Typical Flow

<Steps>
  <Step title="Agent decides to capture evidence">
    Mid-task, the agent determines the step deserves a proof — for example, after finishing a UI change that is ready for review.
  </Step>

  <Step title="Call the CLI">
    The agent runs `ade proof screenshot --lane <laneId>` (or `record --seconds 20`) from its terminal.
  </Step>

  <Step title="ADE stores and links">
    ADE stores the file under `.ade/artifacts/computer-use/` and records a `ComputerUseArtifact` row with kind, owner, and metadata. A link is created to the lane, and any additional owners passed via flags.
  </Step>

  <Step title="Review in the UI">
    The proof shows up in the chat artifact panel, the PR attachments panel, or the Linear issue attachment list depending on its owners.
  </Step>
</Steps>

### Ingesting External Evidence

For proofs that come from outside ADE — a Playwright trace, a browser verification script, a console log bundle — the agent uses `ade proof ingest`:

```bash theme={null}
ade proof ingest --input-json '{
  "backend": { "name": "my-external-runner" },
  "inputs": [
    { "kind": "browser_trace", "title": "checkout flow", "path": "/tmp/trace.zip" },
    { "kind": "console_logs", "title": "checkout console", "text": "..." }
  ],
  "owners": [
    { "kind": "worker_task", "id": "worker_task_abc" }
  ]
}'
```

ADE normalizes each entry into a proof record of the declared kind and links it to the declared owners.

***

## Storage Layout

```
.ade/artifacts/computer-use/
  <artifact-id>.png         # screenshot
  <artifact-id>.mp4         # video recording
  <artifact-id>.zip         # trace or log bundle
```

Each artifact has a row in ADE's SQLite database with pointers to the file, the owners, the review state, and the workflow state. See [Configuration](/computer-use/config) for retention settings.