VergeOS CLI (vrg)

vrg ist die offizielle Befehlszeilenschnittstelle für VergeOS und bietet über 200 Befehle zur Verwaltung virtueller Maschinen, Netzwerke, Tenants, NAS und mehr über ein Terminal oder eine Automatisierungspipeline.

Übersicht

vrg ist die offizielle Befehlszeilenschnittstelle für VergeOS. Sie bietet über 200 Befehle für Compute, Netzwerke, Mandanten, NAS, Identität, Automatisierung und Überwachung sowie deklarative .vrg.yaml VM-Vorlagen für reproduzierbare, versionskontrollierte Bereitstellung. Verwende sie für die Administration zuerst im Terminal, Shell-Scripting und CI/CD-Pipelines.

Anforderungen

• Python 3.10 oder höher (bei der Installation über pip, pipx, oder uv)
• Ein Benutzerkonto oder API-Schlüssel mit den entsprechenden Berechtigungen auf der VergeOS-Instanz

Installation

vrg kann auf mehrere Arten installiert werden. pipx wird empfohlen, da es die CLI in einer eigenen virtuellen Umgebung isoliert.

pipx (empfohlen)

pipx install vrg

pip

pip install vrg

uv

uv tool install vrg

Homebrew

brew install verge-io/tap/vrg

Eigenständige Binärdatei

Lade eine vorgefertigte Binärdatei von der neuesten Version herunter und lege sie dann in dein PATH. Binärdateien sind verfügbar für Linux (x86_64), macOS (ARM64) und Windows (x86_64).

macOS-Quarantäne

Unter macOS kann die eigenständige Binärdatei von Gatekeeper in Quarantäne gesetzt werden. Entferne das Attribut vor dem Ausführen:

xattr -d com.apple.quarantine ./vrg

Nach der Installation mit folgendem Befehl prüfen:

vrg --version

Aktualisieren

Installationsmethode	Upgrade-Befehl
pipx	pipx upgrade vrg
pip	pip install --upgrade vrg
uv	uv tool upgrade vrg
Homebrew	brew upgrade vrg
Eigenständig	Erneut herunterladen von der Release-Seite

Schnellstart

# 1. Anmeldedaten konfigurieren (interaktiver Assistent)
vrg configure setup

# 2. Die Verbindung prüfen
vrg system info

# 3. Befehle unterwegs entdecken — jeder Befehl unterstützt --help
vrg --help
vrg vm --help

# 4. Deine VMs auflisten
vrg vm list

vrg configure setup ist ein interaktiver Assistent, der nach der Host-URL, der Authentifizierungsmethode und dem Standard-Ausgabeformat fragt. Er speichert das Ergebnis in ~/.vrg/config.toml. Siehe Authentifizierung für Details zu jeder Methode und dazu, wie Anmeldedaten per Skript bereitgestellt werden.

Authentifizierung

vrg unterstützt vier Authentifizierungsmethoden. Alle vier können über den interaktiven Assistenten, Umgebungsvariablen, Befehlszeilen-Flags oder ein Profil in ~/.vrg/config.toml.

Methode	Am besten geeignet für	Bereitzustellen über
Bearer-Token	CI-Pipelines, Skripte	--token Flag oder VERGE_TOKEN Umgebungsvariable
API-Schlüssel	Langfristige Dienstautomatisierung	--api-key Flag
Benutzername + Passwort	Interaktive Sitzungen, Einzelaufrufe	--username / --password oder Assistentenabfragen
Profil	Mehrere Instanzen	--profile <name> nach dem Ausführen von vrg configure setup

Einen API-Schlüssel generieren

API-Schlüssel werden sowohl in der VergeOS-Oberfläche (System → API Keys) als auch über die CLI selbst verwaltet, sobald du dich auf eine andere Weise authentifiziert hast:

# Nach deinem ersten interaktiven Login einen langlebigen Schlüssel für CI erstellen
vrg api-key create --name ci-pipeline
vrg api-key list

