| summary |
read_when |
| Execute .peekaboo.json scripts via peekaboo run |
| batching multiple CLI steps into a reusable automation script |
| capturing structured execution results for regression tests |
|
peekaboo run
peekaboo run loads a .peekaboo.json (PeekabooScript) file, executes every step via ProcessService, and reports the aggregated result. It’s the same engine the agent runtime uses for scripted flows, which makes it ideal for regression suites or reproducing agent traces.
Key options
| Flag |
Description |
<scriptPath> |
Positional argument pointing at a .peekaboo.json file. |
--output <file> |
Write the JSON execution report to disk instead of stdout. |
--no-fail-fast |
Continue executing the remaining steps even if one fails (default behavior is fail-fast). |
--json |
Emit machine-readable JSON to stdout (wrapper + ScriptExecutionResult). (Alias: --json-output / -j) |
Implementation notes
- Scripts are parsed on the main actor via
services.process.loadScript, so relative paths (~/, ./) resolve exactly as they do when agents run scripts.
- Execution delegates to
services.process.executeScript, which returns a [StepResult] containing individual timings, success flags, and error strings; the command wraps those in a summary with total durations and counts.
--output writes via JSONEncoder().encode + atomic file replacement; if the write succeeds but the script fails, you still get the partial data for debugging.<scriptPath> and --output accept ~/....- Script-level
see screenshot paths and clipboard file/output paths also accept ~/....
- In JSON mode (
--json / --json-output / -j), stdout is a single CodableJSONResponse<ScriptExecutionResult> payload (top-level success tracks overall script success).
- The command exits non-zero if any step fails (even when
--no-fail-fast continues execution) so CI can register the run as failed.
Examples
# Run a script and view the JSON summary inline
peekaboo run scripts/safari-login.peekaboo.json --json
# Capture results for later inspection but keep executing even if a step flakes
peekaboo run ./flows/regression.peekaboo.json --no-fail-fast --output /tmp/regression-results.json
Troubleshooting
- Verify Screen Recording + Accessibility permissions (
peekaboo permissions status).
- Confirm your target (app/window/selector) with
peekaboo list/peekaboo see before rerunning.
- Re-run with
--json or --verbose to surface detailed errors.
