CLI de VergeOS (vrg)

vrg es la interfaz oficial de línea de comandos para VergeOS, que proporciona más de 200 comandos para gestionar máquinas virtuales, redes, tenants, NAS y más desde un terminal o un pipeline de automatización.

Descripción general

vrg es la interfaz oficial de línea de comandos para VergeOS. Ofrece más de 200 comandos en computación, redes, inquilinos, NAS, identidad, automatización y supervisión, además de lo declarativo .vrg.yaml Plantillas de VM para aprovisionamiento reproducible y controlado por versiones. Úselo para administración centrada en terminal, scripting de shell y pipelines de CI/CD.

Requisitos

• Python 3.10 o posterior (al instalar mediante pip, pipx, o uv)
• Una cuenta de usuario o una clave de API con los permisos adecuados en la instancia de VergeOS

Instalación

vrg puede instalarse de varias maneras. pipx se recomienda porque aísla la CLI en su propio entorno virtual.

pipx (recomendado)

pipx install vrg

pip

pip install vrg

uv

uv tool install vrg

Homebrew

brew install verge-io/tap/vrg

Binario independiente

Descargue un binario precompilado desde la última versión , luego colóquelo en su PATH. Los binarios están disponibles para Linux (x86_64), macOS (ARM64) y Windows (x86_64).

Cuarentena de macOS

En macOS, el binario independiente puede quedar en cuarentena por Gatekeeper. Elimine el atributo antes de ejecutarlo:

xattr -d com.apple.quarantine ./vrg

Después de la instalación, verifique con:

vrg --version

Actualización

Método de instalación	Comando de actualización
pipx	pipx upgrade vrg
pip	pip install --upgrade vrg
uv	uv tool upgrade vrg
Homebrew	brew upgrade vrg
Independiente	Vuelva a descargarlo desde la página de versiones

Inicio rápido

# 1. Configure las credenciales (asistente interactivo)
vrg configure setup

# 2. Verifique la conexión
vrg system info

# 3. Descubra los comandos sobre la marcha — cada comando admite --help
vrg --help
vrg vm --help

# 4. Liste sus VMs
vrg vm list

vrg configure setup es un asistente interactivo que solicita la URL del host, el método de autenticación y el formato de salida predeterminado. Guarda el resultado en ~/.vrg/config.toml. Véase Autenticación para los detalles de cada método y cómo automatizar credenciales.

Autenticación

vrg acepta cuatro métodos de autenticación. Los cuatro pueden proporcionarse mediante el asistente interactivo, variables de entorno, flags de la línea de comandos o un perfil en ~/.vrg/config.toml.

Método	Ideal para	Cómo proporcionarlo
Token portador	Pipelines de CI, scripts	--token bandera o VERGE_TOKEN variable de entorno
Clave de API	Automatización de servicios de larga duración	--api-key bandera
Usuario + contraseña	Sesiones interactivas, usos puntuales	--username / --password o indicaciones del asistente
Perfil	Varias instancias	--profile <name> después de ejecutar vrg configure setup

Generación de una clave de API

Las claves de API se gestionan tanto en la IU de VergeOS (System → API Keys) como a través de la propia CLI una vez que se haya autenticado por otro método:

# Después de su primer inicio de sesión interactivo, genere una clave de larga duración para CI
vrg api-key create --name ci-pipeline
vrg api-key list

Trate el valor devuelto como un secreto: guárdelo en el gestor de secretos de su proveedor de CI, nunca en el control de código fuente.

Variables de entorno

Las variables de entorno sobrescriben los valores del archivo de configuración, lo que las hace ideales para CI/CD:

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

Perfiles

Los perfiles le permiten cambiar entre varias instancias de VergeOS (producción, preproducción, entornos de clientes):

vrg configure setup --profile prod   # Configure un perfil con nombre
vrg configure list                   # Liste los perfiles configurados
vrg configure show                   # Muestre el perfil activo (credenciales ocultas)
vrg --profile prod vm list           # Utilice un perfil específico para un comando
vrg -p staging vm list               # Forma abreviada

Consultas entre perfiles

Use --all-profiles en un comando de listado para ejecutarlo contra cada perfil configurado. Cada fila de salida incluye una columna de perfil que muestra de qué perfil proviene.

Patrón de comandos

Todos vrg los comandos siguen una estructura uniforme:

vrg [opciones globales] <dominio> [subdominio] <acción> [argumentos] [opciones]

La mayoría de los recursos implementan acciones CRUD estándar: list, get, create, updatey delete. Las operaciones destructivas requieren --yes para omitir el mensaje de confirmación.

Dominios de comandos

Dominio	Subdominios
Computación	vm, vm drive, vm nic, vm device, vm snapshot, vm export, vm import
Redes	Red, network rule, network dns, network host, network alias, network diag, network query
Inquilinos	Inquilino, 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
Infraestructura	cluster, node, storage
Instantáneas	snapshot, perfil de instantáneas
Sitios y replicación	site, site sync outgoing, site sync incoming
Identidad y acceso	user, group, permission, api-key, auth-source
Certificados y SSO	certificate, oidc
Automatización	Tarea, task schedule, task trigger, task event, task script
Recetas	Receta, recipe section, recipe question, recipe instance, recipe log
Catálogo	catalog, catalog repo
Actualizaciones	update, update source, update branch, update package, update available
Monitorización	alarm, alarm history, log
Etiquetado	tag, tag category, resource-group
Sistema	Sistema, system settings, system license, system diag, doctor, configure, file, completion

La referencia completa se mantiene en la Referencia de comandos .

Ejemplos de uso

Listado e inspección de VMs

# Listar todas las VM
vrg vm list

# Inspeccione una sola VM
vrg vm get web-server

# Estado de encendido
vrg vm start web-server --wait    # --wait espera hasta que la VM esté en ejecución
vrg vm stop web-server --wait
vrg vm restart web-server

Creación de una VM desde flags de shell

El enfoque con flags de shell es bueno para experimentos rápidos. Para aprovisionamiento repetible, consulte Plantillas de VM.

# Crear una VM (--ram está en MB)
vrg vm create --name web-server --ram 4096 --cpu 2

# Añada un disco de 50 GB y conecte una NIC
vrg vm drive create web-server --size 50GB --name os-disk
vrg vm nic create web-server --network External

# Inicie la VM
vrg vm start web-server --wait

Las VMs vacías no arrancan

Una VM creada con flags de shell no tiene un sistema operativo adjunto. Para instalar uno, arranque desde una unidad ISO (vrg vm drive create … --media cdrom), clone una VM existente (vrg vm clone), o defina una imagen del SO y cloud-init en una .vrg.yaml plantilla.

Trabajar con redes

# Cree una red interna con DHCP
vrg network create --name dev-net --cidr 10.0.0.0/24 --ip 10.0.0.1 --dhcp
vrg network start dev-net

# Permitir SSH entrante (--dest-ports acepta un solo puerto, un rango "80-443" o "80,443")
vrg network rule create dev-net \
  --name allow-ssh --action accept --direction incoming \
  --protocol tcp --dest-ports 22

# Aplique los cambios pendientes del firewall
vrg network apply-rules dev-net

Diagnósticos de red y nodo

vrg expone consultas de diagnóstico que se ejecutan en el enrutador virtual de una red o directamente en un nodo físico:

# Pruebas de conectividad de red
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

# Comprobaciones de hardware del nodo
vrg node query smartctl node1 /dev/sda
vrg node query ipmi-sensor node1
vrg node lldp list node1

Verificación del estado del sistema

# Ejecute todas las comprobaciones de estado integradas
vrg doctor

# Ejecute un subconjunto específico
vrg doctor --check connectivity,clusters,nodes,storage

# Salida JSON para automatización; código de salida 0 = correcto, 1 = fallos
vrg -o json doctor | jq '.[] | select(.status == "fail")'

Plantillas de VM

Defina las VMs como .vrg.yaml archivos para un aprovisionamiento repetible y controlado por versiones. Las plantillas admiten variables, previsualizaciones en modo simulación, anulaciones en tiempo de ejecución mediante --set, cloud-init y creación por lotes con VirtualMachineSet.

Plantilla de ejemplo

Guarde lo siguiente como 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

Validación y creación

# Valide la plantilla contra el esquema
vrg vm validate -f web-server.vrg.yaml

# Previsualice la operación sin realizar cambios
vrg vm create -f web-server.vrg.yaml --dry-run

# Cree la VM
vrg vm create -f web-server.vrg.yaml

# Anule un campo en tiempo de ejecución
vrg vm create -f web-server.vrg.yaml \
  --set vm.name=web-server-02 --set vm.ram=16GB

