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:
- 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
- Verify:
agent-capture-pp-cli --version
- 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:
- Empty,
help, or --help -> show agent-capture --help
- Starts with
install -> CLI installation (no MCP server ships today)
- Anything else -> Direct Use (map to the best command and run it)
Direct Use
- Check installed:
which agent-capture. If missing, offer CLI installation.
- If permissions aren't granted, run
agent-capture permissions first.
- Use
agent-capture list to see available capture targets (open windows, displays).
- Use
agent-capture find <text> to fuzzy-match a window title before capturing.
- 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) |
1---2name: pp-agent-capture3description: macOS screen capture, window recording, GIF conversion, and agent evidence bundles from the terminal. Built on ScreenCaptureKit for window-level targeting ffmpeg cannot do. Use when the user wants a screenshot of a specific window or app, a screen recording, a GIF conversion, a before/after diff, an evidence bundle for a PR, OCR text from a window, a terminal VHS recording, a Remotion render, or wants to watch a UI for changes. Requires macOS Screen Recording permission on first run.4license: Apache-2.05---6<!-- GENERATED FILE — DO NOT EDIT.
7 This file is a verbatim mirror of library/developer-tools/agent-capture/SKILL.md,
8 regenerated post-merge by tools/generate-skills/. Hand-edits here are
9 silently overwritten on the next regen. Edit the library/ source instead.
10 See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->
11
12# Agent Capture - Printing Press CLI
13
14## Prerequisites: Install the CLI
15
16This 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:
17
181. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
19 ```bash
20 npx -y @mvanhorn/printing-press-library install agent-capture --cli-only
21 ```
222. Verify: `agent-capture-pp-cli --version`
233. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.
24
25If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):
26
27```bash
28go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-capture/cmd/agent-capture-pp-cli@latest
29```
30
31If `--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.
32
33## When to Use This CLI
34
35Reach for this when the user wants:
36
37- screenshot a specific window or app (`screenshot`, `batch` for multiple)
38- record video of a window, app, display, or region (`record`)
39- convert a recording to an optimized GIF (`convert`)
40- do a full capture + record + GIF pipeline in one command (`pipeline`)
41- diff against a baseline screenshot (`diff`) for before/after evidence
42- bundle screenshots + recording + GIF as evidence for a PR or bug report (`evidence`)
43- find the right window by fuzzy-matching its title (`find`)
44- stitch multiple screenshots into an animated GIF (`stitch`)
45- extract text from a window using macOS Vision OCR (`ocr`)
46- record a terminal session via VHS tape files (`vhs`)
47- render Remotion compositions to video or stills (`remotion`)
48- monitor a UI by periodic screenshots (`watch`)
49- save and replay capture configs (`preset`)
50
51Skip 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.
52
53## Argument Parsing
54
55Parse `$ARGUMENTS`:
56
571. **Empty, `help`, or `--help`** -> show `agent-capture --help`
582. **Starts with `install`** -> CLI installation (no MCP server ships today)
593. **Anything else** -> Direct Use (map to the best command and run it)
60## Direct Use
61
621. Check installed: `which agent-capture`. If missing, offer CLI installation.
632. If permissions aren't granted, run `agent-capture permissions` first.
643. Use `agent-capture list` to see available capture targets (open windows, displays).
654. Use `agent-capture find <text>` to fuzzy-match a window title before capturing.
665. Execute with `--json` for structured output (agent-native default):
67 ```bash
68 agent-capture <command> [args] --json
69 ```
70
71## Notable Commands
72
73| Command | What it does |
74|---------|--------------|
75| `screenshot` | Capture a window, app, display, or region |
76| `record` | Record video of a window, app, display, or region |
77| `pipeline` | Record + convert + optimize in one command |
78| `convert` | Video -> optimized GIF (two-pass palette) |
79| `diff` | Capture + diff against a baseline |
80| `evidence` | Full bundle (screenshots + recording + GIF) for a PR |
81| `batch` | Screenshot multiple apps in one invocation |
82| `find` | Fuzzy search open window titles |
83| `list` | List available capture targets |
84| `ocr` | Extract text from a window using macOS Vision |
85| `stitch` | Combine screenshots into an animated GIF |
86| `vhs` | Run a VHS tape file for terminal recording |
87| `remotion` | Render Remotion compositions |
88| `watch` | Periodic capture for UI monitoring |
89| `preset` | Save / load capture configs |
90| `permissions` | Guide Screen Recording permission setup |
91| `health` | Machine-readable CI / agent preflight |
92
93Run any command with `--help` for full flag documentation.
94
95## Agent Mode
96
97Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`.
98
99- **Pipeable** — JSON on stdout, errors on stderr
100- **Filterable** — `--select` keeps a subset of fields, with dotted-path support (see below)
101- **Previewable** — `--dry-run` shows the request without sending
102- **Cacheable** — GET responses cached for 5 minutes, bypass with `--no-cache`
103- **Non-interactive** — never prompts, every input is a flag
104
105
106### Filtering output
107
108`--select` accepts dotted paths to descend into nested responses; arrays traverse element-wise:
109
110```bash
111<cli>-pp-cli <command> --agent --select id,name
112<cli>-pp-cli <command> --agent --select items.id,items.owner.name
113```
114
115Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.
116
117
118## Exit Codes
119
120| Code | Meaning |
121|------|---------|
122| 0 | Success |
123| 2 | Usage error (wrong arguments) |
124| 3 | Target not found (no matching window or display) |
125| 4 | Permissions missing (Screen Recording not granted) |
126| 5 | Capture error (ScreenCaptureKit failure, ffmpeg failure) |
mvanhorn