Skip to content

VergeOS CLI (vrg)#

Overview#

vrg is the official command-line interface for VergeOS. It provides 200+ commands across compute, networking, tenants, NAS, identity, automation, and monitoring, plus declarative .vrg.yaml VM templates for reproducible, version-controlled provisioning. Use it for terminal-first administration, shell scripting, and CI/CD pipelines.

Requirements#

  • Python 3.10 or later (when installing via pip, pipx, or uv)
  • A user account or API key with appropriate permissions on the VergeOS instance

Installation#

vrg can be installed several ways. pipx is recommended because it isolates the CLI in its own virtual environment.

pipx install vrg

pip#

pip install vrg

uv#

uv tool install vrg

Homebrew#

brew install verge-io/tap/vrg

Standalone Binary#

Download a pre-built binary from the latest release, then place it on your PATH. Binaries are available for Linux (x86_64), macOS (ARM64), and Windows (x86_64).

macOS Quarantine

On macOS, the standalone binary may be quarantined by Gatekeeper. Remove the attribute before running:

xattr -d com.apple.quarantine ./vrg

After installation, verify with:

vrg --version

Upgrading#

Install Method Upgrade Command
pipx pipx upgrade vrg
pip pip install --upgrade vrg
uv uv tool upgrade vrg
Homebrew brew upgrade vrg
Standalone Re-download from the releases page

Quick Start#

# 1. Configure credentials (interactive wizard)
vrg configure setup

# 2. Verify the connection
vrg system info

# 3. Discover commands as you go — every command supports --help
vrg --help
vrg vm --help

# 4. List your VMs
vrg vm list

vrg configure setup is an interactive wizard that prompts for the host URL, authentication method, and default output format. It saves the result to ~/.vrg/config.toml. See Authentication for the details on each method and how to script credentials.

Authentication#

vrg accepts four authentication methods. All four can be supplied through the interactive wizard, environment variables, command-line flags, or a profile in ~/.vrg/config.toml.

Method Best For How to Provide
Bearer token CI pipelines, scripts --token flag or VERGE_TOKEN env var
API key Long-lived service automation --api-key flag
Username + password Interactive sessions, one-offs --username / --password or wizard prompts
Profile Multiple instances --profile <name> after running vrg configure setup

Generating an API Key#

API keys are managed both in the VergeOS UI (System → API Keys) and through the CLI itself once you've authenticated by another method:

# After your first interactive login, mint a long-lived key for CI
vrg api-key create --name ci-pipeline
vrg api-key list

Treat the returned value as a secret — store it in your CI provider's secret manager, never in source control.

Environment Variables#

Environment variables override values in the config file, which makes them ideal for CI/CD:

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

Profiles#

Profiles let you switch between multiple VergeOS instances (production, staging, customer environments):

vrg configure setup --profile prod   # Set up a named profile
vrg configure list                   # List configured profiles
vrg configure show                   # Show active profile (credentials masked)
vrg --profile prod vm list           # Use a specific profile for one command
vrg -p staging vm list               # Short form

Cross-Profile Queries

Use --all-profiles on a list command to run it against every configured profile. Each output row includes a profile column showing where it came from.

Command Pattern#

All vrg commands follow a consistent structure:

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

Most resources implement standard CRUD actions: list, get, create, update, and delete. Destructive operations require --yes to skip the confirmation prompt.

Command Domains#

Domain Sub-domains
Compute vm, vm drive, vm nic, vm device, vm snapshot, vm export, vm import
Networking network, network rule, network dns, network host, network alias, network diag, network query
Tenants 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
Infrastructure cluster, node, storage
Snapshots snapshot, snapshot profile
Sites & Replication site, site sync outgoing, site sync incoming
Identity & Access user, group, permission, api-key, auth-source
Certificates & SSO certificate, oidc
Automation task, task schedule, task trigger, task event, task script
Recipes recipe, recipe section, recipe question, recipe instance, recipe log
Catalog catalog, catalog repo
Updates update, update source, update branch, update package, update available
Monitoring alarm, alarm history, log
Tagging tag, tag category, resource-group
System system, system settings, system license, system diag, doctor, configure, file, completion

The complete reference is maintained in the Command Reference.

Usage Examples#

Listing and Inspecting VMs#

# List all VMs
vrg vm list

# Inspect a single VM
vrg vm get web-server

# Power state
vrg vm start web-server --wait    # --wait blocks until the VM is running
vrg vm stop web-server --wait
vrg vm restart web-server

Building a VM from Shell Flags#

The shell-flag approach is good for quick experiments. For repeatable provisioning, see VM Templates.

# Create a VM (--ram is in MB)
vrg vm create --name web-server --ram 4096 --cpu 2

# Add a 50 GB disk and attach a NIC
vrg vm drive create web-server --size 50GB --name os-disk
vrg vm nic create web-server --network External

# Start the VM
vrg vm start web-server --wait

