olyx replay

Replay a local trace, select an alternative model, or compare model aliases.

Send the successful model requests from a saved trace again. Replay uses your current configuration and API keys, creates new traces, and keeps the original trace.

Synopsis

olyx replay TRACE_ID [--model ALIAS | --compare ALIAS1,ALIAS2] [--config FILE] [--dry-run]

Arguments and options

Argument or option	Description
`TRACE_ID`	Source trace ID returned by route or listed by debug
`--model ALIAS`	Override recorded model aliases with one configured alternative
`--compare ALIASES`	Comma-separated aliases to execute and return together
`--config FILE`	Configuration pointing to the source trace database and current routes
`--dry-run`	Print replay parameters without opening the runtime or calling providers

Use either --model or --compare, not both. Replay waits for the model calls to finish before returning. Comparisons run one alias at a time, with a maximum of 16 aliases.

Replay the recorded route

olyx debug
olyx replay TRACE_ID

Without --model or --compare, replay uses the alias saved with each successful request. It looks up that alias in your current configuration. If you changed the provider list, replay may call a different endpoint or model. Keep a copy of the original configuration if you need the same routing setup.

Select an alternative or compare

olyx replay TRACE_ID --model quality
olyx replay TRACE_ID --compare fast,quality
olyx replay TRACE_ID --config examples/olyx.json --compare fast,quality

Replay returns JSON with the original trace ID and the new trace data. Comparisons put the new traces in comparison.replays. Each trace contains its model response and provider attempts. Olyx does not score or rank the answers.

Comparisons attempt every alias and include all results in comparison.replays. If any replay fails, the command exits 1 after writing the JSON result. Successful replays remain in storage; inspect each replay’s status and trace before retrying.

olyx replay TRACE_ID --compare fast,quality > comparison.json 2> comparison-errors.log

Use an optional JSON processor to inspect the saved result:

jq '.comparison.replays[] | {external_id, status}' comparison.json

jq is only needed for the filtering example. The CLI returns JSON without it.

What can be replayed

Replay uses successful model calls. If the trace has none, it returns no_replayable_steps.
For a streaming request, replay waits for the complete response and returns it together.
Replay returns model tool calls. It does not run tools or repeat actions taken by your application.
You cannot replay expired traces or traces from an earlier command that used in-memory storage.

See storage and debug to locate a source trace.