> 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/de/integrationen-und-apis/vrg-cli.md). # VergeOS CLI (vrg) ## Ü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) ```bash pipx install vrg ``` ### pip ```bash pip install vrg ``` ### uv ```bash uv tool install vrg ``` ### Homebrew ```bash brew install verge-io/tap/vrg ``` ### Eigenständige Binärdatei Lade eine vorgefertigte Binärdatei von der [neuesten Version](https://github.com/verge-io/vrg/releases/latest) herunter und lege sie dann in dein `PATH`. Binärdateien sind verfügbar für Linux (x86\_64), macOS (ARM64) und Windows (x86\_64). {% hint style="warning" %} **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: ```bash xattr -d com.apple.quarantine ./vrg ``` {% endhint %} Nach der Installation mit folgendem Befehl prüfen: ```bash 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](https://github.com/verge-io/vrg/releases/latest) | ## Schnellstart ```bash # 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](#authentication) 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 ` 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: ```bash # 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: ```bash 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): ```bash 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 ``` {% hint style="success" %} **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. {% endhint %} ## Befehlsmuster Alle `vrg` Befehle folgen einer einheitlichen Struktur: ``` vrg [global-options] [sub-domain] [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](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) . ## Anwendungsbeispiele ### VMs auflisten und prüfen ```bash # 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](#vm-templates). ```bash # 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 ``` {% hint style="info" %} **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. {% endhint %} ### Mit Netzwerken arbeiten ```bash # 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: ```bash # 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 ```bash # 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`: ```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 ```bash # 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 ``` {% hint style="success" %} **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. {% endhint %} Für die vollständige Referenz der Vorlagenfelder siehe den [Vorlagenleitfaden](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) . ## 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 | ```bash # 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: ```bash vrg --install-completion ``` {% hint style="warning" %} **macOS zsh: unsichere Verzeichnisse** Wenn Sie `compinit: unsichere Verzeichnisse` nach der Installation der Vervollständigungen auf macOS sehen, beheben Sie die Verzeichnisberechtigungen von Homebrew: ```bash chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions ``` {% endhint %} ## 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](/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.md) | Sie Python-Anwendungen schreiben, komplexe Automatisierungen erstellen oder andere Python-Tools integrieren | | [PowerShell-Modul](/automate-protect-and-extend/de/integrationen-und-apis/powershell-module.md) | Sie primär auf Windows setzen oder bereits mit PowerShell automatisieren | | [Terraform-Provider](/automate-protect-and-extend/de/integrationen-und-apis/terraform-provider.md) | Sie VergeOS zusammen mit anderer von Terraform verwalteter Infrastruktur verwalten | | [Go-SDK](/automate-protect-and-extend/de/integrationen-und-apis/go-sdk.md) | Sie die VergeOS-Verwaltung in eine Go-Anwendung einbetten | ## Ressourcen & Support * [GitHub-Repository](https://github.com/verge-io/vrg) — Quellcode, Issues und Releases * [Befehlsreferenz](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) — jeder Befehl und jedes Flag * [Vorlagenleitfaden](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) — vollständige `.vrg.yaml` Feldreferenz * [Kochbuch](https://github.com/verge-io/vrg/blob/main/docs/COOKBOOK.md) — aufgabenorientierte Anleitungen * [Architektur](https://github.com/verge-io/vrg/blob/main/docs/ARCHITECTURE.md) — Design und Interna * [Bekannte Probleme](https://github.com/verge-io/vrg/blob/main/docs/KNOWN_ISSUES.md) — aktuelle Einschränkungen und Workarounds * [PyPI-Paket](https://pypi.org/project/vrg/) * [Ein Problem melden](https://github.com/verge-io/vrg/issues) * [VergeOS-API-Dokumentation](/knowledge-base/de/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/de/integrationen-und-apis/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.