CLI VergeOS (vrg)

vrg est l’interface en ligne de commande officielle de VergeOS, fournissant plus de 200 commandes pour gérer les machines virtuelles, les réseaux, les locataires, le NAS et plus encore depuis un terminal ou un pipeline d’automatisation.

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é)

pipx install vrg

pip

pip install vrg

uv

uv tool install vrg

Homebrew

brew install verge-io/tap/vrg

Binaire autonome

Téléchargez un binaire précompilé depuis la dernière version , puis placez-le dans votre PATH. Des binaires sont disponibles pour Linux (x86_64), macOS (ARM64) et Windows (x86_64).

Quarantaine macOS

Sur macOS, le binaire autonome peut être mis en quarantaine par Gatekeeper. Supprimez l'attribut avant de l'exécuter :

xattr -d com.apple.quarantine ./vrg

Après l'installation, vérifiez avec :

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

Démarrage rapide

# 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 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 <name> 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 :

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

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) :

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

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.

Modèle de commande

Toutes vrg les commandes suivent une structure cohérente :

vrg [global-options] <domain> [sub-domain] <action> [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 .

Exemples d'utilisation

Liste et inspection des VM

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

# 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

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.

Travail avec les réseaux

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

# 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

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

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

# 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

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.

Pour la référence complète des champs de modèle, consultez le Guide des modèles .

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

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

vrg --install-completion

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 :

chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

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	Vous écrivez des applications Python, de l’automatisation complexe ou vous intégrez d’autres outils Python
Module PowerShell	Votre environnement est d’abord Windows ou vous automatisez déjà avec PowerShell
Fournisseur Terraform	Vous gérez VergeOS aux côtés d’autres infrastructures gérées par Terraform
SDK Go	Vous intégrez la gestion de VergeOS dans une application Go

Ressources et assistance

• Dépôt GitHub — source, problèmes et versions
• Référence des commandes — chaque commande et chaque option
• Guide des modèles — complet .vrg.yaml référence des champs
• Livre de recettes — recettes orientées tâches
• Architecture — conception et interne
• Problèmes connus — limitations actuelles et solutions de contournement
• Package PyPI
• Signaler un problème
• Documentation de l'API VergeOS