> ## 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.

# Report runs

> Run a command unchanged and print metadata for the SDK-created Sovara run.

Use `sovara record` when an instrumented application should print its run ID
and project metadata in the terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara record -- python agent.py
```

The only supported form is:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
usage: sovara record -- <command> [args...]
```

Everything after `--` is executed unchanged. The application SDK still owns
the project name, run name, persistent client run ID, tracing, and execution
timeouts.

## What `record` does

1. Gives the child process a private result-file path through
   `SOVARA_RUN_FILE`.
2. Runs the command with its original arguments and terminal streams.
3. Waits for the SDK to finish and publish its run metadata.
4. Prints JSON with the child status, exit code, duration, and observed run.
5. Exits with the child's exit code.

When a run is observed, the output includes fields such as:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "exit_code": 0,
  "duration_seconds": 1.23,
  "run_observed": true,
  "run_id": "...",
  "project_id": "...",
  "project_name": "support-agent",
  "appended": false,
  "inspect_command": "sovara probe ..."
}
```

If the command creates several top-level runs, the last completed run is
reported.

## What `record` does not do

`record` does not instrument an arbitrary Python or Node.js program. An
uninstrumented command still runs, but the result contains
`"run_observed": false` and a message explaining that no SDK-created run was
seen.

Add the run boundary in application code first:

* Python: `SovaraClient(project_name="...").run(...)`
* TypeScript: `new SovaraClient({ projectName: "..." })`

Run names and durable application IDs also belong in those SDK calls.

## Normal execution is supported

The wrapper is optional. This records the same run without printing metadata:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
python agent.py
```

After `record`, continue with the emitted `inspect_command` or see
[Inspect runs](/cli/inspect).