Behandle den zurückgegebenen Wert als Geheimnis — speichere ihn im Secret-Manager deines CI-Anbieters, niemals in der Quellcodeverwaltung.

Umgebungsvariablen

Umgebungsvariablen überschreiben Werte in der Konfigurationsdatei, was sie ideal für CI/CD macht:

export VERGE_HOST=https://verge.example.com
export VERGE_TOKEN=eyJhbGc...
vrg vm list

Profile

Profile ermöglichen dir den Wechsel zwischen mehreren VergeOS-Instanzen (Produktion, Staging, Kundenumgebungen):

vrg configure setup --profile prod   # Ein benanntes Profil einrichten
vrg configure list                   # Konfigurierte Profile auflisten
vrg configure show                   # Aktives Profil anzeigen (Anmeldedaten maskiert)
vrg --profile prod vm list           # Ein bestimmtes Profil für einen Befehl verwenden
vrg -p staging vm list               # Kurzform

Abfragen über Profile hinweg

Verwende --all-profiles bei einem Listen-Befehl, um ihn gegen jedes konfigurierte Profil auszuführen. Jede Ausgabzeile enthält eine Profil Spalte, die zeigt, woher sie stammt.

Befehlsmuster

Alle vrg Befehle folgen einer einheitlichen Struktur:

vrg [global-options] <domain> [sub-domain] <action> [arguments] [options]

Die meisten Ressourcen implementieren standardmäßige CRUD-Aktionen: list, get, create, update, und delete. Zerstörerische Operationen erfordern --yes um die Bestätigungsabfrage zu überspringen.

Befehlsbereiche

Bereich	Unterbereiche
Compute	vm, vm drive, vm nic, vm device, vm snapshot, vm export, vm import
Netzwerk	network, network rule, network dns, network host, network alias, network diag, network query
Mandanten	tenant, 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
Infrastruktur	cluster, node, storage
Snapshots	snapshot, Snapshot-Profil
Standorte & Replikation	site, site sync outgoing, site sync incoming
Identität & Zugriff	user, group, permission, api-key, auth-source
Zertifikate & SSO	certificate, oidc
Automatisierung	task, task schedule, task trigger, task event, task script
Rezepte	recipe, recipe section, recipe question, recipe instance, recipe log
Katalog	catalog, catalog repo
Updates	update, update source, update branch, update package, update available
Überwachung	alarm, alarm history, log
Tagging	tag, tag category, resource-group
System	system, system settings, system license, system diag, doctor, configure, file, completion

Die vollständige Referenz wird im Befehlsreferenz .

Anwendungsbeispiele

VMs auflisten und prüfen

# Alle VMs auflisten
vrg vm list

# Eine einzelne VM prüfen
vrg vm get web-server

# Power-Status
vrg vm start web-server --wait    # --wait blockiert, bis die VM läuft
vrg vm stop web-server --wait
vrg vm restart web-server

Eine VM aus Shell-Flags erstellen

Der Ansatz mit Shell-Flags eignet sich gut für schnelle Experimente. Für wiederholbare Bereitstellung siehe VM-Vorlagen.

# Eine VM erstellen (--ram ist in MB)
vrg vm create --name web-server --ram 4096 --cpu 2

# Eine 50-GB-Festplatte hinzufügen und eine NIC anhängen
vrg vm drive create web-server --size 50GB --name os-disk
vrg vm nic create web-server --network External

# Die VM starten
vrg vm start web-server --wait

Leere VMs booten nicht

Eine VM, die aus Shell-Flags erstellt wurde, hat kein angeschlossenes Betriebssystem. Um eines zu installieren, boote entweder von einem ISO-Laufwerk (vrg vm drive create … --media cdrom), klone eine vorhandene VM (vrg vm clone), oder definiere ein OS-Image und cloud-init in einer .vrg.yaml Vorlage.

