> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/spanish/caracteristicas-clave/headless/command-line-interface.md).

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