Variables y valores predeterminados

Soporte de plantillas ${VAR} sustitución de variables de entorno o un vars: bloque, además de la sintaxis de valor predeterminado (${VM_RAM:-4GB}). Esto es útil para parametrizar una sola plantilla entre entornos.

Para la referencia completa de los campos de la plantilla, consulte la Guía de plantillas .

Formatos de salida

Todos los comandos admiten --output (o -o) para cambiar el formato de salida y --query para extraer un campo con notación de puntos.

Formato	Caso de uso
tabla	Salida legible predeterminada
ancho	Todas las columnas disponibles, incluidas las ocultas en la vista predeterminada
json	Salida legible por máquina para canalizar a jq u otras herramientas
csv	Exportación compatible con hojas de cálculo

# Todas las columnas
vrg -o wide vm list

# JSON para scripts
vrg -o json vm list | jq '.[].name'

# Exportación CSV
vrg -o csv vm list > vms.csv

# Extrae un solo campo con notación de puntos (admite rutas anidadas)
vrg --query status vm get web-server
vrg --query nics[0].network vm get web-server

Autocompletado de shell

El autocompletado con Tab está disponible para bash, zsh, fish y PowerShell. La forma más rápida de activarlo es:

vrg --install-completion

zsh en macOS: directorios inseguros

Si ve compinit: insecure directories después de instalar los autocompletados en macOS, corrija los permisos del directorio de Homebrew:

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

Opciones globales

Opción	Corta	Descripción
--profile	-p	Perfil de configuración a usar
--host	-H	URL del host de VergeOS (anulación)
--token		Token de portador para autenticación
--api-key		Clave de API para autenticación
--username	-u	Nombre de usuario para autenticación básica
--password		Contraseña para autenticación básica
--output	-o	Formato de salida (tabla, ancho, json, csv)
--query		Extraer campo usando notación de puntos
--all-profiles		Ejecutar comandos de listado en cada perfil configurado
--verbose	-v	Aumentar nivel de detalle (-v, -vv, -vvv)
--quiet	-q	Suprimir la salida no esencial
--no-color		Deshabilitar la salida en color
--yes		Omitir los avisos de confirmación en acciones destructivas
--version	-V	Mostrar versión
--help		Mostrar ayuda

Códigos de salida

vrg usa códigos de salida significativos para scripts e integración con CI:

Código	Significado
0	Éxito
1	Error general
2	Argumentos no válidos
3	Error de configuración
4	Error de autenticación
5	Permiso denegado
6	Recurso no encontrado
7	Conflicto (p. ej., nombre duplicado)
8	Error de validación
9	Tiempo de espera agotado
10	Error de conexión

Solución de problemas

Síntoma	Causa probable	Solución
Código de salida 4	Fallo de autenticación	Ejecute vrg configure setup y verifique el token, la clave de API o las credenciales
Código de salida 3	Error de configuración	Inspeccione ~/.vrg/config.toml o ejecute vrg configure show
Código de salida 10	Error de conexión	Verificar VERGE_HOST es accesible y la URL es correcta
compinit: insecure directories (macOS)	Permisos de Homebrew	chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions
vrg bloqueado en macOS	cuarentena de Gatekeeper	xattr -d com.apple.quarantine ./vrg

Cómo elegir la herramienta adecuada

vrg es una de varias interfaces de automatización de VergeOS. Elija según cómo trabaje:

Herramienta	Úselo cuando
vrg CLI	Trabaja siempre en una terminal, quiere plantillas de VM declarativas o necesita un script puntual
Python SDK	Está escribiendo aplicaciones en Python, automatización compleja o integrando otras herramientas de Python
Módulo de PowerShell	Su entorno es principalmente Windows o ya automatiza con PowerShell
Proveedor de Terraform	Gestiona VergeOS junto con otra infraestructura administrada por Terraform
Go SDK	Está integrando la gestión de VergeOS en una aplicación Go

Recursos y soporte

• Repositorio de GitHub — código fuente, incidencias y versiones
• Referencia de comandos — cada comando y opción
• Guía de plantillas — completo .vrg.yaml referencia de campos
• Libro de recetas — recetas orientadas a tareas
• Arquitectura — diseño e internos
• Problemas conocidos — limitaciones actuales y soluciones alternativas
• Paquete de PyPI
• Informar de un problema
• Documentación de la API de VergeOS