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

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

## transfer

Move a scenario or recording onto another map: recorded tracks warped through lane frames, behaviour re-bound by the matcher; simulated and gated, with a transfer report. Locally it needs the map's odr derivative, which `simforge maps pull` does not install yet: run it with --cloud

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

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

| Argument / flag | Notes | What |
| - | - | - |
| `<source>` | required | The source: a recording (simforge.recording/v1 or log-scene/v1, optionally gzipped), a v2 scenario, or a package directory holding one |
| `--map DIR\|NAME@VERSION` | required | The target map: a map directory, or name\[@version] under the maps cache (semantic profile) |
| `--source-map DIR\|NAME@VERSION\|FILE.xodr` | | The source's map (default: the map the source names): a map directory, name\[@version], or a bare OpenDRIVE file for a recording |
| `--recording FILE` | repeatable | A recording the scenario's replay routes pin (repeatable) |
| `--from-root` | | Transfer from the source's root: follow its recording's `derivedFrom` (a transfer's warped recording, a scenario's rollout of the one recording it replays) through the `--recording` files to the recording it started from, and transfer that onto the map. The source's own scenario content (its edits) is not carried; the report records the chain in `source.root` |
| `--sites SITES` | one of network, corridor, same; default network | Where recorded motion looks for sites |
| `--profile PROFILE` | one of pure, generalized, key-only; default pure | Which recorded actors transfer |
| `--crossing CROSSING` | one of any, faithful; default any | How a crosswalk crossing must land |
| `--max-try N` | | Sites tried (transferred, gated and simulated) before giving up \[default: 6 per --max-sites] |
| `--max-sites N` | default 1 | Distinct accepted sites to transfer onto (recorded motion), ranked; more than one writes each to site-\<rank>/ under --out |
| `--site-cell-m M` | | With --max-sites: one site per cell of this size (metres) and heading quadrant \[default: 200]. Smaller admits near-copies of the same drive |
| `--min-path-separation-m M` | | With --max-sites: no two placements whose egos' target paths come within this distance (metres) \[default: 10] |
| `--out DIR` | required | The output directory (created; must be empty if it exists) |
| `--cache-root DIR` | | Map cache root to search for NAME\@VERSION. Default: SIMFORGE\_MAPS\_CACHE\_ROOT, then \$XDG\_DATA\_HOME/simforge/maps |
| `--allow-no-colliders` | | Simulate without map colliders when the map publishes none (recorded; the default refuses) |
| `--budget-s SECONDS` | default 32400 | Last-resort wall-clock limit, seconds: a transfer still running then fails whole (`transfer_budget_exceeded`, nothing written). Set far above any healthy transfer (about 10x the slowest seen); what a transfer tries is bounded by --max-try and the import's rounds, never by time, so its result does not depend on the machine |
| `--mode MODE` | one of motion, semantic; default motion | How the scenario moves to the target map |
| `--experimental` | | Allow an experimental --mode |
| `--target-control CLASS,...\|as-source` | default as-source | Semantic mode: the target approach classes accepted, comma separated (two\_way\_stop\_minor, two\_way\_stop\_major, all\_way\_stop, signal, yield\_minor, yield\_major, stop\_line\_only, uncontrolled, mixed), or `as-source`. A class other than the source's is recorded as a requested substitution |
| `--t-junction` | | Semantic mode: also fit a four-arm source onto a T-junction whose stem is the ego's approach; the roles on the source's opposite arm are left out (recorded), and each such placement is tagged `t_junction` |
| `--policy FILE` | | A transfer policy JSON file to transfer with, instead of a registered version |
| `--policy-version VERSION` | | A registered transfer policy version (sdk/contracts/transfer-policies.json, e.g. `transfer-v2`). Default: the registry's active version |
| `--revision REVISION_ID` | | The immutable revision of a hosted scenario SOURCE |
| `--name NAME` | | The new scenario's name. Default: `<source title> · <target map>` |
| `--max-cost CENTS` | | Explicit maximum cloud cost in cents |
| `--wait` | one of true, false | Wait for the transfer to finish |
| `--download` | one of true, false | Download a finished transfer's new scenario, report and receipt into --out; implies --wait |
| `--stage` | one of true, false | Save a SOURCE file to the workspace as an immutable revision (free) and price the transfer on it; starts nothing. --dry-run saves nothing |


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