# Interfaz de línea de comandos

Utiliza la interfaz de línea de comandos `studio` para verificar una licencia y ejecutar escenarios `.pmod` guardados sin abrir la aplicación de escritorio.

La forma más segura de invocar la CLI es mediante el ejecutable de Python donde está instalado AugeLab Studio:

```bash
python -m studio --help
```

Si tu entorno también expone el comando de consola `studio`, esto también funciona:

```bash
studio --help
```

## Antes de empezar

Necesitas:

* AugeLab Studio instalado.
* Un escenario `.pmod` guardado.
* Tu código de verificación de AugeLab, a menos que la máquina ya esté activada.
* El ejecutable de Python del entorno donde está instalado `studio`.

{% hint style="info" %}
Usa rutas absolutas cuando ejecutes desde servicios, tareas programadas, Docker o sesiones SSH. Esto evita usar el entorno de Python incorrecto.
{% endhint %}

## Paso 1: Localizar Python

### Windows

Si instalaste con el instalador de AugeLab, el entorno de Python suele estar en:

```powershell
$py = "$env:USERPROFILE\studio_venv\Scripts\python.exe"
& $py -m studio --help
```

Si instalaste manualmente en un entorno virtual de proyecto, apunta a ese entorno en su lugar:

```powershell
$py = "C:\path\to\studio_venv\Scripts\python.exe"
& $py -m studio --help
```

Si `studio` está en `PATH`, puedes comprobarlo directamente:

```powershell
studio --help
```

### Linux

Si instalaste con el instalador para Linux, el entorno de Python suele estar en:

```bash
PY="$HOME/studio_venv/bin/python"
"$PY" -m studio --help
```

Si instalaste manualmente en un entorno virtual de proyecto, apunta a ese entorno en su lugar:

```bash
PY="/path/to/studio_venv/bin/python"
"$PY" -m studio --help
```

Si el entorno virtual ya está activado:

```bash
python -m studio --help
```

### Docker

En los ejemplos de Docker, ejecuta la forma de módulo:

```bash
python -m studio --help
```

## Paso 2: Verificar la licencia

Ejecuta esto una vez por máquina o por imagen de contenedor:

```powershell
& $py -m studio verify "YOUR_VERIFICATION_CODE"
```

Linux:

```bash
"$PY" -m studio verify "YOUR_VERIFICATION_CODE"
```

Salida esperada:

```
Verification succeeded.
```

No incluyas códigos de verificación reales en scripts compartidos, Dockerfiles o repositorios Git. Usa variables de entorno o almacenamiento seguro de secretos al automatizar despliegues.

## Paso 3: Ejecutar el escenario

Windows:

```powershell
& $py -m studio run "C:\path\to\scenario.pmod"
```

Linux:

```bash
"$PY" -m studio run /path/to/scenario.pmod
```

El comando mantiene el escenario en ejecución hasta que el escenario termine, falle o lo interrumpas con `Ctrl+C`.

{% hint style="warning" %}
Copia la carpeta completa del proyecto cuando un escenario use archivos externos como imágenes, modelos, archivos de calibración o assets de bloques personalizados. Mantén esos archivos en las mismas ubicaciones relativas que tenía el escenario cuando se guardó.
{% endhint %}

## Modos comunes de ejecución

Ejecutar un número fijo de pasos completados:

```bash
"$PY" -m studio run scenario.pmod --step 10
```

Iniciar con el panel web:

```bash
"$PY" -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080
```

Usar supervisión de reinicio para ejecuciones desatendidas:

```bash
"$PY" -m studio run scenario.pmod --on-fail restart --max-restarts 5 --restart-delay 3
```

Emitir eventos JSON delimitados por línea para automatización:

```bash
"$PY" -m studio run scenario.pmod --json
```

Cambiar la verbosidad del log en tiempo de ejecución:

```bash
"$PY" -m studio run scenario.pmod --verbosity 20
```

Ignorar errores de carga de escenario solo cuando intencionalmente quieras continuar con recursos opcionales faltantes:

```bash
"$PY" -m studio run scenario.pmod --ignore-errors
```

{% hint style="warning" %}
`--step` no puede usarse junto con `--web`.
{% endhint %}

## Referencia de comandos

| Command                                                                  | Propósito                                                    |
| ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `python -m studio --help`                                                | Mostrar la ayuda de la CLI a nivel superior.                 |
| `python -m studio verify CODE`                                           | Registrar un código de verificación para la máquina actual.  |
| `python -m studio run scenario.pmod`                                     | Ejecutar un escenario guardado de forma continua.            |
| `python -m studio run scenario.pmod --step 10`                           | Ejecutar un escenario guardado durante 10 pasos completados. |
| `python -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080` | Ejecutar con el panel web (web dashboard).                   |
| `python -m studio run scenario.pmod --on-fail restart --max-restarts 5`  | Reiniciar ejecuciones fallidas hasta 5 veces.                |
| `python -m studio run scenario.pmod --json`                              | Emitir registros de ciclo de vida y resultados en JSON.      |

## Códigos de salida

| Code  | Significado                                                        |
| ----- | ------------------------------------------------------------------ |
| `0`   | Éxito.                                                             |
| `2`   | Error de uso del comando.                                          |
| `3`   | Fallo en la verificación de licencia o en la carga de la licencia. |
| `4`   | Fallo al cargar el escenario.                                      |
| `5`   | Fallo en tiempo de ejecución del escenario.                        |
| `6`   | Bloqueo inesperado.                                                |
| `7`   | Fallo al iniciar el panel web.                                     |
| `8`   | Reintentos de reinicio agotados.                                   |
| `130` | Interrumpido por el usuario.                                       |

## Solución de problemas

| Síntoma                      | Solución                                                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `No module named studio`     | Usa el ejecutable de Python del entorno virtual de Studio.                                                 |
| `studio` command not found   | Usa `python -m studio` con el ejecutable de Python correcto.                                               |
| Scenario file not found      | Usa una ruta absoluta al `.pmod` o ejecuta desde la carpeta del proyecto.                                  |
| License failure              | Ejecuta `studio verify` de nuevo y revisa el código de verificación.                                       |
| Web dashboard does not start | Cambia `--port`, o revisa el firewall y el mapeo de puertos del contenedor.                                |
| Scenario load failure        | Copia los recursos faltantes junto con el `.pmod`, o corrige las rutas de bloques/recursos personalizados. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.augelab.com/spanish/caracteristicas-clave/headless/command-line-interface.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.