Verge CLI

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

Claude Code deploying an internal network and VM with vrg

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]

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

AI Agent Skill

This repo ships an agent skill that teaches AI coding agents (Claude Code, Codex) how to drive vrg — command patterns, domain reference, recipes, and VM templates.

Claude Code

Copy the skill into your personal skills directory:

cp -R skills/vrg ~/.claude/skills/vrg

Or into a single project to share it with your team:

cp -R skills/vrg /path/to/project/.claude/skills/vrg

Claude Code picks it up automatically; ask it anything VergeOS-related ("list my VMs", "create a firewall rule") and it will use vrg.

Codex

Codex uses the same SKILL.md format, loaded from .agents/skills. Copy into your user-level skills directory:

cp -R skills/vrg ~/.agents/skills/vrg

Or into a project to share it with your team:

cp -R skills/vrg /path/to/project/.agents/skills/vrg

Codex detects skill changes automatically; if it doesn't appear, restart Codex.

Both agents need vrg installed and configured (vrg configure setup) to actually run commands.

Global Options

Exit Codes

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

License

Apache License 2.0 — see LICENSE for details.