Skip to content

Latest commit

 

History

History
39 lines (32 loc) · 2.39 KB

run.md

File metadata and controls

39 lines (32 loc) · 2.39 KB
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-output Emit machine-readable JSON to stdout (wrapper + ScriptExecutionResult). (Alias: --json / -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.
  • In JSON mode (--json-output / --json / -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
polter peekaboo -- run scripts/safari-login.peekaboo.json --json-output

# Capture results for later inspection but keep executing even if a step flakes
polter 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-output or --verbose to surface detailed errors.