> 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/key-features/headless/command-line-interface.md).

# Command Line Interface

Use the `studio` command line interface to verify a license and run saved `.pmod` scenarios without opening the desktop application.

The safest way to call the CLI is through the Python executable that has AugeLab Studio installed:

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

If your environment also exposes the `studio` console command, this works too:

```bash
studio --help
```

## Before You Start

You need:

* AugeLab Studio installed.
* A saved `.pmod` scenario.
* Your AugeLab verification code, unless the machine is already activated.
* The Python executable from the environment where `studio` is installed.

{% hint style="info" %}
Use absolute paths when running from services, scheduled tasks, Docker, or SSH sessions. This avoids running the wrong Python environment.
{% endhint %}

## Step 1: Locate Python

### Windows

If you installed with the AugeLab installer, the Python environment is usually:

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

If you installed manually into a project virtual environment, point to that environment instead:

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

If `studio` is on `PATH`, you can check it directly:

```powershell
studio --help
```

### Linux

If you installed with the Linux installer, the Python environment is usually:

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

If you installed manually into a project virtual environment, point to that environment instead:

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

If the virtual environment is already active:

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

### Docker

Inside the Docker examples, run the module form:

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

## Step 2: Verify License

Run this once per machine or container image environment:

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

Linux:

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

Expected output:

```
Verification succeeded.
```

Do not hardcode real verification codes into shared scripts, Dockerfiles, or Git repositories. Use environment variables or secret storage when automating deployments.

## Step 3: Run Scenario

Windows:

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

Linux:

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

The command keeps the scenario running until the scenario stops, fails, or you interrupt it with `Ctrl+C`.

{% hint style="warning" %}
Copy the complete project folder when a scenario uses external files such as images, models, calibration files, or custom block assets. Keep those files in the same relative locations used when the scenario was saved.
{% endhint %}

## Common Run Modes

Run a fixed number of completed steps:

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

Start with the web dashboard:

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

Use restart supervision for unattended runs:

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

Emit line-delimited JSON events for automation:

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

Change runtime log verbosity:

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

Ignore scenario load errors only when you intentionally want to continue with missing optional resources:

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

{% hint style="warning" %}
`--step` cannot be used together with `--web`.
{% endhint %}

## Command Reference

| Command                                                                  | Purpose                                               |
| ------------------------------------------------------------------------ | ----------------------------------------------------- |
| `python -m studio --help`                                                | Show top-level CLI help.                              |
| `python -m studio verify CODE`                                           | Register a verification code for the current machine. |
| `python -m studio run scenario.pmod`                                     | Run a saved scenario continuously.                    |
| `python -m studio run scenario.pmod --step 10`                           | Run a saved scenario for 10 completed steps.          |
| `python -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080` | Run with the web dashboard.                           |
| `python -m studio run scenario.pmod --on-fail restart --max-restarts 5`  | Restart failed runs up to 5 times.                    |
| `python -m studio run scenario.pmod --json`                              | Emit JSON lifecycle and result records.               |

## Exit Codes

| Code  | Meaning                                          |
| ----- | ------------------------------------------------ |
| `0`   | Success.                                         |
| `2`   | Command usage error.                             |
| `3`   | License verification or license loading failure. |
| `4`   | Scenario load failure.                           |
| `5`   | Scenario runtime failure.                        |
| `6`   | Unexpected crash.                                |
| `7`   | Web dashboard startup failure.                   |
| `8`   | Restart retries exhausted.                       |
| `130` | Interrupted by user.                             |

## Troubleshooting

| Symptom                      | Fix                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `No module named studio`     | Use the Python executable from the Studio virtual environment.               |
| `studio` command not found   | Use `python -m studio` with the correct Python executable.                   |
| Scenario file not found      | Use an absolute `.pmod` path or run from the project folder.                 |
| License failure              | Run `studio verify` again and check the verification code.                   |
| Web dashboard does not start | Change `--port`, or check firewall and container port mapping.               |
| Scenario load failure        | Copy missing resources with the `.pmod`, or fix custom block/resource paths. |