> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerun LLM steps

> Replay one recorded LLM step with edited input from the CLI.

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 run.
2. Inspect the run 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id>
sovara probe <run-id> --step 3 --input --key-regex "body"
sovara replay-keys set anthropic --api-key-env ANTHROPIC_API_KEY
```

See [Replay keys](/cli/replay-keys) for provider key management.

## Basic rerun

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> --step 3
```

This replays the recorded LLM input as-is and returns the new output.

## Edit string values

Use `--set KEY=VALUE` for a string edit:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> \
  --step 3 \
  --set body.messages.0.content="Answer using the policy excerpt only."
```

Keys must use the flattened names shown by `probe`; unknown keys are rejected:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id> --step 3 --input --key-regex "body.messages"
```

## Edit JSON values

Use `--set-json` for numbers, booleans, arrays, objects, or null:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> \
  --step 3 \
  --set-json body.max_tokens=512
```

For arrays or objects, quote the JSON for your shell:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> \
  --step 3 \
  --set-json 'body.stop=["</answer>"]'
```

## Read an edit from a file

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> \
  --step 3 \
  --set-file body.system.0.text=prompt_variant.txt
```

## Combine edits

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara rerun <run-id> \
  --step 3 \
  --set-file body.system.0.text=prompt_variant.txt \
  --set body.messages.0.content="Use the attached table." \
  --set-json body.max_tokens=512
```

## Output

Successful reruns return JSON with:

* `status`
* `run_id`
* `step_ref`
* `overwritten_output`

The Sovara app will show the rerun output for the selected step.

## 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
with `sovara replay-keys set`. If the provider is not replayable with an API
key, inspect the step and rerun the full agent instead.