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

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

## import log

A recording (simforge.recording/v1 or log-scene/v1) as a scenario package: scenario, recording, trace, import report

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

Runs on: local runtime, or hosted with --cloud.

| Argument / flag | Notes | What |
| - | - | - |
| `<recording>` | required | The recording (JSON, optionally gzipped). With --cloud: The log: a recording (JSON, optionally gzipped) or a ROS 2 MCAP lidar log |
| `--map DIR\|NAME@VERSION` | required | The installed map: 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) |
| `--report REPORT.JSON` | | The register step's import report (`simforge.import-report/v1` fields: methods, registration, laneMatch, droppedActors), merged into the package's |
| `--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) |
| `--allow-no-colliders` | | Simulate without map colliders when the map publishes none (recorded; the default refuses) |
| `--name NAME` | | The scenario's name. Default: the file's name |
| `--max-cost CENTS` | | Explicit maximum cloud cost in cents |
| `--wait` | one of true, false | Wait for the import to finish and print its scenario |
| `--download` | one of true, false | Download a finished import's scenario document, import report and Event Timeline into --out; implies --wait |
| `--stage` | one of true, false | Upload the log and price its import, starting nothing (the host prices an import from the uploaded log). --dry-run uploads nothing |
| `--lidar-topic TOPIC` | | MCAP only: the lidar topic, when the log has several |
| `--gnss-topic TOPIC` | | MCAP only: the GNSS topic, when the log has several |
| `--ego-dims L,W,H` | repeatable | MCAP only: the ego's box in metres, length,width,height (perceive's default otherwise) |
| `--ego-rear-axle-to-centre METRES` | | MCAP only: how far the ego box's centre is ahead of base\_link (the rear axle), metres |

## import openscenario

An OpenSCENARIO 1.x XML file as a scenario package; its map is found by the OpenDRIVE's sha256, and every element it cannot represent is refused by name

```sh theme={null}
simforge import openscenario [OPTIONS] --out <DIR> <FILE.xosc>
```

Runs on: local runtime.

| Argument / flag | Notes | What |
| - | - | - |
| `<file.xosc>` | required | The OpenSCENARIO 1.x XML file; its catalogs and OpenDRIVE are read beside it |
| `--out DIR` | required | The package directory to write (created; must be empty if it exists) |
| `--map-version DIR\|NAME@VERSION` | | The map version: a map directory, or name\[@version] under the maps cache. It must hold the file's OpenDRIVE. Default: the installed map whose OpenDRIVE has the file's sha256 |
| `--ego ENTITY` | | The ego entity (default: one named ego or hero, else the first vehicle) |
| `--clip-seconds S` | | The clip, when the storyboard does not stop at a simulation time |
| `--cache-root DIR` | | Map cache root to search. 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) |
| `--allow-no-colliders` | | Simulate without map colliders when the map publishes none (recorded; the default refuses) |


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