pp-agent-capture

Agent Capture - Printing Press CLI

Prerequisites: Install the CLI

This skill drives the agent-capture-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install agent-capture --cli-only
   

2. Verify: agent-capture-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-capture/cmd/agent-capture-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Reach for this when the user wants:

• screenshot a specific window or app (screenshot, batch for multiple)
• record video of a window, app, display, or region (record)
• convert a recording to an optimized GIF (convert)
• do a full capture + record + GIF pipeline in one command (pipeline)
• diff against a baseline screenshot (diff) for before/after evidence
• bundle screenshots + recording + GIF as evidence for a PR or bug report (evidence)
• find the right window by fuzzy-matching its title (find)
• stitch multiple screenshots into an animated GIF (stitch)
• extract text from a window using macOS Vision OCR (ocr)
• record a terminal session via VHS tape files (vhs)
• render Remotion compositions to video or stills (remotion)
• monitor a UI by periodic screenshots (watch)
• save and replay capture configs (preset)

Skip it on non-macOS hosts; the CLI uses ScreenCaptureKit (macOS only). On first run it will prompt for Screen Recording permission; the permissions command guides that flow.

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help -> show agent-capture --help
2. Starts with install -> CLI installation (no MCP server ships today)
3. Anything else -> Direct Use (map to the best command and run it)

Direct Use

1. Check installed: which agent-capture. If missing, offer CLI installation.
2. If permissions aren't granted, run agent-capture permissions first.
3. Use agent-capture list to see available capture targets (open windows, displays).
4. Use agent-capture find <text> to fuzzy-match a window title before capturing.
5. Execute with --json for structured output (agent-native default):

   agent-capture <command> [args] --json
   

Notable Commands

Command	What it does
screenshot	Capture a window, app, display, or region
record	Record video of a window, app, display, or region
pipeline	Record + convert + optimize in one command
convert	Video -> optimized GIF (two-pass palette)
diff	Capture + diff against a baseline
evidence	Full bundle (screenshots + recording + GIF) for a PR
batch	Screenshot multiple apps in one invocation
find	Fuzzy search open window titles
list	List available capture targets
ocr	Extract text from a window using macOS Vision
stitch	Combine screenshots into an animated GIF
vhs	Run a VHS tape file for terminal recording
remotion	Render Remotion compositions
watch	Periodic capture for UI monitoring
preset	Save / load capture configs
permissions	Guide Screen Recording permission setup
health	Machine-readable CI / agent preflight

Run any command with --help for full flag documentation.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr
• Filterable — --select keeps a subset of fields, with dotted-path support (see below)
• Previewable — --dry-run shows the request without sending
• Cacheable — GET responses cached for 5 minutes, bypass with --no-cache
• Non-interactive — never prompts, every input is a flag

Filtering output

--select accepts dotted paths to descend into nested responses; arrays traverse element-wise:

<cli>-pp-cli <command> --agent --select id,name
<cli>-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Target not found (no matching window or display)
4	Permissions missing (Screen Recording not granted)
5	Capture error (ScreenCaptureKit failure, ffmpeg failure)