sp replay

When agents use this: Start and monitor replay plans. For failed cases and diffs, see replay case and replay diff.

Synopsis

Create, monitor, stop, and rerun replay plans against recorded cases.

Subcommands

Subcommand	Description
run	Create plan (POST /api/createPlan)
status <planId>	Poll progress (GET /api/progress)
statistics <planId> --app <appId>	The plan's summary row, with its case counts
report <planId> --app <appId>	The plan's statistic report
stop <planId>	Stop plan
rerun <planId>	Re-run plan

Case lists, diffs and metadata are under replay case and replay diff.

Flags (run)

Flag	API field	Description
--app	appId	Application id (required)
--env	targetEnv	Replay target base URL (required), not a symbolic name. Must include http:// or https:// and a host, e.g. http://travel-ota:8080. The CLI rejects values like staging or dev.
--suite	—	Case suite. Set to Pinned for manually pinned cases only. AutoPinned is not selectable.
--from	caseSourceFrom	Rolling selection start time (duration e.g. -24h or RFC3339). Ignored for --suite Pinned.
--to	caseSourceTo	Rolling selection end time (default: now). Ignored for --suite Pinned.
--limit	caseCountLimit	Max cases
--name	planName	Display name
--operation	operationIds	Repeatable; filter operations
--enable-mock	enableMock	Mock during replay (default true)
--no-mock	enableMock	Disable mock (enableMock=false; overrides --enable-mock)
--allow-empty	—	Create a Rolling plan even when no recorded cases exist in the window (default false). It does not make an empty Pinned suite runnable.
--watch	—	On run: create plan then poll until terminal; on status: poll an existing plan

Examples

sp record case list --app my-app --since -24h --json   # verify cases exist first
sp replay run --app my-app --env http://travel-ota:8080 --from -24h --enable-mock --json
sp replay run --app my-app --env http://travel-ota:8080 --suite Pinned --watch --json
sp replay run --app my-app --env http://travel-ota:8080 --from -24h --no-mock --watch --json
sp replay status plan-xyz --watch --json
sp replay stop plan-xyz --json
sp replay rerun plan-xyz --json

Case selection

The default selection is Rolling: cases are selected from the --from/--to window (the default window is the last 24 hours when the flags are omitted).

--suite Pinned selects the explicit manual Pinned collection for the application. It is not a time-window query, so --from and --to are ignored. A case remains eligible after it falls outside the normal recording window. Automatically managed AutoPinned cases are excluded.

sp replay run \
  --app my-app \
  --env http://travel-ota:8080 \
  --suite Pinned \
  --watch \
  --json

Preflight (run, Rolling)

Before POST /api/createPlan, the CLI queries POST /api/storage/replay/query/replayCase for the same --app, --from, and --to window. If no entry cases exist and --allow-empty is not set:

{
  "ok": false,
  "command": "replay run",
  "error": {
    "code": "NO_RECORDED_CASES",
    "message": "no recorded cases for app …; run the app with the agent and send traffic first, or use --allow-empty"
  }
}

For --suite Pinned, the CLI checks the manual Pinned collection instead. If it is empty, the command fails with NO_PINNED_CASES; --allow-empty does not override this safety check.

JSON output (run)

{
  "ok": true,
  "command": "replay run",
  "data": {
    "planId": "plan-xyz",
    "result": 1,
    "desc": "success"
  }
}

JSON output (run --watch)

With --json, stdout is newline-delimited envelopes:

1. One success envelope for plan creation (command: replay run).
2. One or more progress envelopes (command: replay status).
3. The final progress envelope includes "finished": true in data.

JSON output (status)

{
  "ok": true,
  "command": "replay status",
  "data": {
    "percent": 42,
    "lastUpdateTime": "2026-06-27 10:00:05"
  }
}

status returns the scheduler's progress as is: percent and lastUpdateTime, no plan status. With --watch, it prints one such envelope per poll and adds "finished": true to the last one; run --watch may end with the plan's statistics row (with "finished": true) instead. A plan that hasn't finished after 10 minutes ends the watch with API_ERROR (exit 1).

JSON output (stop)

{
  "ok": true,
  "command": "replay stop",
  "data": {
    "result": 1,
    "desc": "success"
  }
}

statistics and report

Both need --app as well as the plan ID:

sp replay statistics <planId> --app <appId> --json
sp replay report <planId> --app <appId> --json

statistics looks up the plan's statistics row by app and plan ID; if there is none, it fails with no statistics for plan <planId>. report returns the backend's statistic report for the plan unchanged.

The verdict used to gate a pipeline — findings.state — comes from the Open API, not from these commands.

JSON output (rerun)

{
  "ok": true,
  "command": "replay rerun",
  "data": {
    "planId": "plan-xyz-rerun",
    "result": 1,
    "desc": "success"
  }
}

REST mapping

Subcommand	Method	Path
run	POST	/api/createPlan
run (webhook style)	GET	/api/createPlan?appId=… (discouraged for CLI; use POST)
status	GET	/api/progress?planId=
stop	GET	/api/stopPlan?planId=
rerun	POST	/api/reRunPlan
statistics	POST	/api/report/queryPlanStatistics
report	POST	/api/report/queryPlanStatistic

Body for run: BuildReplayPlanRequest (schedule module).

Response envelope: CommonResponse (result, desc, data).

Related

• replay case
• replay diff
• Diagnose replay failure