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