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

# Interface en ligne de commande

Utilisez l'interface en ligne de commande `studio` pour vérifier une licence et exécuter des scénarios sauvegardés `.pmod` sans ouvrir l'application de bureau.

La façon la plus sûre d'appeler le CLI est via l'exécutable Python dans lequel AugeLab Studio est installé :

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

Si votre environnement expose aussi la commande console `studio`, cela fonctionne également :

```bash
studio --help
```

## Avant de commencer

Vous avez besoin de :

* AugeLab Studio installé.
* Un scénario sauvegardé au format `.pmod`.
* Votre code de vérification AugeLab, sauf si la machine est déjà activée.
* L'exécutable Python de l'environnement où `studio` est installé.

> **Info :**\
> Utilisez des chemins absolus lorsque vous lancez depuis des services, des tâches planifiées, Docker ou des sessions SSH. Cela évite d'exécuter le mauvais environnement Python.

## Étape 1 : Localiser Python

### Windows

Si vous avez installé avec l'installateur AugeLab, l'environnement Python se trouve généralement ici :

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

Si vous avez installé manuellement dans un virtualenv de projet, pointez vers cet environnement :

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

Si `studio` est dans le `PATH`, vous pouvez le vérifier directement :

```powershell
studio --help
```

### Linux

Si vous avez installé avec l'installateur Linux, l'environnement Python se trouve généralement ici :

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

Si vous avez installé manuellement dans un virtualenv de projet, pointez vers cet environnement :

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

Si le virtualenv est déjà activé :

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

### Docker

Dans les exemples Docker, exécutez la forme module :

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

## Étape 2 : Vérifier la licence

Exécutez ceci une fois par machine ou image de conteneur :

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

Linux :

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

Sortie attendue :

```
Verification succeeded.
```

Ne mettez pas en dur de vrais codes de vérification dans des scripts partagés, Dockerfiles ou dépôts Git. Utilisez des variables d'environnement ou un stockage sécurisé pour l'automatisation des déploiements.

## Étape 3 : Exécuter un scénario

Windows :

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

Linux :

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

La commande maintient le scénario en cours d'exécution jusqu'à ce que le scénario s'arrête, échoue ou que vous l'interrompiez avec `Ctrl+C`.

> **Avertissement :**\
> Copiez le dossier complet du projet lorsqu'un scénario utilise des fichiers externes tels que des images, des modèles, des fichiers d'étalonnage ou des assets de blocs personnalisés. Conservez ces fichiers aux mêmes emplacements relatifs utilisés lors de la sauvegarde du scénario.

## Modes d'exécution courants

Exécuter un nombre fixe d'étapes complétées :

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

Démarrer avec le tableau de bord web :

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

Utiliser une supervision de redémarrage pour des exécutions sans surveillance :

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

Émettre des événements JSON délimités par ligne pour l'automatisation :

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

Changer la verbosité des logs runtime :

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

Ignorer les erreurs de chargement du scénario uniquement lorsque vous souhaitez volontairement continuer avec des ressources optionnelles manquantes :

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

> **Avertissement :**\
> `--step` ne peut pas être utilisé simultanément avec `--web`.

## Référence des commandes

| Commande                                                                 | But                                                            |
| ------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `python -m studio --help`                                                | Affiche l'aide CLI de niveau supérieur.                        |
| `python -m studio verify CODE`                                           | Enregistre un code de vérification pour la machine courante.   |
| `python -m studio run scenario.pmod`                                     | Exécute un scénario sauvegardé en continu.                     |
| `python -m studio run scenario.pmod --step 10`                           | Exécute un scénario sauvegardé pour 10 étapes complétées.      |
| `python -m studio run scenario.pmod --web --address 0.0.0.0 --port 8080` | Exécute avec le tableau de bord web.                           |
| `python -m studio run scenario.pmod --on-fail restart --max-restarts 5`  | Redémarre les exécutions échouées jusqu'à 5 fois.              |
| `python -m studio run scenario.pmod --json`                              | Émet des enregistrements JSON de cycle de vie et de résultats. |

## Codes de sortie

| Code  | Signification                                                       |
| ----- | ------------------------------------------------------------------- |
| `0`   | Succès.                                                             |
| `2`   | Erreur d'utilisation de la commande.                                |
| `3`   | Échec de la vérification de licence ou du chargement de la licence. |
| `4`   | Échec du chargement du scénario.                                    |
| `5`   | Échec d'exécution du scénario.                                      |
| `6`   | Plantage inattendu.                                                 |
| `7`   | Échec du démarrage du tableau de bord web.                          |
| `8`   | Tentatives de redémarrage épuisées.                                 |
| `130` | Interrompu par l'utilisateur.                                       |

## Dépannage

| Symptom                      | Solution                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `No module named studio`     | Utilisez l'exécutable Python de l'environnement virtuel Studio.                                               |
| `studio` command not found   | Utilisez `python -m studio` avec l'exécutable Python correct.                                                 |
| Scenario file not found      | Utilisez un chemin `.pmod` absolu ou exécutez depuis le dossier du projet.                                    |
| License failure              | Exécutez `studio verify` à nouveau et vérifiez le code de vérification.                                       |
| Web dashboard does not start | Changez le `--port`, ou vérifiez le pare-feu et le mappage de ports du conteneur.                             |
| Scenario load failure        | Copiez les ressources manquantes avec le `.pmod`, ou corrigez les chemins des blocs/ressources personnalisés. |