> 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/es/integraciones-y-api/vrg-cli.md).

# CLI de VergeOS (vrg)

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

```bash
pipx install vrg
```

### pip

```bash
pip install vrg
```

### uv

```bash
uv tool install vrg
```

### Homebrew

```bash
brew install verge-io/tap/vrg
```

### Binario independiente

Descargue un binario precompilado desde la [última versión](https://github.com/verge-io/vrg/releases/latest) , luego colóquelo en su `PATH`. Los binarios están disponibles para Linux (x86\_64), macOS (ARM64) y Windows (x86\_64).

{% hint style="warning" %}
**Cuarentena de macOS**

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

```bash
xattr -d com.apple.quarantine ./vrg
```

{% endhint %}

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

```bash
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](https://github.com/verge-io/vrg/releases/latest) |

## Inicio rápido

```bash
# 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](#authentication) 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:

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

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

```bash
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
```

{% hint style="success" %}
**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.
{% endhint %}

## 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`, `update`y `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](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) .

## Ejemplos de uso

### Listado e inspección de VMs

```bash
# 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](#vm-templates).

```bash
# 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
```

{% hint style="info" %}
**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.
{% endhint %}

### Trabajar con redes

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

```bash
# 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

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

```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

```bash
# 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
```

{% hint style="success" %}
**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.
{% endhint %}

Para la referencia completa de los campos de la plantilla, consulte la [Guía de plantillas](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) .

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

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

```bash
vrg --install-completion
```

{% hint style="warning" %}
**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:

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

{% endhint %}

## 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](/automate-protect-and-extend/es/integraciones-y-api/python-sdk.md)                     | Está escribiendo aplicaciones en Python, automatización compleja o integrando otras herramientas de Python |
| [Módulo de PowerShell](/automate-protect-and-extend/es/integraciones-y-api/powershell-module.md)    | Su entorno es principalmente Windows o ya automatiza con PowerShell                                        |
| [Proveedor de Terraform](/automate-protect-and-extend/es/integraciones-y-api/terraform-provider.md) | Gestiona VergeOS junto con otra infraestructura administrada por Terraform                                 |
| [Go SDK](/automate-protect-and-extend/es/integraciones-y-api/go-sdk.md)                             | Está integrando la gestión de VergeOS en una aplicación Go                                                 |

## Recursos y soporte

* [Repositorio de GitHub](https://github.com/verge-io/vrg) — código fuente, incidencias y versiones
* [Referencia de comandos](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) — cada comando y opción
* [Guía de plantillas](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) — completo `.vrg.yaml` referencia de campos
* [Libro de recetas](https://github.com/verge-io/vrg/blob/main/docs/COOKBOOK.md) — recetas orientadas a tareas
* [Arquitectura](https://github.com/verge-io/vrg/blob/main/docs/ARCHITECTURE.md) — diseño e internos
* [Problemas conocidos](https://github.com/verge-io/vrg/blob/main/docs/KNOWN_ISSUES.md) — limitaciones actuales y soluciones alternativas
* [Paquete de PyPI](https://pypi.org/project/vrg/)
* [Informar de un problema](https://github.com/verge-io/vrg/issues)
* [Documentación de la API de VergeOS](/knowledge-base/es/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/es/integraciones-y-api/vrg-cli.md?ask=<question>&goal=<endgoal>
```

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