# Référence CLI Le CLI Sovrium exécute votre application et gère son cycle de vie : démarrer et arrêter le serveur, recharger la configuration à chaud sans interruption, générer un site statique, échafauder un projet, afficher le JSON Schema et valider un fichier de configuration. La configuration est chargée depuis un fichier ou une variable d'environnement. ## Utilisation Le CLI accepte une commande suivie d'un chemin de fichier de configuration optionnel et d'options. ```bash sovrium [command] [config] [flags] sovrium start app.yaml # Démarrer le serveur (commande par défaut) sovrium stop # Arrêter le serveur en cours d'exécution sovrium restart app.yaml # Redémarrer le serveur en cours d'exécution sovrium reload # Recharger la configuration à chaud sans interruption sovrium build app.yaml # Générer un site statique sovrium init ./my-app # Échafauder un nouveau projet sovrium schema # Afficher le JSON Schema sovrium validate app.yaml # Valider la configuration sovrium --help # Afficher l'aide ``` ## Commandes Les commandes les plus courantes sont présentées ci-dessous. Si aucune commande n'est spécifiée, `start` est utilisée par défaut. Le CLI expose également des commandes pour étendre un projet (`agents`), l'exploiter (`admin`, `secret`) et maintenir le binaire à jour (`update`) — toutes documentées ci-dessous. Exécutez `sovrium --help` pour la liste complète. ### `sovrium start` Démarre un serveur de développement qui sert votre application. C'est la commande par défaut — exécuter `sovrium app.yaml` équivaut à `sovrium start app.yaml`. ```bash sovrium start app.yaml ``` ### `sovrium stop` Arrête le serveur Sovrium en cours d'exécution. ```bash sovrium stop ``` ### `sovrium restart` Redémarre le serveur en cours d'exécution, éventuellement avec un nouveau fichier de configuration. ```bash sovrium restart app.yaml ``` ### `sovrium reload` Recharge à chaud la configuration d'un serveur en cours d'exécution sans interruption. Le rechargement sonde d'abord l'état de dérive de l'application en direct ; si le schéma en direct a dérivé par rapport au fichier (modifié à l'exécution via l'API d'administration ou MCP), le rechargement est refusé sauf si `--force` est passé. Voir [Métadonnées de l'application](/fr/docs/app-metadata#schema-drift-detection). ```bash sovrium reload sovrium reload --force # écrase un schéma en direct dérivé avec le fichier ``` ### `sovrium init` Échafaude un nouveau projet dans le répertoire indiqué (ou le répertoire courant). Utilisez `--template ` pour partir d'un modèle et `--name ` pour définir le nom de l'application. ```bash sovrium init ./my-app --template blog ``` ### `sovrium build` Génère un site statique à partir de votre configuration. Produit du HTML, du CSS et des ressources prêts à être déployés vers n'importe quel hébergeur de sites statiques. ```bash sovrium build app.yaml ``` ### `sovrium schema` Affiche le JSON Schema (Draft-07) de la configuration d'application Sovrium sur la sortie standard. Utilisez `--output ` pour écrire dans un fichier à la place. ```bash sovrium schema sovrium schema --output app.schema.json ``` ### `sovrium validate ` Valide un fichier de configuration par rapport à l'AppSchema Sovrium. Retourne le code de sortie 0 si la configuration est valide, 1 si elle est invalide avec le détail des erreurs. ```bash sovrium validate app.yaml ``` ### `sovrium agents list` Liste les modèles d'agents intégrés au binaire. Ce sont des définitions de sous-agents Claude Code que vous pouvez installer dans le répertoire `.claude/agents/` d'un projet. ```bash sovrium agents list ``` ### `sovrium agents install ` Installe un modèle d'agent intégré dans `.claude/agents/.md`. `add` est un alias d'`install`. Par défaut, l'agent est écrit sous le répertoire courant ; passez `--target ` pour choisir une autre racine de projet. La commande refuse d'écraser un fichier d'agent existant sauf si `--force` est fourni. ```bash sovrium agents install crm-editor sovrium agents add crm-editor --target ./my-project --force ``` ### `sovrium admin create ` Provisionne un utilisateur administrateur dans la base de données sans avoir à fournir un schéma complet. Le mot de passe est lu depuis `--password ` lorsqu'il est fourni (utile en CI/scripts) ; sinon, il vous est demandé de manière interactive avec l'écho désactivé. Exécuter la commande sans `--password` dans un shell non interactif (sans TTY) est une erreur. Le schéma de la base de données est résolu dans cet ordre : un `--config ` explicite, puis `APP_SCHEMA`, puis un schéma par défaut minimal intégré — afin que la commande `sovrium admin create ` fonctionne sans fichier de configuration. Si l'administrateur existe déjà, aucune modification n'est effectuée. ```bash # Demander le mot de passe de manière interactive sovrium admin create me@example.com # Fournir le mot de passe (CI / scripts) sovrium admin create me@example.com --password 's3cret-pass' # Résoudre le schéma depuis une configuration spécifique sovrium admin create me@example.com --config app.yaml ``` ### `sovrium secret generate` Affiche des secrets fraîchement générés, cryptographiquement aléatoires, sous forme de lignes prêtes pour `.env`. Chaque secret est une valeur de 256 bits (64 caractères hexadécimaux). Sans portée, `AUTH_SECRET` et `SOVRIUM_ENCRYPTION_KEY` sont tous deux affichés. Passez une portée pour n'afficher qu'un sous-ensemble. | Portée | Sortie | | ------------ | ---------------------------------------- | | _(aucune)_ | `AUTH_SECRET` + `SOVRIUM_ENCRYPTION_KEY` | | `all` | Les deux (explicite) | | `auth` | `AUTH_SECRET` uniquement | | `encryption` | `SOVRIUM_ENCRYPTION_KEY` uniquement | Les lignes `.env` générées sont écrites sur la sortie standard (pour que les redirections fonctionnent proprement) ; les messages d'information vont sur la sortie d'erreur. ```bash # Les deux secrets sovrium secret generate # Ajouter un nouveau AUTH_SECRET à votre .env sovrium secret generate auth >> .env # Clé de chiffrement uniquement sovrium secret generate encryption ``` ### `sovrium update` Met à jour Sovrium vers la dernière version. Le comportement dépend de la méthode d'installation : | Méthode d'installation | Comportement | | ---------------------- | --------------------------------------------------------- | | `binary` | Auto-remplacement depuis GitHub Releases (Unix) | | `homebrew` | Délègue à `brew upgrade sovrium/tap/sovrium` | | `scoop` | Délègue à `scoop update sovrium` | | `docker` | Affiche l'instruction `docker pull` | | `npm` | Affiche un avis d'obsolescence (le paquet npm est retiré) | ```bash sovrium update sovrium update --help ``` ### `sovrium --help` Affiche le message d'aide avec un résumé des commandes, des options et des exemples. ```bash sovrium --help ``` ## Options Les options peuvent être placées n'importe où dans la commande. | Option | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `--watch, -w` | Surveille le fichier de configuration et recharge automatiquement le serveur à chaud. Disponible uniquement avec la commande `start`. | | `--version, -V` | Affiche le numéro de version de Sovrium et quitte. | | `--output ` | Écrit la sortie dans un fichier au lieu de la sortie standard (commande `schema` uniquement). | | `--template ` | Modèle de projet à partir duquel échafauder (commande `init`). | | `--name ` | Nom de l'application à définir lors de l'échafaudage (commande `init`). | | `--target ` | Répertoire de destination de l'installation, par défaut le répertoire courant (commande `agents install`). | | `--config ` | Fichier de configuration utilisé pour résoudre le schéma de la base de données (commande `admin create`). | | `--password ` | Mot de passe administrateur ; s'il est omis, il vous est demandé de manière interactive (commande `admin create`). | | `--force` | Écrase les fichiers existants ou un schéma en direct dérivé (`init`, `reload`, `agents install`). | | `--help, -h` | Affiche le message d'aide et quitte. | ## Sources de configuration Sovrium peut charger la configuration depuis un chemin de fichier ou depuis la variable d'environnement `APP_SCHEMA`. Un chemin de fichier a la priorité lorsque les deux sont fournis. ### Chemin de fichier Passez un chemin vers un fichier de configuration JSON ou YAML comme deuxième argument. ```bash sovrium start app.yaml sovrium build config.json ``` ### Variable d'environnement Définissez la variable `APP_SCHEMA` pour fournir la configuration sans fichier. Prend en charge le JSON en ligne, le YAML en ligne ou une URL distante. ```bash # JSON en ligne APP_SCHEMA='{"name":"my-app"}' sovrium start # YAML en ligne APP_SCHEMA='name: my-app' sovrium start # URL distante APP_SCHEMA='https://example.com/app.yaml' sovrium start ``` :::callout **YAML ou JSON.** Sovrium prend en charge les fichiers `.yaml`/`.yml` et `.json`. Le YAML est recommandé pour sa lisibilité. ::: ## Mode surveillance Le mode surveillance surveille votre fichier de configuration et recharge automatiquement le serveur lorsque des modifications sont détectées. ```bash # Démarrer avec la surveillance de fichier sovrium start app.yaml --watch # Modifiez app.yaml dans un autre terminal... # Le serveur se recharge automatiquement ``` :::callout **Récupération d'erreur.** Si le fichier de configuration mis à jour est invalide, le rechargement échoue proprement et le serveur précédent continue de fonctionner. Corrigez la configuration et enregistrez pour réessayer. ::: ## Exemples Cas d'utilisation courants du CLI. ### `sovrium start` ```bash # Démarrer depuis un fichier JSON sovrium start app.json # Démarrer depuis un fichier YAML sovrium start app.yaml # Démarrage implicite (commande par défaut) sovrium app.yaml # Démarrer avec le mode surveillance (rechargement à chaud) sovrium start app.yaml --watch sovrium start app.yaml -w # Démarrer sur un port personnalisé PORT=8080 sovrium start app.yaml ``` ### `sovrium build` ```bash # Build statique de base sovrium build app.yaml # Build pour GitHub Pages SOVRIUM_DEPLOYMENT=github-pages sovrium build app.yaml # Build avec sitemap et sortie personnalisée SOVRIUM_OUTPUT_DIR=./public \ SOVRIUM_BASE_URL=https://example.com \ SOVRIUM_GENERATE_SITEMAP=true \ SOVRIUM_GENERATE_ROBOTS=true \ sovrium build app.yaml ``` ### `sovrium schema` ```bash # Afficher le JSON Schema sur la sortie standard sovrium schema # Écrire le JSON Schema dans un fichier sovrium schema --output app.schema.json ``` ### `sovrium validate ` ```bash # Valider une configuration YAML sovrium validate app.yaml # Valider une configuration JSON sovrium validate config.json ``` ## Codes de sortie Le CLI utilise des codes de sortie standard. | Code | Signification | | ---- | -------------------------------------------------------------------- | | `0` | Succès | | `1` | Erreur (configuration invalide, fichier manquant, commande inconnue) | ## Pages associées - [Fichiers de configuration](/fr/docs/configuration-files) — configurations multi-fichiers YAML, JSON, TypeScript et `$ref`. - [Variables d'environnement](/fr/docs/env-vars) — `APP_SCHEMA`, `PORT`, `DATABASE_URL` et variables de build. - [Métadonnées de l'application](/fr/docs/app-metadata) — le registre de versions et la détection de dérive que `reload` respecte.