Mit Netzwerken arbeiten

# Ein internes Netzwerk mit DHCP erstellen
vrg network create --name dev-net --cidr 10.0.0.0/24 --ip 10.0.0.1 --dhcp
vrg network start dev-net

# Eingehendes SSH zulassen (--dest-ports akzeptiert einen einzelnen Port, den Bereich "80-443" oder "80,443")
vrg network rule create dev-net \\
  --name allow-ssh --action accept --direction incoming \\
  --protocol tcp --dest-ports 22

# Ausstehende Firewall-Änderungen anwenden
vrg network apply-rules dev-net

Netzwerk- und Knoten-Diagnose

vrg stellt Diagnoseabfragen bereit, die auf dem virtuellen Router eines Netzwerks oder direkt auf einem physischen Knoten ausgeführt werden:

# Tests der Netzwerkkonnektivität
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

# Hardwareprüfungen am Knoten
vrg node query smartctl node1 /dev/sda
vrg node query ipmi-sensor node1
vrg node lldp list node1

System-Gesundheitsprüfung

# Alle integrierten Gesundheitsprüfungen ausführen
vrg doctor

# Einen bestimmten Teilbereich ausführen
vrg doctor --check connectivity,clusters,nodes,storage

# JSON-Ausgabe für Automatisierung; Exit-Code 0 = gesund, 1 = Fehler
vrg -o json doctor | jq '.[] | select(.status == "fail")'

VM-Vorlagen

Definiere VMs als .vrg.yaml Dateien für wiederholbare, versionskontrollierte Bereitstellung. Vorlagen unterstützen Variablen, Vorschauen per Dry Run, Laufzeitüberschreibungen über --set, cloud-init und Stapelerstellung mit VirtualMachineSet.

Beispielvorlage

Speichere das Folgende als 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: "OS Disk"
      media: disk
      interface: virtio-scsi
      size: 50GB

  nics:
    - name: "Primary"
      interface: virtio
      network: External

Validieren und Erstellen

# Die Vorlage gegen das Schema validieren
vrg vm validate -f web-server.vrg.yaml

# Die Operation in der Vorschau anzeigen, ohne Änderungen vorzunehmen
vrg vm create -f web-server.vrg.yaml --dry-run

# Die VM erstellen
vrg vm create -f web-server.vrg.yaml

# Ein Feld zur Laufzeit überschreiben
vrg vm create -f web-server.vrg.yaml \\
  --set vm.name=web-server-02 --set vm.ram=16GB

Variablen und Standardwerte

Unterstützung für Vorlagen ${VAR} Ersetzung aus Umgebungsvariablen oder einem vars: Block sowie Standardsyntax für Werte (${VM_RAM:-4GB}). Dies ist nützlich, um eine einzelne Vorlage über verschiedene Umgebungen hinweg zu parametrieren.

Für die vollständige Referenz der Vorlagenfelder siehe den Vorlagenleitfaden .

Ausgabeformate

Alle Befehle unterstützen --output (oder -o) zum Ändern des Ausgabeformats und --query zum Extrahieren eines Feldes mit Punktnotation.

Format	Anwendungsfall
Tabelle	Standardmäßige menschenlesbare Ausgabe
breit	Alle verfügbaren Spalten, einschließlich der in der Standardansicht ausgeblendeten
JSON	Maschinenlesbare Ausgabe zum Weiterleiten an jq oder andere Werkzeuge
CSV	Tabellenkalkulationsfreundlicher Export

# Alle Spalten
vrg -o wide vm list

# JSON für Skripte
vrg -o json vm list | jq '.[].name'

# CSV-Export
vrg -o csv vm list > vms.csv

# Ein einzelnes Feld mit Punktnotation extrahieren (unterstützt verschachtelte Pfade)
vrg --query status vm get web-server
vrg --query nics[0].network vm get web-server

Shell-Vervollständigung

