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

# simforge recording

> Reference for simforge recording: usage, arguments and flags, generated from the CLI.

Generated from the CLI's own help (CLI 0.2.0-rc.5). Global flags and exit codes are on the [command reference](/cli).

## recording from-trace

Save a simulation's trace (a rollout) as a simforge.recording/v1 recording

```sh theme={null}
simforge recording from-trace [OPTIONS] --out <FILE> --producer <PRODUCER> <TRACE|DIR>
```

Runs on: local runtime.

| Argument / flag | Notes | What |
| - | - | - |
| `<trace\|dir>` | required | The trace (`trace.json[.gz]`), or a workspace/package directory (its `simulation/trace.json.gz`) |
| `--out FILE` | required | The recording to write (gzipped canonical JSON; the conventional name is `<sha256>.rec.json.gz`) |
| `--producer PRODUCER` | required | The producer recorded in `source.producer` (id and version) |
| `--clip-ref CLIP_REF` | default | An opaque reference to the rollout (`source.clipRef`) |
| `--license LICENSE` | | The licence of the rollout's inputs, when it carries one |
| `--ego EGO` | | The ego actor id (default: the trace's metricSubject) |
| `--map-version MAP_VERSION` | | The map release version the trace ran on (`map.version`), when known |

## recording inspect

Read a recording through the contract: its digest, map, size and lineage

```sh theme={null}
simforge recording inspect [OPTIONS] <RECORDING>
```

Runs on: local runtime.

| Argument / flag | Notes | What |
| - | - | - |
| `<recording>` | required | The recording (simforge.recording/v1 or log-scene/v1, optionally gzipped) |

## recording scaffold

A registered recording as a scenario package that carries no simulation: the scaffolded scenario, the recording it pins and the report of the operation that made it

```sh theme={null}
simforge recording scaffold [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <RECORDING>
```

Runs on: local runtime.

| Argument / flag | Notes | What |
| - | - | - |
| `<recording>` | required | The recording (simforge.recording/v1 or log-scene/v1, optionally gzipped); registered on the map |
| `--map DIR\|NAME@VERSION` | required | The map the recording was registered on: a map directory, or name\[@version] under the maps cache (semantic profile) |
| `--out DIR` | required | The package directory to write (created; must be empty if it exists) |
| `--title NAME` | | The scenario's name (`meta.name`; default "\<producer> \<clipRef>") |
| `--report REPORT.JSON` | | The report the recording's `derivedFrom.reportSha256` names, packaged byte for byte (`transfer-report.json` or `import-report.json`, by its schema) |
| `--cache-root DIR` | | Map cache root to search for NAME\@VERSION. Default: SIMFORGE\_MAPS\_CACHE\_ROOT, then \$XDG\_DATA\_HOME/simforge/maps |
| `--assets-root DIR` | | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE\_ACTOR\_ASSETS\_ROOT, then \$XDG\_DATA\_HOME/simforge/actor-assets |
| `--actor-closure SHA256` | | The actor closure the package pins (default: this CLI's pinned public closure) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.