# Referencia de la CLI
> Traducción de la [página original en inglés](https://github.com/lmonteirotech/OmsiLaunch/blob/v0.1.0-beta.3/docs/reference/cli.md) de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si difieren, prevalecen la página en inglés y el código.
Esta página es la referencia completa y normativa de la línea de comandos de OmsiLaunch `0.1.0-beta3`: los tres ejecutables, la gramática de argumentos, el orden de despacho, cada palabra de comando, cada ruta jerárquica, cada flag, los envelopes de salida y el comportamiento ante errores de cada comando. Se genera a partir de `tools\OmsiLaunch.Cli\Program.cs` (`CliProgram.RunAsync`, `OwnerSession.RunAsync`, `CliInput.Parse`, `CliInput.KnownFlags`, `CliInput.AcceptedNoEffectFlags`, `CliInput.CommandWordsAccepted`, `CliInput.HierarchicalRoutes`, `CliInput.BuildSpecAsync`, `CliEventWatch`), `tools\OmsiLaunch.Cli\LaunchSpecJson.cs` y los dos shims nativos de `tools\OmsiLaunch.Bootstrapper`. Los resultados del proceso se enumeran en [códigos de salida](https://omsilaunch.omsimods.com.br/es/docs/reference/exit-codes/index.md); los códigos de error, en [errores](https://omsilaunch.omsimods.com.br/es/docs/reference/errors/index.md); las invocaciones de ejemplo, en [ejemplos de la CLI](https://omsilaunch.omsimods.com.br/es/docs/reference/cli-examples/index.md).
## Ejecutables
| Archivo | Subsistema | Función | Diferencias |
|---|---|---|---|
| `OmsiLaunch.exe` | Consola | Bootstrapper nativo (`OmsiLaunch.Bootstrapper.cpp`): resuelve su propio directorio, divide la línea de comandos en tokens con `CommandLineToArgvW`, localiza `hostfxr` mediante `nethost.dll` y ejecuta `OmsiLaunch.Controller.dll` con los mismos argumentos. | Se escribe salida en la consola; el código de salida del proceso es el del controlador administrado o un código del shim `100`..`106` si no se pudo iniciar el host de .NET. |
| `OmsiLaunchW.exe` | Windows (GUI) | El mismo shim (`OmsiLaunch.WindowsHost.cpp`) compilado para el subsistema Windows. Establece la variable de entorno `OMSILAUNCH_WINDOWS_HOST=1` antes de iniciar el controlador. | Sin consola: la salida de consola se suprime salvo que se indique `--json` (`WindowsHost.SuppressConsole`), los fallos se muestran como cuadros de mensaje (`WindowsHost.ShowFailure`: mensaje, `Code: OL_E_...` y la indicación `See .omsilaunch\diagnostics for details.`), y un fallo del shim `100`..`106` se muestra como `OmsiLaunch could not start the .NET host (code N).` Comportamiento completo: [referencia de OmsiLaunchW.exe](https://omsilaunch.omsimods.com.br/es/docs/reference/omsilaunchw/index.md). |
| `OmsiLaunch.Controller.dll` | Administrado (x64, `net6.0-windows`, Windows Forms) | El propio controlador. Los usuarios nunca lo invocan directamente; ambos shims pasan la ruta del controlador como primer argumento del host, de modo que nunca aparece en la lista pública de argumentos. | Requiere el runtime de .NET 6 x64 con `Microsoft.WindowsDesktop.App`; consulta [instalación](https://omsilaunch.omsimods.com.br/es/docs/getting-started/installation/index.md). |
`nethost.dll` debe estar junto a los shims. Los shims no leen ningún argumento por sí mismos; todos los argumentos llegan sin cambios a `CliInput.Parse`, por lo que `OmsiLaunch.exe` y `OmsiLaunchW.exe` aceptan exactamente la misma sintaxis.
## Modelo de invocación
### Gramática de argumentos (`CliInput.Parse`)
| Forma | Significado |
|---|---|
| `/key:value`, `/key`, `-key:value`, `-key` | Un flag. La clave no distingue mayúsculas de minúsculas; el valor es todo lo que sigue al primer `:`. Las claves desconocidas fallan con `OL_E_INVALID_ARGUMENT` (`Unknown argument: ...`), salida `2`. |
| `--key=value` | Un argumento de runtime para la operación de runtime seleccionada (por ejemplo, `--handle=rv-000001`). Todo token `--` que contenga `=` es un argumento de runtime, nunca un flag. |
| `--json`, `/json` | Salida estructurada (consulta [Formatos de salida](#output-formats)). `--json` es el único token `--` sin `=` que tiene significado; se analiza como el flag `/json`. |
| palabra suelta | Si aún no se ha visto ninguna palabra de comando y la palabra es una de las [palabras de comando](#command-words), se convierte en el comando. Una vez presente una palabra de comando, toda palabra suelta posterior es una palabra de comando (la ruta). En caso contrario, la primera palabra suelta es la raíz de la instalación y cualquier palabra suelta posterior se añade a la ruta. |
Consecuencias: una ruta jerárquica (`time get`) no se puede combinar con un argumento de instalación colocado después de ella (`time get D:\OMSI` es la ruta desconocida `time get d:\omsi`, salida `2`). `D:\OMSI time get` se acepta, pero es **modo propietario** (se inicia una sesión nueva y la operación se ejecuta una vez dentro de ella). Los errores de análisis (`ArgumentException`, `FormatException`, `InvalidDataException`, `OverflowException`) y los errores del perfil de sesión (`SessionProfileException`) se notifican antes de ejecutar nada, siempre con salida `2`.
### Raíz de la instalación
- Un argumento de instalación explícito en forma de palabra suelta tiene prioridad sobre `RootPath` en un archivo `/spec` (`CliInput.BuildSpecAsync`).
- `.` significa el directorio que contiene el ejecutable (`AppContext.BaseDirectory`), nunca el directorio de trabajo del llamador (`CliInput.ResolveInstallationRoot`). Un paquete portable depende de esto.
- Cuando se omite el argumento, las operaciones en modo propietario (`/new`, `/saved`, `/spec`, `/list`, `/recovery-status`, `/recover`) también usan el directorio del ejecutable. La ruta se normaliza con `Path.GetFullPath`.
- Los comandos en modo cliente nunca aceptan un argumento de instalación: se dirigen al endpoint de control local de la instalación en la que reside el ejecutable (`AppContext.BaseDirectory`). Consulta [control local](https://omsilaunch.omsimods.com.br/es/docs/reference/local-control/index.md).
### Propietario y cliente
- **Propietario**: el proceso que planifica, inicia, supervisa y restaura una sesión (`OwnerSession.RunAsync`). Mantiene el lease de la instalación (`Local\OmsiLaunch.Installation.`) y la transacción de configuración, expone el endpoint de control local mientras la sesión está activa y muestra el [icono de la bandeja](https://omsilaunch.omsimods.com.br/es/docs/reference/windows-tray/index.md). Exactamente un propietario por instalación: si un propietario ya responde a `session.status` en el endpoint de control, un segundo lanzamiento falla con `OL_E_SESSION_ALREADY_ACTIVE` (salida `7`).
- **Cliente**: cualquier invocación sin argumento de instalación que envíe `session status`, `session stop`, `events read`, `events watch` o una operación de runtime. Se reenvía por la canalización de control local; sin propietario falla con `OL_E_NO_ACTIVE_SESSION` (salida `4`).
### Orden de despacho (`CliProgram.RunAsync`)
1. `/silent` (cuando no se está ejecutando ya bajo `OmsiLaunchW.exe`): inicia `OmsiLaunchW.exe` desde el directorio del ejecutable mediante `ShellExecute` (sin herencia de handles) con los mismos argumentos excepto `/silent`/`--silent`, escribe el envelope `silent` (`delegated`, `host_process_id`) y devuelve `0`. El proceso de consola no espera a la sesión; consulta [OmsiLaunchW.exe](https://omsilaunch.omsimods.com.br/es/docs/reference/omsilaunchw/index.md#silent-delegation). `OL_E_WINDOWS_HOST_MISSING` / `OL_E_WINDOWS_HOST_START_FAILED` devuelven `7`.
2. `/version`: envelope `version` con `product`, `version` (versión informativa del ensamblado, tomada de `OmsiLaunch.Version.props`, `0.1.0-beta3`), `protocol_version` (`0.1`), `supported_family` (`OMSI_2_3_004_COMMON`); salida `0`.
3. `capabilities`: envelope con todos los descriptores `PublicStableBeta` o `PublicExperimental` de `PublicCapabilityRegistry`; salida `0`.
4. `help [family]`: envelope `help` con `usage`, `product_version`, `protocol_version`, `family` y los `commands` públicos (`CliRoute`, `Description`, `Classification`, `RuntimeValidation`), filtrados opcionalmente por familia; salida `0`.
5. `profiles`: envelope con `family` y las variantes de ejecutable `supported` (`ALTERNATE_LAA` `692EBFBF...`, `runtime_validated=true`; el hash de Steam LAA `7DAB063D...` con `validation_status=pending_beta_field_validation`); salida `0`.
6. Operación de runtime de cliente (sin argumento de instalación y con una ruta o `/runtime:`): los argumentos se validan con `PublicCapabilityRegistry.ValidateRuntimeArguments` (`OL_E_RUNTIME_OPERATION_UNKNOWN`, `OL_E_RUNTIME_ARGUMENT_REQUIRED`, salida `2`) y después se reenvía `runtime.execute` con un timeout de 8 s (30 s para `road-vehicles.spawn`).
7. `session status` de cliente (750 ms), `session stop` (vinculado al id de la sesión activa, 750 ms), `events read` (750 ms), `events watch` (sondea cada 250 ms hasta Ctrl+C).
8. `detect`, o **ningún argumento en absoluto** (sin instalación, sin comando, sin `/?`, sin `/spec`, sin flag de lanzamiento, sin flag de recuperación, sin `/list`): enumera los procesos `Omsi` y sondea el endpoint de control (250 ms); envelope `detect`; salida `0`.
9. `/?` o `/help`: imprime el texto de uso, salida `0`. Cualquier otra invocación que tenga una palabra de comando pero ninguna ruta despachable (por ejemplo, `d3d` sola o `session status D:\OMSI`) imprime el texto de uso y sale con `2`.
10. Modo propietario. Condiciones previas: `plugins\OmsiLaunch.Plugin.opl` y `plugins\OmsiLaunch.Native.x86.dll` deben existir junto al ejecutable (`OL_E_RUNTIME_INSTALLATION_INCOMPLETE`, salida `7`). `release-manifest.json` junto al ejecutable, cuando existe, proporciona los hashes esperados del plugin.
11. `/recovery-status` / `/recover`: `RecoverPendingAsync`; envelope `recover` con `pending`, `recovered`, `diagnostics`; salida `8` solo cuando se solicitó una restauración y no se completó; en caso contrario, `0`.
12. `/list:`: `DiscoverAsync`; envelope `content.list`; salida `0`.
13. Construye el `LaunchSpec` (`BuildSpecAsync`), lo planifica (`PlanSessionAsync`) e imprime el plan. `/plan` o `/validate`: salida `0` si `IsRunnable`; si no, `1`. Un plan no ejecutable nunca inicia OMSI (salida `1`); bajo `OmsiLaunchW.exe`, un lanzamiento con un plan no ejecutable muestra su último diagnóstico `OL_E_` en un cuadro de mensaje (auditoría de documentación BUG-06). La planificación también verifica el conjunto de archivos del plugin permanente instalado frente a `release-manifest.json`, de modo que un plugin ausente o modificado hace que el plan no sea ejecutable (`OL_E_PERMANENT_PLUGIN_*`).
14. Sondea si existe un propietario (`OL_E_SESSION_ALREADY_ACTIVE`, salida `7`) y después `OwnerSession.RunAsync`.
### Ciclo de vida del propietario (`OwnerSession.RunAsync`)
1. `StartSessionAsync(plan)`. A partir de aquí, toda ruta de salida llega a `CloseAsync` en un bloque `finally`: excepciones, Ctrl+C (`Console.CancelKeyPress`), cierre de la consola / cierre de sesión de Windows (`AppDomain.ProcessExit` con un margen de 4 s para detención + restauración; lo que quede lo recupera el diario en el siguiente inicio), «End session» (finalizar la sesión) de la bandeja, `session.stop` por la canalización y `/observe-seconds`.
2. Se crea el icono de la bandeja, salvo que `Presentation.SuppressTrayIcon` esté establecido en el spec.
3. Espera `Running` durante `StartupTimeoutSeconds + 5` segundos. Se imprime el estado. Si el estado no es `Running`, salida `1` (`OmsiLaunchW.exe` muestra `The OMSI session did not reach gameplay.` con el último diagnóstico `OL_E_` u `OL_E_SESSION_START_FAILED`).
4. Se ejecutan los lotes de validación (`/runtime-batch`, `/runtime-write-batch`, `/d3d-batch`) y escriben sus artefactos.
5. Se inicia el endpoint de control local.
6. `/runtime:` se ejecuta una vez (5 s, 15 s para `road-vehicles.spawn`); el resultado se escribe en `\.omsilaunch\diagnostics\-runtime-operation.json` y se imprime. Un comando de runtime que falla nunca termina la sesión (en su lugar se imprime `runtime_error`).
7. Espera: con `/observe-seconds:n`, la sesión se detiene tras `n` segundos **o** antes ante una detención desde la bandeja o la canalización, o cuando OMSI termina; sin él, el propietario espera hasta que OMSI termine o se solicite una detención.
8. Se imprime el estado final; salida `0` si `Completed`, `1` en caso contrario.
`session.stop`, «End session» de la bandeja, Ctrl+C y `CloseAsync` solicitan todos la detención canónica: OMSI se termina con `TerminateProcess` (la rutina de cierre propia de OMSI no se ejecuta y OMSI no reescribe `options.cfg`) y después se restauran todos los archivos propiedad de la sesión. Consulta [ciclo de vida de la sesión](https://omsilaunch.omsimods.com.br/es/docs/concepts/session-lifecycle/index.md) y [transacciones y recuperación](https://omsilaunch.omsimods.com.br/es/docs/concepts/transactions-and-recovery/index.md).
## Palabras de comando
Todas las palabras aceptadas en primera posición (`CliInput.CommandWordsAccepted`):
| Palabra | Propósito | Modo | Notas |
|---|---|---|---|
| `capabilities` | Enumera las capacidades públicas | Local, sin sesión | Envelope `capabilities`. |
| `profiles` | Enumera las variantes de `Omsi.exe` compatibles | Local, sin sesión | Envelope `profiles`. |
| `detect` | Informa de los procesos `Omsi.exe` y de un propietario activo | Local, sin sesión | También es el valor predeterminado cuando no se indica ningún argumento. Estados: `NO_OMSI_FOUND`, `OMSI_FOUND_UNMANAGED`, `UNKNOWN_BINARY_FOUND` por proceso cuando no se puede inspeccionar el binario; `active_omsilaunch_instance`, `managed_session`. |
| `help` | Uso y catálogo público de comandos | Local, sin sesión | `help ` filtra por familia de capacidades (`session`, `time`, `weather`, `map`, `camera`, `vehicles`, `player`, `humans`, `timetable`, `scripts`, `constants`, `curves`, `hof`, `drivers`, `tickets`, `d3d`, `events`). |
| `session` | `session status`, `session stop` | Cliente | Exactamente una palabra a continuación; cualquier otra cosa imprime el uso, salida `2`. `session plan`/`session start` son nombres de rutas de la API, no palabras de la CLI: usa `/plan` y `/new`. |
| `events` | `events read`, `events watch` | Cliente | `read` devuelve una vez la lista acotada de eventos; `watch` imprime cada evento nuevo (por `Sequence`) como un envelope `events.watch` cada 250 ms hasta Ctrl+C (salida `0`), `4` cuando no responde ningún propietario, `7` ante un error de control. |
| `time` | `time get`, `time set` | Ruta de cliente | |
| `weather` | `weather get`, `weather set`, `weather actual get` | Ruta de cliente | |
| `map` | `map get` | Ruta de cliente | |
| `camera` | `camera get`, `camera set`, `camera lock`, `camera unlock` | Ruta de cliente | |
| `vehicles` | `vehicles list`, `vehicles get`, `vehicles summary`, `vehicles spawn`, `vehicles place-random` | Ruta de cliente | |
| `player` | `player get` | Ruta de cliente | |
| `humans` | `humans list`, `humans get`, `humans summary` | Ruta de cliente | |
| `timetable` | `timetable get`, `timetable
list`, `timetable logs list` | Ruta de cliente | |
| `scripts` | `scripts variable list|get|set`, `scripts string list|get` | Ruta de cliente | |
| `constants` | `constants list`, `constants get` | Ruta de cliente | |
| `curves` | `curves list`, `curves evaluate` | Ruta de cliente | |
| `hof` | `hof get` | Ruta de cliente | |
| `drivers` | `drivers list` | Ruta de cliente | |
| `tickets` | `tickets get` | Ruta de cliente | |
| `d3d` | Palabra de familia reservada | Ninguno | `d3d` **no tiene ruta jerárquica**: `d3d texture ...` es una ruta desconocida (salida `2`) y `d3d` sola imprime el uso (salida `2`). A las operaciones D3D se accede con `/runtime:d3d.status`, `/runtime:d3d.texture.create`, etc. (consulta [Operaciones sin ruta](#operations-without-a-route)). |
## Rutas jerárquicas
`CliInput.HierarchicalRoutes` asigna una ruta en minúsculas a un id de operación de runtime. Todas las rutas requieren una sesión en `Running` y se ejecutan a través del buzón de runtime (`ExecuteRuntimeAsync`). Las escrituras de runtime solo cambian el estado en memoria de OMSI: nunca tocan archivos, no forman parte de la transacción de configuración y **no** se revierten en la detención (OMSI se termina). La estabilidad sigue a `PublicCapabilityRegistry` y a la [matriz de validación](https://omsilaunch.omsimods.com.br/es/docs/status/runtime-validation-status/index.md); los detalles y los campos de resultado están en [control de runtime](https://omsilaunch.omsimods.com.br/es/docs/reference/runtime-control/index.md).
| Ruta | Operación de runtime | Tipo | Requiere Running | Modifica OMSI | Participación en la restauración | Estabilidad | Notas |
|---|---|---|---|---|---|---|---|
| `time get` | `time.read` | Read | Sí | No | Ninguna | STABLE_BETA | Campos de reloj y calendario. |
| `time set` | `time.set` | Write | Sí | Sí (reloj en memoria) | Ninguna, no se revierte | EXPERIMENTAL | Por ejemplo, `--minute=<0..59>`; escritura, relectura y restauración validadas el 2026-09-20. |
| `weather get` | `weather.read` | Read | Sí | No | Ninguna | STABLE_BETA | |
| `weather set` | `weather.set` | Write | Sí | No (siempre se rechaza) | Ninguna | UNAVAILABLE | Devuelve `OL_E_RUNTIME_SETTING_NOT_PERSISTENT`; OMSI sobrescribe el valor en su siguiente ciclo meteorológico. |
| `weather actual get` | `weather.actual.read` | Read | Sí | No | Ninguna | EXPERIMENTAL | Estado del controlador real/ICAO. |
| `map get` | `map.read` | Read | Sí | No | Ninguna | STABLE_BETA | Nombre del mapa, archivo, descripción, número de tiles, rango de años y sentido de circulación; revalidado en runtime sobre el slot de mapa corregido. |
| `camera get` | `camera.read` | Read | Sí | No | Ninguna | STABLE_BETA | |
| `camera set` | `camera.set` | Write | Sí | Sí (escalares de cámara, p. ej. `--field_of_view=`) | Ninguna, no se revierte | EXPERIMENTAL | Escritura/relectura del FOV validada. |
| `camera lock` | `camera.lock` | Action | Sí | Sí (política limitada a la sesión) | Ninguna | EXPERIMENTAL | Requiere `--family=<0..3>` (conductor=0, pasajero=1, exterior=2, mapa=3), `--preset=` opcional (familia 0 o 1). Necesita un vehículo del jugador (por ejemplo, una situación guardada). Validado en runtime en el cierre de runtime (`CAM01`); la cadena `RuntimeValidation` del registro sigue indicando `STATICALLY_VALIDATED` (consulta [capacidades](https://omsilaunch.omsimods.com.br/es/docs/reference/capabilities/index.md)). |
| `camera unlock` | `camera.unlock` | Action | Sí | Sí | Ninguna | EXPERIMENTAL | Libera la política establecida por `camera lock` (`CAM01`). |
| `vehicles list` | `road-vehicles.list` | Read | Sí | No | Ninguna | STABLE_BETA | Devuelve handles `rv-NNNNNN` limitados a la sesión. |
| `vehicles get` | `road-vehicle.read` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`. Handle obsoleto: `OL_E_RUNTIME_OBJECT_HANDLE_STALE`. |
| `vehicles summary` | `road-vehicles.read` | Read | Sí | No | Ninguna | STABLE_BETA | Recuentos y estado del jugador, sin handles. |
| `vehicles spawn` | `road-vehicles.spawn` | Action | Sí | Sí (añade un RoadVehicle) | Ninguna, no se elimina | EXPERIMENTAL | Requiere `--model=Vehicles\...\*.bus`. Timeout de 30 s en el cliente y de 15 s en el propietario. No asigna el vehículo del jugador. RV-003 `RUNTIME_PASS`. |
| `vehicles place-random` | `road-vehicles.place-random` | Action | Sí | Sí | Ninguna | EXPERIMENTAL | `PlaceRandomBus` perfilado. |
| `player get` | `player-vehicle.read` | Read | Sí | No | Ninguna | STABLE_BETA | Null semántico cuando no hay vehículo del jugador. |
| `humans list` | `humans.list` | Read | Sí | No | Ninguna | EXPERIMENTAL | Devuelve handles `hb-NNNNNN`. |
| `humans get` | `human.read` | Read | Sí | No | Ninguna | EXPERIMENTAL | Requiere `--handle=`. |
| `humans summary` | `humans.read` | Read | Sí | No | Ninguna | EXPERIMENTAL | Solo recuentos. |
| `timetable get` | `timetable.read` | Read | Sí | No | Ninguna | STABLE_BETA | Estado del gestor de horarios. |
| `timetable tracks list` | `timetable.tracks.list` | Read | Sí | No | Ninguna | STABLE_BETA | Parte de la capacidad `timetable.read`; evidencia de lectura por lotes del 2026-09-20. |
| `timetable trips list` | `timetable.trips.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable lines list` | `timetable.lines.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable tours list` | `timetable.tours.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable profiles list` | `timetable.profiles.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable bus-stops list` | `timetable.bus-stops.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable station-links list` | `timetable.station-links.list` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `timetable logs list` | `timetable.logs.read` | Read | Sí | No | Ninguna | STABLE_BETA | Igual que la anterior. |
| `drivers list` | `drivers.read` | Read | Sí | No | Ninguna | EXPERIMENTAL | Registros de conductores. |
| `tickets get` | `tickets.read` | Read | Sí | No | Ninguna | EXPERIMENTAL | Registros de paquetes de billetes. |
| `hof get` | `vehicle.hofs.read` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`. |
| `constants list` | `vehicle.constants.list` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`. |
| `constants get` | `vehicle.constant.get` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`, `--name=`. |
| `curves list` | `vehicle.curves.list` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`. |
| `curves evaluate` | `vehicle.curve.evaluate` | Read | Sí | No | Ninguna | STABLE_BETA | Requiere `--handle=`, `--name=`, `--x=`. |
| `scripts variable list` | `vehicle.variables.list` | Read | Sí | No | Ninguna | EXPERIMENTAL | Requiere `--handle=`. |
| `scripts variable get` | `vehicle.variable.get` | Read | Sí | No | Ninguna | EXPERIMENTAL | Requiere `--handle=`, `--name=`. |
| `scripts variable set` | `vehicle.variable.set` | Write | Sí | Sí (variable de script) | Ninguna, no se revierte | EXPERIMENTAL | Requiere `--handle=`, `--name=`, `--value=` (número finito). |
| `scripts string list` | `vehicle.string-variables.list` | Read | Sí | No | Ninguna | EXPERIMENTAL | Requiere `--handle=`. |
| `scripts string get` | `vehicle.string-variable.get` | Read | Sí | No | Ninguna | EXPERIMENTAL | Requiere `--handle=`, `--name=`. |
### Operaciones sin ruta
Estos ids de operación públicos (`PublicCapabilityRegistry.PublicRuntimeOperationIds`) no tienen ruta jerárquica y se invocan con `/runtime:` más `--key=value` o `/runtime-arg:key=value`: `timetable.rv-files.list`, `timetable.track-entries.list`, `timetable.tour-entries.list`, `d3d.status`, `d3d.texture.create` (`width`, `height`, `format` obligatorios; `levels` opcional), `d3d.texture.describe` (`handle`; `level` opcional), `d3d.texture.update` (`handle`, `width`, `height`, `pixels_base64` obligatorios; `level`, `x`, `y` opcionales), `d3d.texture.release` (`handle`). Las operaciones D3D son EXPERIMENTAL; el ciclo de vida de las texturas y la invalidación por reset del dispositivo están validados en runtime (cierre de runtime `H02`, `D01`; consulta [capacidades](https://omsilaunch.omsimods.com.br/es/docs/reference/capabilities/index.md)). `timetable.track-entries.list` y `timetable.tour-entries.list` son listas acotadas: un resultado que no cabe en el slot de runtime se acorta (`truncated=true`). `internal.road-vehicles.make-basic` es INTERNAL y tanto la CLI como la API lo rechazan con `OL_E_RUNTIME_OPERATION_UNKNOWN`.
## Flags
Todos los flags de `CliInput.KnownFlags`. La «fase» es *de lanzamiento* (da forma al `LaunchSpec`/plan de una sesión nueva), *de runtime* (actúa sobre una sesión en ejecución) o *de control* (cambia el comportamiento de la propia CLI). Los flags que solo se analizan por compatibilidad (`CliInput.AcceptedNoEffectFlags`) se indican en su línea.
### Control y salida
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/?` | `/?` | desactivado | control | STABLE_BETA | Imprime el texto de uso, salida `0`. |
| `/help` | `/help` | desactivado | control | STABLE_BETA | Igual que `/?`. (La palabra suelta `help` devuelve en cambio el catálogo estructurado). |
| `/version` | `/version` | desactivado | control | STABLE_BETA | Envelope `version`, salida `0`. Se evalúa antes que cualquier otro comando excepto `/silent`. |
| `/json` | `/json` o `--json` | desactivado | control | STABLE_BETA | Emite envelopes JSON; también fuerza la salida de consola incluso bajo `OmsiLaunchW.exe`. |
| `/quiet` | `/quiet` | desactivado | control | ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT | Establece `CliInput.Quiet`; nada lo lee. |
| `/silent` | `/silent` (también `--silent`) | desactivado | control | EXPERIMENTAL | Delega toda la línea de comandos en `OmsiLaunchW.exe` y devuelve `0` en cuanto se ha iniciado el proceso host. El resultado de la sesión lo notifican `OmsiLaunchW.exe` (cuadros de mensaje, icono de la bandeja), `.omsilaunch\diagnostics` y el endpoint de control local. La delegación y los cuadros de diálogo de error están validados en runtime (cierre de runtime `T04`); consulta [OmsiLaunchW.exe](https://omsilaunch.omsimods.com.br/es/docs/reference/omsilaunchw/index.md). |
| `/serve` | `/serve` | desactivado | control | ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT | Establece `CliInput.Serve`; nada lo lee. El endpoint de control siempre lo inicia un propietario. |
| `/verbose` | `/verbose` | desactivado | de lanzamiento | PARTIAL | `DiagnosticsSpec.Verbose`. Los valores se transportan en el spec; su efecto se limita a la traza del host en `.omsilaunch\diagnostics`. |
| `/log` | `/log` | activado (`DiagnosticsSpec.Log` es `true` de forma predeterminada) | de lanzamiento | PARTIAL | `DiagnosticsSpec.Log`. En la práctica, siempre activado. |
| `/logall` | `/logall` | desactivado | de lanzamiento | PARTIAL | Establece `Verbose`, `ProcessTrace`, `PluginTrace` y `NativeTrace` a la vez. |
| `/omsi-logall` | `/omsi-logall` | desactivado | de lanzamiento | PARTIAL | `DiagnosticsSpec.OmsiLogAll`. |
| `/trace` | `/trace` | desactivado | de lanzamiento | PARTIAL | Alias de `/trace-process`. |
| `/trace-process` | `/trace-process` | desactivado | de lanzamiento | PARTIAL | `DiagnosticsSpec.ProcessTrace`. |
| `/trace-plugin` | `/trace-plugin` | desactivado | de lanzamiento | PARTIAL | `DiagnosticsSpec.PluginTrace`. |
| `/trace-native` | `/trace-native` | desactivado | de lanzamiento | PARTIAL | `DiagnosticsSpec.NativeTrace`. |
### Planificación, validación y harnesses
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/plan` | `/plan` | desactivado | de lanzamiento | STABLE_BETA | Construye e imprime el `SessionPlan`, sin iniciar OMSI. Salida `0` cuando `IsRunnable`, `1` en caso contrario. Requiere una selección de lanzamiento (`/new`, `/saved`, `/spec` o un argumento de instalación); `/plan` solo, sin nada más, ejecuta `detect`. |
| `/validate` | `/validate` | desactivado | de lanzamiento | STABLE_BETA | Idéntico a `/plan` en esta compilación. |
| `/runtime-batch` | `/runtime-batch` | desactivado | de runtime (propietario) | INTERNAL | Harness de validación: tras `Running`, ejecuta el conjunto de operaciones de lectura y escribe `-runtime-read-batch.json`. |
| `/runtime-write-batch` | `/runtime-write-batch` | desactivado | de runtime (propietario) | INTERNAL | Harness de validación: lecturas más `time.set`, `camera.set` y `vehicle.variable.set` con restauración; escribe `-runtime-write-batch.json`. |
| `/d3d-batch` | `/d3d-batch` | desactivado | de runtime (propietario) | INTERNAL | Harness de validación del ciclo de vida de las texturas D3D; escribe `-d3d-wave-d-batch.json`. |
| `/runtime` | `/runtime:` | ninguno | de runtime | STABLE_BETA (despacho) | Selecciona una operación de runtime pública por su id. Modo cliente (sin argumento de instalación): se reenvía al propietario. Modo propietario: se ejecuta una vez tras `Running`. Ids desconocidos: `OL_E_RUNTIME_OPERATION_UNKNOWN`, salida `2`. |
| `/runtime-arg` | `/runtime-arg:=` (repetible) | ninguno | de runtime | STABLE_BETA (despacho) | Argumento de runtime; equivalente a `--key=value`. Si falta `=`: `/runtime-arg requires key=value`, salida `2`. |
### Selección del mundo
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/new` | `/new` | `WorldMode.NewMap` es el modo predeterminado, pero solo se solicita un lanzamiento cuando está presente uno de `/new`, `/saved`, `/last`, `/spec` | de lanzamiento | STABLE_BETA | NEW_MAP. Requiere `/map` y `/entrypoint-index` (un plan sin índice del punto de entrada presentado notifica `OL_E_ENTRYPOINT_REQUIRED`; sin `/map` no se resuelve ningún mapa). `/new` nunca selecciona un mapa de forma implícita. |
| `/saved` | `/saved:` | ninguno | de lanzamiento | STABLE_BETA | SAVED_SITUATION. El mapa y la posición proceden del `.osn`; `/map`, `/entrypoint`, `/entrypoint-index` se rechazan junto con `/saved` (salida `2`). Situación inexistente: `OL_E_SITUATION_NOT_FOUND`; su mapa inexistente: `OL_E_SITUATION_MAP_NOT_FOUND`. |
| `/last` | `/last` | ninguno | de lanzamiento | UNAVAILABLE | LAST_MAP_STATE. Siempre produce `OL_E_CAPABILITY_UNAVAILABLE` (no ejecutable, salida `1`) en este perfil; no se realiza ninguna alternativa con `.osn` basada en marcas de tiempo. |
| `/map` | `/map:` (por ejemplo, `maps\Grundorf\global.cfg`) | ninguno | de lanzamiento | STABLE_BETA | Identidad del mapa para `/new`, o el ámbito para `/list:Entrypoints`. Desconocido: `OL_E_MAP_NOT_FOUND`. |
| `/entrypoint` | `/entrypoint:` | ninguno | de lanzamiento | UNAVAILABLE | Punto de entrada por etiqueta. Bloqueado: el plan registra `world.entrypoint-identity` como `RUNTIME_PARTIAL` y deja de ser ejecutable (`OL_E_CAPABILITY_UNAVAILABLE`). Mutuamente excluyente con `/entrypoint-index` (la identidad prevalece y borra el índice). |
| `/entrypoint-index` | `/entrypoint-index:`, `0..2147483647` | ninguno | de lanzamiento | STABLE_BETA | Índice del punto de entrada en la lista presentada (empezando en 1, tal como lo presenta OMSI). Obligatorio para un plan NEW_MAP ejecutable. |
### Fecha, hora y meteorología
Los cuatro se aceptan y se transportan al `LaunchSpec`, pero la ruta de inicio nativa no los aplica: el planificador los registra como `STATICALLY_PARTIAL` **y añade `OL_E_CAPABILITY_UNAVAILABLE`, por lo que el plan NO ES EJECUTABLE (salida `1`)**. Un archivo `/spec` o un perfil de sesión que los establezca tiene el mismo efecto.
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/date` | `/date:` o `/date:system` | sin establecer | de lanzamiento | UNAVAILABLE | `DateSpec` explícito/sistema. Valor no analizable: `OL_E_INVALID_ARGUMENT`, salida `2`. |
| `/time` | `/time:` o `/time:system` | sin establecer | de lanzamiento | UNAVAILABLE | `TimeSpec` explícito/sistema. |
| `/year` | `/year:` o `/year:system` | sin establecer | de lanzamiento | UNAVAILABLE | `YearSpec`. |
| `/weather` | `/weather:` | sin establecer | de lanzamiento | UNAVAILABLE | `WeatherMode.Preset`. |
| `/weather-icao` | `/weather-icao:` | sin establecer | de lanzamiento | UNAVAILABLE | `WeatherMode.Icao`. |
| `/weather-real` | `/weather-real` | sin establecer | de lanzamiento | UNAVAILABLE | `WeatherMode.RealCurrent`. Prevalece el último de `/weather`, `/weather-icao`, `/weather-real`. |
### Vehículo del jugador
Se aceptan y se resuelven frente a la instalación, pero el runtime no los aplica: cada campo establecido es `STATICALLY_PARTIAL` y añade `OL_E_CAPABILITY_UNAVAILABLE` (plan NO EJECUTABLE, salida `1`).
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/vehicle` | `/vehicle:` (`Vehicles\...\*.bus`) | sin establecer | de lanzamiento | UNAVAILABLE | Se resuelve primero (`OL_E_VEHICLE_NOT_FOUND` si es desconocido). |
| `/repaint` | `/repaint:` | sin establecer | de lanzamiento | UNAVAILABLE | Solo se resuelve junto con `/vehicle` (`OL_E_REPAINT_NOT_FOUND`). |
| `/hof` | `/hof:` | sin establecer | de lanzamiento | UNAVAILABLE | `OL_E_HOF_NOT_FOUND` si es desconocido. |
| `/fleet` | `/fleet:` | sin establecer | de lanzamiento | UNAVAILABLE | Número de flota. |
| `/registration` | `/registration:` | sin establecer | de lanzamiento | UNAVAILABLE | Matrícula. |
| `/no-vehicle` | `/no-vehicle` | desactivado | de lanzamiento | STABLE_BETA | Quita cualquier vehículo del jugador de la semilla (`/spec` o perfil). Inocuo. |
### Overlays de configuración
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/set` | `/set:=` (repetible; las claves no distinguen mayúsculas de minúsculas) | ninguno | de lanzamiento | STABLE_BETA | Overlay semántico de `options.cfg` a partir de `ConfigurationCatalog` (por ejemplo, `graphics.maxFPS=60`, `traffic.randomVehicles=150`). Clave desconocida: `OL_E_UNKNOWN_SETTING` (salida `2`); clave de solo lectura (`advanced.multithreadingCalculate`, `advanced.multithreadingTextureLoad`, `graphics.texture`, `graphics.textureFilter`): `OL_E_SETTING_NOT_WRITABLE` (salida `2`); valor fuera de rango o mal formado: `OL_E_INVALID_SETTING_VALUE` al construir el overlay. El overlay es una mutación de la sesión: se guarda en un snapshot, se aplica antes de iniciar OMSI y se restaura byte a byte en la detención (RV-005 `RUNTIME_PASS`). Conflicto con una clave propiedad del preset de un perfil seleccionado: `OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT`. |
### Presentación del splash
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/splash` | `/splash:Managed`, `/splash:Native`, `/splash:Unset` (sin distinguir mayúsculas de minúsculas) | `Managed` | de lanzamiento | STABLE_BETA | `Managed`: los BMP empaquetados de 640x480 y 24 bits se copian una vez a `\.omsilaunch\assets\splash`, y `GUI\NewSplashscreen_ENG.bmp` más `GUI\NewSplashscreen_.bmp` se aplican como overlay de forma transaccional y se restauran exactamente (RV-006 `RUNTIME_PASS`). `Native`/`Unset` (alias): los archivos de OMSI no se tocan. Si falta el valor: `/splash requires Unset, Native, or Managed`, salida `2`. |
| `/splash-language` | `/splash-language:PTB|ENG|DEU|FRA` (también `pt-BR`, `de`, `fr`, `en`; cualquier otro valor recurre a `ENG`) | `[language]` de `options.cfg`; si no, `ENG` | de lanzamiento | STABLE_BETA | Selecciona el archivo de destino localizado. |
| `/splash-assets` | `/splash-assets:` (las rutas relativas se resuelven bajo la raíz de la instalación) | `\.omsilaunch\assets\splash`; si no, el conjunto empaquetado | de lanzamiento | STABLE_BETA | Directorio de recursos personalizado; debe contener `ENG.bmp` y, para un idioma distinto del inglés, `.bmp`. Errores: `OL_E_SPLASH_ASSET_DIRECTORY_MISSING`, `OL_E_SPLASH_ASSET_MISSING`, `OL_E_SPLASH_FORMAT_UNSUPPORTED` (se presentan como `OL_E_SESSION_PRESENTATION_INVALID` en el plan; no ejecutable). |
### Texturas de Internet
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/internet-textures` | `/internet-textures:Native|Disabled|Override` | `Native` | de lanzamiento | EXPERIMENTAL | `Native`: sin cambios. `Disabled`: se suprime el descargador perfilado dentro del proceso. `Override`: el perfil `.itx` indicado se aplica como overlay en `Texture\standard.itx`; todos los destinos HTTP(S) enumerados en él más `Texture\standard.ipr` pasan a ser eliminaciones de sesión (se quitan durante la sesión y se restauran en la detención). Si falta el valor: salida `2`. |
| `/internet-textures-profile` | `/internet-textures-profile:` | ninguno | de lanzamiento | EXPERIMENTAL | Obligatorio con `Override` (`OL_E_ITX_PROFILE_REQUIRED`, salida `2`). `OL_E_ITX_PROFILE_MISSING`, `OL_E_ITX_PROFILE_INVALID` (deben ser pares de líneas URL/destino con URL `http`/`https`), `OL_E_ITX_TARGET_OUTSIDE_TEXTURE_PATH` (los destinos deben resolverse bajo `Texture\`, sin rutas absolutas, `..` ni puntos de reanálisis). |
### Perfiles de sesión
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/predefined-profile` | `/predefined-profile:` | ninguno | de lanzamiento | STABLE_BETA (compilación; `OmsiLaunch.ProfileTests` offline) | Carga `\.omsilaunch\session-profiles\\profile.yaml` (consulta [perfiles de sesión](https://omsilaunch.omsimods.com.br/es/docs/reference/session-profiles/index.md)). Requiere `/predefined-profile-index` (`OL_E_SESSION_PROFILE_PRESET_NOT_FOUND`, salida `2`). El bloque `new:` solo se aplica con `/new`; `compatibility.maps` se aplica para `/new` y `/saved` (`OL_E_SESSION_PROFILE_MAP_MISMATCH`). Los flags explícitos que colisionan con un campo propiedad del perfil se rechazan con `OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT` (`CliInput.RejectProfileConflicts`): mapa/punto de entrada/fecha/hora/año/meteorología cuando el bloque `new:` es su propietario, claves de `/set` propiedad del preset, flags de splash cuando el preset tiene `presentation`, flags de texturas de Internet cuando tiene `internet-textures`, timeouts cuando tiene `behavior`. |
| `/predefined-profile-index` | `/predefined-profile-index:<1..5>` | ninguno | de lanzamiento | STABLE_BETA | Selecciona el preset por `index`. Fuera de rango: salida `2`. |
### Archivo LaunchSpec
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/spec` | `/spec:` | ninguno | de lanzamiento | STABLE_BETA (cargador probado offline; semántica de sesión idéntica a la de los flags) | Carga un archivo JSON `LaunchSpec` como semilla (consulta [LaunchSpec](https://omsilaunch.omsimods.com.br/es/docs/reference/launchspec/index.md)) y marca que se ha solicitado un lanzamiento. Reglas (`LaunchSpecJson`): el archivo debe existir (`OL_E_SPEC_NOT_FOUND`, salida `6`); como máximo 1 MiB (`OL_E_SPEC_TOO_LARGE`, salida `2`); la raíz debe ser un objeto (`OL_E_SPEC_INVALID`); los nombres de propiedad no distinguen mayúsculas de minúsculas; se admiten comentarios `//` y comas finales; profundidad máxima de 32; toda propiedad desconocida se rechaza con su ruta JSON (`OL_E_SPEC_UNKNOWN_PROPERTY: $.Presentation.Foo`, salida `2`). |
**Precedencia** (`CliInput.BuildSpecAsync`): valores predeterminados → archivo `/spec` → `/predefined-profile` (sustituye `Installation` y `World` y después aplica el perfil) → flags explícitos. Un argumento de instalación explícito prevalece sobre `RootPath` en el spec. `/no-vehicle` quita el vehículo del jugador del spec; `/vehicle` y los flags relacionados se combinan con él campo a campo. Las claves de `/set` se combinan en `Environment.General`. `/splash`, `/splash-language`, `/splash-assets`, `/internet-textures`, `/internet-textures-profile` solo sobrescriben cuando se indican. `/startup-timeout` y `/shutdown-timeout` solo sobrescriben cuando se indican; `Presentation.SuppressTrayIcon` procede únicamente del spec (no hay flag). Los flags de diagnóstico se combinan mediante OR con los `Diagnostics` del spec.
### Descubrimiento de contenido
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/list` | `/list:`; las categorías son los valores de `ContentQueryKind` `Maps`, `Situations`, `Vehicles`, `Repaints`, `Hofs`, `FleetNumbers`, `Registrations`, `Addons`, `Entrypoints` (sin distinguir mayúsculas de minúsculas) | ninguno | local, sin sesión | STABLE_BETA | `DiscoverAsync` sobre la instalación; envelope `content.list` con entradas `Identity`, `Kind`, `DisplayName`; salida `0`. Categoría desconocida: `Unknown discovery category`, salida `2`. Los puntos de reanálisis (uniones/enlaces simbólicos) se omiten y los archivos de OMSI se leen como Windows-1252. |
| `/vehicle-scope` | `/vehicle-scope:` | ninguno | local | STABLE_BETA | Ámbito que se reenvía para todas las categorías excepto `Entrypoints`, que usa `/map` como ámbito. |
### Timeouts y observación
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/startup-timeout` | `/startup-timeout:<1..600>` segundos | valor del spec/perfil; si no, `180` | de lanzamiento | STABLE_BETA | `Behavior.StartupTimeoutSeconds`. El propietario espera `Running` durante este valor más 5 s; `OL_E_STARTUP_TIMEOUT` termina la sesión con salida `1`. |
| `/shutdown-timeout` | `/shutdown-timeout:<1..600>` segundos | valor del spec/perfil; si no, `30` | de lanzamiento | ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT | Se transporta a `Behavior.ShutdownTimeoutSeconds`; el supervisor no lo consume en esta compilación (OMSI se termina, no se le pide que se cierre). |
| `/observe-seconds` | `/observe-seconds:<0..2147483647>` | ninguno (se ejecuta hasta que OMSI termine o se solicite una detención) | de runtime (propietario) | STABLE_BETA | Límite superior de la fase de ejecución: tras `n` segundos en `Running` se solicita la detención canónica. Una detención desde la bandeja o la canalización, o la finalización de OMSI, la terminan antes. `0` detiene inmediatamente después de `Running`. |
### Recuperación
| Flag | Sintaxis y valores | Predeterminado | Fase | Estabilidad | Comportamiento |
|---|---|---|---|---|---|
| `/recovery-status` | `/recovery-status` | desactivado | local | STABLE_BETA | Informa de si `\.omsilaunch\journal.json` está pendiente (`pending`); nunca restaura; salida `0`. Toma el lease de la instalación: `OL_E_INSTALLATION_BUSY` (salida `7`) mientras un propietario lo mantiene. |
| `/recover` | `/recover` | desactivado | local | STABLE_BETA | Restaura un diario pendiente (las copias de seguridad se verifican primero frente al SHA-256 del snapshot; `OL_E_RECOVERY_BACKUP_CORRUPT`, `OL_E_RECOVERY_ABSENT_OWNERSHIP_MISMATCH`, `OL_W_RESTORE_FOREIGN_FILE_RETAINED` se notifican en `diagnostics`). Salida `0` cuando no había nada pendiente o la restauración se completó; `8` cuando había un diario pendiente y sigue estándolo. Se rechaza con `OL_E_INSTALLATION_BUSY` mientras el proceso de OMSI registrado en el diario (PID, hora de creación, ruta del exe) o, en el caso de un diario posterior a `HandoffCreated` sin PID, cualquier `Omsi.exe` de esa raíz sigue vivo. Cada inicio de sesión realiza automáticamente la misma recuperación antes de leer la instalación. |
## Formatos de salida
- **Envelope de éxito** (`CliInput.WriteEnvelope`, con `--json`): `{"ok": true, "command": "", "protocol_version": "0.1", "result":