---
name: frayo
description: See and read the user's screen with the Frayo CLI. Use when you need to look at the app or UI you are building, check a visual bug, read text from a window or screenshot, or find an earlier capture. Prefer `frayo ocr` when only the text matters.
---

# Frayo: capture and read the screen

`frayo` talks to the Frayo menu-bar app, which owns the Screen Recording permission. If the app is not running the command starts it. If `frayo` is not found, ask the user to open Frayo > Settings > Integrations and turn on Allow scripts and agents to capture. That also adds `~/.local/bin/frayo`; if the shell still cannot find it, the user needs `export PATH="$HOME/.local/bin:$PATH"` in their shell profile. Every capture made this way shows a "Captured from the command line" notice on screen.

## When to use it

- You changed a UI and want to see the result: `frayo capture window --json`, then Read the PNG at `path`.
- You need the text on screen (error dialog, terminal output, docs page), not the picture: use `frayo ocr`. It costs far fewer tokens than reading an image.
- The user says "look at this", "what's on my screen", "the screenshot from earlier": use `list` or `search`.

## Commands

```
frayo capture area|window|screen|scrolling [--rect x,y,w,h] [--out path] [--keep] [--json]
frayo ocr <file> | --rect x,y,w,h [--code] [--json]
frayo list [--limit n] [--json]
frayo search <query> [--limit n] [--json]
frayo open <path>
```

- `capture area` and `capture window` without `--rect` open the normal picker and wait for the user to choose. Tell the user to pick before you run it. `--rect` works on `area` and `scrolling` only, and `scrolling` requires it.
- `capture area --rect x,y,w,h` captures without any UI. The rect is in screen points from the top-left of the main display (same as `screencapture -R`). Add `--keep` (area only) to also save it in the user's Library; otherwise it is a temporary file.
- `capture scrolling --rect x,y,w,h` stitches a region that is being scrolled by something else into one tall image, and ends after about six seconds without movement. The result is always saved in the user's Library.
- `--json` prints `{path, title, width, height, text}`; `list` and `search` print `{items: [{path, title, date}]}`. Without it you get the path (or text) on stdout.
- `--code` makes `ocr` rebuild indentation and spacing, for source code.
- Exit codes: 0 ok, 1 usage, 2 app not reachable, 3 permission denied or cancelled, 4 the command line needs a license (tell the user; do not retry).

## Examples

```
# See the app you are building
frayo capture window --json            # then Read the PNG at "path"

# Read an error without loading an image
frayo ocr --rect 0,800,1200,300

# Read code from a screenshot, keeping indentation
frayo ocr ~/Desktop/shot.png --code

# Find the screenshot that showed a stack trace
frayo search "NullPointerException" --json

# Save a capture to a known place
frayo capture screen --out /tmp/screen.png
```

## Notes

- Captures can contain private information. Capture only what the task needs and do not paste secrets you find into replies.
- Exit code 3 on a capture usually means Screen Recording permission is off or the user pressed Esc; ask the user rather than retrying in a loop.