Empty VMs Don't Boot

A VM created from shell flags has no operating system attached. To install one, either boot from an ISO drive (vrg vm drive create … --media cdrom), clone an existing VM (vrg vm clone), or define an OS image and cloud-init in a .vrg.yaml template.

Working with Networks#

# Create an internal network with DHCP
vrg network create --name dev-net --cidr 10.0.0.0/24 --ip 10.0.0.1 --dhcp
vrg network start dev-net

# Allow incoming SSH (--dest-ports accepts a single port, range "80-443", or "80,443")
vrg network rule create dev-net \
  --name allow-ssh --action accept --direction incoming \
  --protocol tcp --dest-ports 22

# Apply pending firewall changes
vrg network apply-rules dev-net

Network and Node Diagnostics#

vrg exposes diagnostic queries that run on a network's virtual router or directly on a physical node:

# Network connectivity tests
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

# Node hardware checks
vrg node query smartctl node1 /dev/sda
vrg node query ipmi-sensor node1
vrg node lldp list node1

System Health Check#

# Run all built-in health checks
vrg doctor

# Run a specific subset
vrg doctor --check connectivity,clusters,nodes,storage

# JSON output for automation; exit code 0 = healthy, 1 = failures
vrg -o json doctor | jq '.[] | select(.status == "fail")'

VM Templates#

Define VMs as .vrg.yaml files for repeatable, version-controlled provisioning. Templates support variables, dry-run previews, runtime overrides via --set, cloud-init, and batch creation with VirtualMachineSet.

Example Template#

Save the following as 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

Validating and Creating#

# Validate the template against the schema
vrg vm validate -f web-server.vrg.yaml

# Preview the operation without making changes
vrg vm create -f web-server.vrg.yaml --dry-run

# Create the VM
vrg vm create -f web-server.vrg.yaml

# Override a field at runtime
vrg vm create -f web-server.vrg.yaml \
  --set vm.name=web-server-02 --set vm.ram=16GB

Variables and Defaults

Templates support ${VAR} substitution from environment variables or a vars: block, plus default-value syntax (${VM_RAM:-4GB}). This is useful for parameterizing a single template across environments.

For the complete template field reference, see the Template Guide.

Output Formats#

All commands support --output (or -o) for changing the output format and --query for extracting a field with dot notation.

Format Use Case
table Default human-readable output
wide All available columns, including those hidden from the default view
json Machine-readable output for piping to jq or other tools
csv Spreadsheet-friendly export 
# All columns
vrg -o wide vm list

# JSON for scripting
vrg -o json vm list | jq '.[].name'

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

# Extract a single field with dot notation (supports nested paths)
vrg --query status vm get web-server
vrg --query nics[0].network vm get web-server

Shell Completion#

Tab completion is available for bash, zsh, fish, and PowerShell. The fastest way to enable it is:

vrg --install-completion

macOS zsh: insecure directories

If you see compinit: insecure directories after installing completions on macOS, fix the Homebrew directory permissions:

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

Global Options#

Option Short Description
--profile -p Configuration profile to use
--host -H VergeOS host URL (override)
--token Bearer token for authentication
--api-key API key for authentication
--username -u Username for basic auth
--password Password for basic auth
--output -o Output format (table, wide, json, csv)
--query Extract field using dot notation
--all-profiles Run list commands across every configured profile
--verbose -v Increase verbosity (-v, -vv, -vvv)
--quiet -q Suppress non-essential output
--no-color Disable colored output
--yes Skip confirmation prompts on destructive actions
--version -V Show version
--help Show help

Exit Codes#

vrg uses meaningful exit codes for scripting and CI integration:

Code Meaning
0 Success
1 General error
2 Invalid arguments
3 Configuration error
4 Authentication error
5 Permission denied
6 Resource not found
7 Conflict (e.g., duplicate name)
8 Validation error
9 Timeout
10 Connection error

Troubleshooting#

Symptom Likely Cause Fix
Exit code 4 Authentication failure Run vrg configure setup and verify the token, API key, or credentials
Exit code 3 Configuration error Inspect ~/.vrg/config.toml or run vrg configure show
Exit code 10 Connection error Verify VERGE_HOST is reachable and the URL is correct
compinit: insecure directories (macOS) Homebrew permissions chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions
vrg blocked on macOS Gatekeeper quarantine xattr -d com.apple.quarantine ./vrg

Choosing the Right Tool#

vrg is one of several VergeOS automation interfaces. Pick based on how you work:

Tool Use When
vrg CLI You live in a terminal, want declarative VM templates, or need a one-shot script
Python SDK You're writing Python applications, complex automation, or integrating with other Python tooling
PowerShell Module You're a Windows-first shop or already automate with PowerShell
Terraform Provider You manage VergeOS alongside other Terraform-managed infrastructure
Go SDK You're embedding VergeOS management into a Go application

Resources & Support#