Tab-Vervollständigung ist für bash, zsh, fish und PowerShell verfügbar. Der schnellste Weg, sie zu aktivieren, ist:

vrg --install-completion

macOS zsh: unsichere Verzeichnisse

Wenn Sie compinit: unsichere Verzeichnisse nach der Installation der Vervollständigungen auf macOS sehen, beheben Sie die Verzeichnisberechtigungen von Homebrew:

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

Globale Optionen

Option	Kurz	Beschreibung
--profile	-p	Zu verwendendes Konfigurationsprofil
--host	-H	VergeOS-Host-URL (überschreiben)
--token		Bearer-Token zur Authentifizierung
--api-key		API-Schlüssel zur Authentifizierung
--username	-u	Benutzername für die Basis-Authentifizierung
--password		Passwort für die Basis-Authentifizierung
--output	-o	Ausgabeformat (Tabelle, breit, JSON, CSV)
--query		Feld mit Punktnotation extrahieren
--all-profiles		List-Befehle über jedes konfigurierte Profil hinweg ausführen
--verbose	-v	Ausführlichkeit erhöhen (-v, -vv, -vvv)
--quiet	-q	Nicht wesentliche Ausgabe unterdrücken
--no-color		Farbausgabe deaktivieren
--yes		Bestätigungsabfragen bei destruktiven Aktionen überspringen
--version	-V	Version anzeigen
--help		Hilfe anzeigen

Exit-Codes

vrg verwendet aussagekräftige Exit-Codes für Skripting und CI-Integration:

Code	Bedeutung
0	Erfolg
1	Allgemeiner Fehler
2	Ungültige Argumente
3	Konfigurationsfehler
4	Authentifizierungsfehler
5	Zugriff verweigert
6	Ressource nicht gefunden
7	Konflikt (z. B. doppelter Name)
8	Validierungsfehler
9	Zeitüberschreitung
10	Verbindungsfehler

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Behebung
Exit-Code 4	Authentifizierungsfehler	Führen Sie vrg configure setup und überprüfen Sie das Token, den API-Schlüssel oder die Anmeldedaten
Exit-Code 3	Konfigurationsfehler	Überprüfen Sie ~/.vrg/config.toml oder führen Sie vrg configure show
Exit-Code 10	Verbindungsfehler	Überprüfen VERGE_HOST erreichbar ist und die URL korrekt ist
compinit: unsichere Verzeichnisse (macOS)	Homebrew-Berechtigungen	chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions
vrg unter macOS blockiert	Gatekeeper-Quarantäne	xattr -d com.apple.quarantine ./vrg

Das richtige Werkzeug wählen

vrg ist eine von mehreren VergeOS-Automatisierungsschnittstellen. Wählen Sie basierend darauf, wie Sie arbeiten:

Werkzeug	Verwenden, wenn
vrg-CLI	Sie im Terminal arbeiten, deklarative VM-Vorlagen möchten oder ein Einmal-Skript benötigen
Python SDK	Sie Python-Anwendungen schreiben, komplexe Automatisierungen erstellen oder andere Python-Tools integrieren
PowerShell-Modul	Sie primär auf Windows setzen oder bereits mit PowerShell automatisieren
Terraform-Provider	Sie VergeOS zusammen mit anderer von Terraform verwalteter Infrastruktur verwalten
Go-SDK	Sie die VergeOS-Verwaltung in eine Go-Anwendung einbetten

Ressourcen & Support

• GitHub-Repository — Quellcode, Issues und Releases
• Befehlsreferenz — jeder Befehl und jedes Flag
• Vorlagenleitfaden — vollständige .vrg.yaml Feldreferenz
• Kochbuch — aufgabenorientierte Anleitungen
• Architektur — Design und Interna
• Bekannte Probleme — aktuelle Einschränkungen und Workarounds
• PyPI-Paket
• Ein Problem melden
• VergeOS-API-Dokumentation