Verge CLI

Command-line interface for VergeOS — manage virtual machines, networks, DNS, firewall rules, and more from your terminal.

Installation

pipx (recommended)

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 and place it in your PATH. Available for Linux (x86_64), macOS (ARM64), and Windows (x86_64).

macOS note: You may need to remove the quarantine attribute:

xattr -d com.apple.quarantine ./vrg

Verify

vrg --version

Quick Start

# 1. Configure credentials
vrg configure setup

# 2. Verify connection
vrg system info

# 3. List your VMs
vrg vm list

Highlights

• 200+ commands across compute, networking, tenants, NAS, identity, automation, and monitoring
• Declarative VM templates — provision from .vrg.yaml files with variables, dry-run, and batch support
• Flexible auth — interactive setup via vrg configure, bearer token, API key, or username/password with named profiles
• Flexible output — table, wide, JSON, or CSV with --query field extraction
• Shell completion — tab completion for bash, zsh, fish, and PowerShell

Commands

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

Domain	Commands
Compute	vm, vm drive, vm nic, vm device, vm snapshot
Networking	network, network rule, network dns, network host, network alias, network diag
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, configure, file, completion

Most commands follow a consistent CRUD pattern (list, get, create, update, delete). Destructive operations require --yes to skip confirmation.

Run vrg <command> --help for usage details, or see the full Command Reference.

Configuration

Configuration is stored in ~/.vrg/config.toml. Run vrg configure setup for interactive setup, or set environment variables (VERGE_HOST, VERGE_TOKEN, etc.) to override. Multiple named profiles are supported.

See the Cookbook for setup recipes and the Command Reference for all environment variables.

VM Templates

Create VMs from declarative .vrg.yaml files instead of long command lines. Templates support variables, dry-run previews, runtime overrides (--set), cloud-init, and batch provisioning.

vrg vm create -f web-server.vrg.yaml --dry-run   # Preview
vrg vm create -f web-server.vrg.yaml              # Create

See the Template Guide for the full field reference and examples.

Output Formats

All commands support --output table|wide|json|csv and --query for field extraction. See the Command Reference.

Shell Completion

Tab completion is available for bash, zsh, fish, and PowerShell. Run vrg --install-completion for quick setup, or see the Cookbook for manual configuration.

macOS zsh note: If you see compinit: insecure directories after installing completions, 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)
--output	-o	Output format (table, wide, json, csv)
--query		Extract field using dot notation
--verbose	-v	Increase verbosity (-v, -vv, -vvv)
--quiet	-q	Suppress non-essential output
--no-color		Disable colored output
--version	-V	Show version
--help		Show help

Exit Codes

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

Contributing

We welcome contributions! Please read the following before submitting a pull request.

git clone https://github.com/verge-io/vrg.git
cd vrg
uv sync --all-extras
uv run pytest              # Tests
uv run ruff check .        # Lint
uv run mypy src/verge_cli  # Type check

By submitting a pull request, you agree to the terms of our Contributor License Agreement.

• Follow the existing code style and conventions
• Add tests for new functionality
• Keep pull requests focused — one feature or fix per PR
• Use conventional commit messages

Documentation

• Command Reference — Full command reference
• Template Guide — Template language reference
• Cookbook — Task-oriented recipes
• Architecture — Design patterns and internals
• Known Issues — Current limitations and workarounds

License

Apache License 2.0 — see LICENSE for details.