← Guide

Command line

Frayo has a command-line tool, frayo. Scripts and AI coding agents can use it to capture the screen, read text from it and search your Library.

The tool does not capture by itself. It asks the Frayo app, which holds the Screen Recording permission. If the app is not running, the command starts it.

Access is off by default

Nothing can use the tool until you allow it.

1. Open Settings › Integrations.
2. Turn on Allow scripts and agents to capture. This adds a link at ~/.local/bin/frayo if it is missing, and allows access.
3. Turn it off and the tool stops working at once. The link stays until you click Uninstall under the switch.

If frayo is not found, add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Move Frayo to Applications before installing. Uninstall removes the link.

Links that capture without asking

The frayo:// links that capture or record with no picker follow the same switch: frayo://record-screen, and any link with ?rect= (such as frayo://capture-area?rect=0,0,400,300). With Allow scripts and agents to capture off, Frayo shows a notice and does nothing. This stops a web page from starting a recording. Links that open the normal picker or a window (capture-area, library, open-settings and so on) always work.

Who can connect

The app listens on a private socket in its Application Support folder. Only your own macOS user can reach it. Every capture made this way shows a "Captured from the command line" notice, so nothing is silent.

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>
frayo help

• capture area and capture window open the normal picker and wait for you to choose.
• capture area --rect captures without any picker. The rectangle is in screen points from the top-left of the main display. The file is temporary unless you add --keep, which also saves it in your Library.
• capture scrolling --rect captures a region that something else is scrolling (a page that scrolls itself, or your own scripted scroll) and stitches it into one tall image. It ends when the content has stopped moving for about six seconds. The rect is required, and the image is always saved in your Library.
• --out chooses where the file goes.
• ocr prints the text in an image file or a screen region. --code keeps indentation, like Code-aware Copy Text. Reading a file needs no Screen Recording permission.
• list shows recent captures, newest first. search finds them by name, title or the words inside.
• open shows a capture as a thumbnail.
• --json prints structured output: path, title, width, height, text. list and search print items.

Exit codes

Examples

frayo capture window --json
frayo ocr --rect 0,800,1200,300
frayo ocr ~/Desktop/shot.png --code
frayo search "NullPointerException" --json

For AI agents

Frayo ships an agent skill file that tells an agent when and how to use these commands. It says to prefer ocr when only the text matters, because text costs far fewer tokens than an image. Copy it to your agent's skills folder.

Captures can hold private data. Check Secret detection, and only turn access on if you trust the tools running as you.