> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/vrg-cli.md). # CLI VergeOS (vrg) ## Vue d’ensemble `vrg` est l'interface officielle en ligne de commande pour VergeOS. Elle fournit plus de 200 commandes couvrant le calcul, le réseau, les locataires, le NAS, l'identité, l'automatisation et la surveillance, ainsi que la configuration déclarative `.vrg.yaml` des modèles de VM pour un approvisionnement reproductible et contrôlé par version. Utilisez-les pour l'administration prioritairement au terminal, les scripts shell et les pipelines CI/CD. ## Prérequis * Python 3.10 ou version ultérieure (lors de l'installation via `pip`, `pipx`, ou `uv`) * Un compte utilisateur ou une clé API disposant des autorisations appropriées sur l'instance VergeOS ## Installation `vrg` peut être installé de plusieurs façons. `pipx` est recommandé, car il isole l'outil CLI dans son propre environnement virtuel. ### pipx (recommandé) ```bash pipx install vrg ``` ### pip ```bash pip install vrg ``` ### uv ```bash uv tool install vrg ``` ### Homebrew ```bash brew install verge-io/tap/vrg ``` ### Binaire autonome Téléchargez un binaire précompilé depuis la [dernière version](https://github.com/verge-io/vrg/releases/latest) , puis placez-le dans votre `PATH`. Des binaires sont disponibles pour Linux (x86\_64), macOS (ARM64) et Windows (x86\_64). {% hint style="warning" %} **Quarantaine macOS** Sur macOS, le binaire autonome peut être mis en quarantaine par Gatekeeper. Supprimez l'attribut avant de l'exécuter : ```bash xattr -d com.apple.quarantine ./vrg ``` {% endhint %} Après l'installation, vérifiez avec : ```bash vrg --version ``` ### Mise à niveau | Méthode d'installation | Commande de mise à niveau | | ---------------------- | ---------------------------------------------------------------------------------------------------- | | `pipx` | `pipx upgrade vrg` | | `pip` | `pip install --upgrade vrg` | | `uv` | `uv tool upgrade vrg` | | Homebrew | `brew upgrade vrg` | | Autonome | Téléchargez à nouveau depuis la [page des versions](https://github.com/verge-io/vrg/releases/latest) | ## Démarrage rapide ```bash # 1. Configurez les identifiants (assistant interactif) vrg configure setup # 2. Vérifiez la connexion vrg system info # 3. Découvrez les commandes au fur et à mesure — chaque commande prend en charge --help vrg --help vrg vm --help # 4. Listez vos VM vrg vm list ``` `vrg configure setup` est un assistant interactif qui demande l'URL de l'hôte, la méthode d'authentification et le format de sortie par défaut. Il enregistre le résultat dans `~/.vrg/config.toml`. Voir [Authentification](#authentication) les détails de chaque méthode et comment automatiser les identifiants. ## Authentification `vrg` accepte quatre méthodes d'authentification. Les quatre peuvent être fournies via l'assistant interactif, des variables d'environnement, des options de ligne de commande ou un profil dans `~/.vrg/config.toml`. | Méthode | Idéal pour | Comment fournir | | ------------------------------------ | ------------------------------------------ | ------------------------------------------------------------ | | **Jeton Bearer** | Pipelines CI, scripts | `--token` option ou `VERGE_TOKEN` variable d'environnement | | **Clé API** | Automatisation de service longue durée | `--api-key` option | | **Nom d'utilisateur + mot de passe** | Sessions interactives, actions ponctuelles | `--username` / `--password` ou invites de l'assistant | | **Profil** | Instances multiples | `--profile ` après avoir exécuté `vrg configure setup` | ### Génération d'une clé API Les clés API sont gérées à la fois dans l'interface VergeOS (System → API Keys) et via la CLI elle-même une fois que vous vous êtes authentifié par une autre méthode : ```bash # Après votre première connexion interactive, générez une clé longue durée pour CI vrg api-key create --name ci-pipeline vrg api-key list ``` Traitez la valeur renvoyée comme un secret — stockez-la dans le gestionnaire de secrets de votre fournisseur CI, jamais dans le code source. ### Variables d'environnement Les variables d'environnement remplacent les valeurs du fichier de configuration, ce qui les rend idéales pour CI/CD : ```bash export VERGE_HOST=https://verge.example.com export VERGE_TOKEN=eyJhbGc... vrg vm list ``` ### Profils Les profils vous permettent de passer d'une instance VergeOS à une autre (production, préproduction, environnements clients) : ```bash vrg configure setup --profile prod # Configurer un profil nommé vrg configure list # Lister les profils configurés vrg configure show # Afficher le profil actif (identifiants masqués) vrg --profile prod vm list # Utiliser un profil spécifique pour une commande vrg -p staging vm list # Forme abrégée ``` {% hint style="success" %} **Requêtes inter-profils** Utilisez `--all-profiles` dans une commande de liste pour l'exécuter sur chaque profil configuré. Chaque ligne de sortie inclut une `profil` colonne indiquant son origine. {% endhint %} ## Modèle de commande Toutes `vrg` les commandes suivent une structure cohérente : ``` vrg [global-options] [sub-domain] [arguments] [options] ``` La plupart des ressources implémentent les actions CRUD standard : `list`, `get`, `create`, `update`, et `delete`. Les opérations destructrices nécessitent `--yes` pour ignorer l'invite de confirmation. ### Domaines de commande | Domaine | Sous-domaines | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Calcul** | `vm`, `vm drive`, `vm nic`, `vm device`, `vm snapshot`, `vm export`, `vm import` | | **Réseautage** | `network`, `network rule`, `network dns`, `network host`, `network alias`, `network diag`, `network query` | | **Locataires** | `locataire`, `tenant node`, `tenant storage`, `tenant net`, `tenant snapshot`, `tenant stats`, `tenant share`, `tenant logs` | | **NAS** | `nas service`, `nas volume`, `nas cifs`, `nas nfs`, `nas user`, `nas sync`, `nas files` | | **Infrastructure** | `cluster`, `node`, `stockage` | | **Instantanés** | `instantané`, `profil d'instantanés` | | **Sites et réplication** | `site`, `synchronisation de site sortante`, `synchronisation de site entrante` | | **Identité et accès** | `utilisateur`, `groupe`, `autorisation`, `clé-api`, `source d'authentification` | | **Certificats et SSO** | `certificat`, `OIDC` | | **Automatisation** | `tâche`, `planification de tâche`, `déclencheur de tâche`, `événement de tâche`, `script de tâche` | | **Recettes** | `recette`, `section de recette`, `question de recette`, `instance de recette`, `journal de recette` | | **Catalogue** | `catalogue`, `dépôt de catalogue` | | **Mises à jour** | `update`, `source de mise à jour`, `branche de mise à jour`, `paquet de mise à jour`, `mise à jour disponible` | | **Surveillance** | `alarme`, `historique des alarmes`, `journal` | | **Étiquetage** | `étiquette`, `catégorie d'étiquette`, `groupe de ressources` | | **Système** | `système`, `paramètres système`, `licence système`, `diagnostic système`, `doctor`, `configurer`, `fichier`, `autocomplétion` | La référence complète est maintenue dans le [Référence des commandes](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) . ## Exemples d'utilisation ### Liste et inspection des VM ```bash # Lister toutes les VM vrg vm list # Inspectez une VM vrg vm get web-server # État d'alimentation vrg vm start web-server --wait # --wait bloque jusqu'à ce que la VM soit en cours d'exécution vrg vm stop web-server --wait vrg vm restart web-server ``` ### Création d'une VM à partir d'options shell L'approche par options shell est adaptée aux expériences rapides. Pour un approvisionnement reproductible, consultez [Modèles de VM](#vm-templates). ```bash # Créez une VM (--ram est en Mo) vrg vm create --name web-server --ram 4096 --cpu 2 # Ajoutez un disque de 50 Go et attachez une NIC vrg vm drive create web-server --size 50GB --name os-disk vrg vm nic create web-server --network External # Démarrez la VM vrg vm start web-server --wait ``` {% hint style="info" %} **Les VM vides ne démarrent pas** Une VM créée à partir d'options shell n'a aucun système d'exploitation associé. Pour en installer un, démarrez soit depuis un lecteur ISO (`vrg vm drive create … --media cdrom`), clonez une VM existante (`vrg vm clone`), ou définissez une image OS et cloud-init dans un `.vrg.yaml` modèle. {% endhint %} ### Travail avec les réseaux ```bash # Créez un réseau interne avec DHCP vrg network create --name dev-net --cidr 10.0.0.0/24 --ip 10.0.0.1 --dhcp vrg network start dev-net # Autorisez les connexions SSH entrantes (--dest-ports accepte un port unique, une plage « 80-443 » ou « 80,443 ») vrg network rule create dev-net \ --name allow-ssh --action accept --direction incoming \ --protocol tcp --dest-ports 22 # Appliquez les modifications de pare-feu en attente vrg network apply-rules dev-net ``` ### Diagnostics du réseau et des nœuds `vrg` expose des requêtes de diagnostic qui s'exécutent sur le routeur virtuel d'un réseau ou directement sur un nœud physique : ```bash # Tests de connectivité réseau vrg network query ping External 8.8.8.8 vrg network query traceroute External 8.8.8.8 vrg network query dns External example.com # Vérifications matérielles du nœud vrg node query smartctl node1 /dev/sda vrg node query ipmi-sensor node1 vrg node lldp list node1 ``` ### Vérification de l'état du système ```bash # Exécutez toutes les vérifications de santé intégrées vrg doctor # Exécutez un sous-ensemble spécifique vrg doctor --check connectivity,clusters,nodes,storage # Sortie JSON pour l'automatisation ; code de sortie 0 = sain, 1 = échecs vrg -o json doctor | jq '.[] | select(.status == \"fail\")' ``` ## Modèles de VM Définissez les VM sous forme de `.vrg.yaml` des fichiers pour un approvisionnement reproductible et contrôlé par version. Les modèles prennent en charge les variables, les aperçus en simulation et les substitutions à l'exécution via `--set`, cloud-init et la création par lot avec `VirtualMachineSet`. ### Exemple de modèle Enregistrez ce qui suit sous `web-server.vrg.yaml`: ```yaml apiVersion: v4 kind: VirtualMachine vm: name: web-server-01 os_family: linux cpu_cores: 4 ram: 8GB machine_type: q35 uefi: true guest_agent: true cloudinit: datasource: nocloud files: - name: user-data content: | #cloud-config hostname: web-server-01 packages: - nginx - qemu-guest-agent runcmd: - systemctl enable --now nginx drives: - name: "Disque OS" media: disk interface: virtio-scsi size: 50GB nics: - name: "Principal" interface: virtio network: External ``` ### Validation et création ```bash # Validez le modèle par rapport au schéma vrg vm validate -f web-server.vrg.yaml # Prévisualisez l'opération sans apporter de modifications vrg vm create -f web-server.vrg.yaml --dry-run # Créez la VM vrg vm create -f web-server.vrg.yaml # Remplacez un champ à l'exécution vrg vm create -f web-server.vrg.yaml \ --set vm.name=web-server-02 --set vm.ram=16GB ``` {% hint style="success" %} **Variables et valeurs par défaut** Prise en charge des modèles `${VAR}` substitution à partir des variables d’environnement ou d’un `vars:` bloc, ainsi que la syntaxe de valeur par défaut (`${VM_RAM:-4GB}`). C’est utile pour paramétrer un seul modèle à travers plusieurs environnements. {% endhint %} Pour la référence complète des champs de modèle, consultez le [Guide des modèles](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) . ## Formats de sortie Toutes les commandes prennent en charge `--output` (ou `-o`) pour modifier le format de sortie et `--query` pour extraire un champ avec la notation par points. | Format | Cas d’utilisation | | ------- | --------------------------------------------------------------------------------- | | `table` | Sortie lisible par l’humain par défaut | | `large` | Toutes les colonnes disponibles, y compris celles masquées dans la vue par défaut | | `json` | Sortie lisible par machine pour être transmise à `jq` ou à d’autres outils | | `csv` | Export compatible avec les tableurs | ```bash # Toutes les colonnes vrg -o wide vm list # JSON pour les scripts vrg -o json vm list | jq '.[].name' # Export CSV vrg -o csv vm list > vms.csv # Extraire un seul champ avec la notation par points (prend en charge les chemins imbriqués) vrg --query status vm get web-server vrg --query nics[0].network vm get web-server ``` ## Complétion du shell La complétion par tabulation est disponible pour bash, zsh, fish et PowerShell. Le moyen le plus rapide de l’activer est : ```bash vrg --install-completion ``` {% hint style="warning" %} **zsh sur macOS : répertoires non sécurisés** Si vous voyez `compinit: insecure directories` après avoir installé la complétion sur macOS, corrigez les permissions du répertoire Homebrew : ```bash chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions ``` {% endhint %} ## Options globales | Option | Raccourci | Description | | ---------------- | --------- | ------------------------------------------------------------------ | | `--profile` | `-p` | Profil de configuration à utiliser | | `--host` | `-H` | URL de l’hôte VergeOS (remplacement) | | `--token` | | Jeton bearer pour l’authentification | | `--api-key` | | Clé API pour l’authentification | | `--username` | `-u` | Nom d’utilisateur pour l’authentification de base | | `--password` | | Mot de passe pour l’authentification de base | | `--output` | `-o` | Format de sortie (`table`, `large`, `json`, `csv`) | | `--query` | | Extraire un champ à l’aide de la notation par points | | `--all-profiles` | | Exécuter les commandes de liste sur chaque profil configuré | | `--verbose` | `-v` | Augmenter la verbosité (`-v`, `-vv`, `-vvv`) | | `--quiet` | `-q` | Masquer la sortie non essentielle | | `--no-color` | | Désactiver la sortie en couleur | | `--yes` | | Ignorer les invites de confirmation pour les actions destructrices | | `--version` | `-V` | Afficher la version | | `--help` | | Afficher l’aide | ## Codes de sortie `vrg` utilise des codes de sortie significatifs pour les scripts et l’intégration CI : | Code | Signification | | ---- | ------------------------------- | | 0 | Succès | | 1 | Erreur générale | | 2 | Arguments invalides | | 3 | Erreur de configuration | | 4 | Erreur d’authentification | | 5 | Permission refusée | | 6 | Ressource introuvable | | 7 | Conflit (par ex. nom en double) | | 8 | Erreur de validation | | 9 | Délai d’attente dépassé | | 10 | Erreur de connexion | ## Dépannage | Symptôme | Cause probable | Correction | | ---------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------- | | Code de sortie 4 | Échec de l’authentification | Exécutez `vrg configure setup` et vérifiez le jeton, la clé API ou les identifiants | | Code de sortie 3 | Erreur de configuration | Vérifiez `~/.vrg/config.toml` ou exécutez `vrg configure show` | | Code de sortie 10 | Erreur de connexion | Vérifier `VERGE_HOST` est accessible et que l’URL est correcte | | `compinit: insecure directories` (macOS) | Autorisations Homebrew | `chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions` | | `vrg` bloqué sur macOS | Quarantaine Gatekeeper | `xattr -d com.apple.quarantine ./vrg` | ## Choisir le bon outil `vrg` est l’une des plusieurs interfaces d’automatisation VergeOS. Choisissez selon votre façon de travailler : | Outil | À utiliser quand | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **CLI vrg** | Vous travaillez dans un terminal, souhaitez des modèles de VM déclaratifs ou avez besoin d’un script ponctuel | | [SDK Python](/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md) | Vous écrivez des applications Python, de l’automatisation complexe ou vous intégrez d’autres outils Python | | [Module PowerShell](/automate-protect-and-extend/fr/integrations-et-api/powershell-module.md) | Votre environnement est d’abord Windows ou vous automatisez déjà avec PowerShell | | [Fournisseur Terraform](/automate-protect-and-extend/fr/integrations-et-api/terraform-provider.md) | Vous gérez VergeOS aux côtés d’autres infrastructures gérées par Terraform | | [SDK Go](/automate-protect-and-extend/fr/integrations-et-api/go-sdk.md) | Vous intégrez la gestion de VergeOS dans une application Go | ## Ressources et assistance * [Dépôt GitHub](https://github.com/verge-io/vrg) — source, problèmes et versions * [Référence des commandes](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) — chaque commande et chaque option * [Guide des modèles](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) — complet `.vrg.yaml` référence des champs * [Livre de recettes](https://github.com/verge-io/vrg/blob/main/docs/COOKBOOK.md) — recettes orientées tâches * [Architecture](https://github.com/verge-io/vrg/blob/main/docs/ARCHITECTURE.md) — conception et interne * [Problèmes connus](https://github.com/verge-io/vrg/blob/main/docs/KNOWN_ISSUES.md) — limitations actuelles et solutions de contournement * [Package PyPI](https://pypi.org/project/vrg/) * [Signaler un problème](https://github.com/verge-io/vrg/issues) * [Documentation de l'API VergeOS](/knowledge-base/fr/automation-api/verge-api-guide.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/fr/integrations-et-api/vrg-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.