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

> Reference for simforge timeline: 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).

## timeline build

Build the render timeline for a workspace's trace (deterministic, content-keyed)

```sh theme={null}
simforge timeline build [OPTIONS] [WORKSPACE]
```

Runs on: local runtime.

| Argument / flag | Notes | What |
| - | - | - |
| `<workspace>` | | The workspace directory (an imported scenario package). Omit it and pass --trace instead |
| `--trace FILE` | | A trace file (JSON or gzip; any released trace format) instead of a workspace |
| `--recorded-trace-sha256 SHA256` | | The identity recorded next to the stored trace (bound to an upgraded trace; checked against a current one) |
| `--catalog-digest SHA256` | | Actor-catalog closure digest to key the timeline by (a workspace supplies its own) |
| `--height HEIGHT` | one of auto, ground, flat; default auto | The height source |
| `--flat-z METRES` | | Elevation of the plane for --height flat |
| `--map-dir DIR` | | Use this map directory (map.xodr + derived/ground/ground-mesh.bin) instead of the installed map found by content |
| `--cache-root DIR` | | Map cache root to search. Default: SIMFORGE\_MAPS\_CACHE\_ROOT, then \$XDG\_DATA\_HOME/simforge/maps |
| `--out FILE` | | Write the canonical timeline here (`.gz` compresses). Default: the workspace's timeline/\<sha256>.json; with --trace, nothing is written |


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