---
summary: 'Execute .peekaboo.json scripts via peekaboo run'
read_when:
  - '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
```bash
# 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.
