Skip to main content
Use sovara rerun when you want to test a small change to one recorded LLM call without rerunning the entire agent. Typical uses:
  • Change a prompt fragment
  • Change an existing model parameter such as max tokens
  • Replace a user message from a file
  • Compare whether one step would have produced a better answer

​
Requirements

Before rerunning a step:
  1. Record or locate a trace.
  2. Inspect the trace and find the step ref.
  3. Confirm the step is an LLM call.
  4. Inspect the exact input keys you want to edit.
  5. Configure a replay API key for the provider used by that step.
Use the trace ID shown in Sovara or a unique ID prefix. To use your own identifier from the SDK, include --project-id.
For a step recorded through Palantir Foundry, store the Foundry token under the palantir provider:
See Replay keys for provider key management.

​
Basic rerun

With your own identifier:
This reruns current lesson retrieval, replays the resulting LLM input, and returns the new output plus the retrieval snapshot. To compare the step without retrieving or injecting new lessons:
The flag removes the selected step’s recorded lesson injection and skips fresh retrieval for that step.

​
Preview a lesson proposal

This retrieves lessons as if the proposal were merged into the project’s current production corpus. It includes lesson additions, edits, moves, deletions, and retrieval configuration changes. The server freezes the merged corpus before retrieval and rejects merge conflicts before calling the replay provider. Nothing is published or merged. Proposal reruns keep the source step unchanged. Each successful attempt returns its own rerun_id, output, and lesson_retrieval.lesson_source containing the proposal ID, proposal head revision, production revision, and merged corpus hash. The latest 100 attempts are available through GET /ui/trace/{trace-id}/reruns. Ordinary reruns continue to replace the selected step’s displayed override. The proposal must belong to the trace’s project, and rerunning requires editor access. --proposal cannot be combined with --disable-lesson-injection. A server advertising proposal rerun support is required; the CLI refuses older servers rather than silently performing an ordinary rerun.

​
Edit string values

Use --set KEY=VALUE for a string edit:
Keys must use the flattened names shown by probe; unknown keys are rejected:

​
Edit JSON values

Use --set-json for numbers, booleans, arrays, objects, or null:
For arrays or objects, quote the JSON for your shell:

​
Read an edit from a file

Use --set-file KEY=PATH for larger prompt text:

​
Combine edits

​
Output

Successful reruns return JSON with:
  • status
  • trace_id
  • step_ref
  • overwritten_output
  • lesson_retrieval
For ordinary reruns, the Sovara app shows the rerun output for the selected step. Proposal reruns return a separate result without changing that display.

​
Limits

sovara rerun is for one recorded LLM step. It does not rerun tool calls, custom traced functions, or the full agent. If a provider key is missing, set it for the trace’s project with the project-scoped command shown above. If the provider is not replayable with an API key, inspect the step and rerun the full agent instead.