Introducing govcai: An Open Source AI-Optimized Wrapper for VMware govc

We talked about the theory. Now here’s the tool. govcai is an open source CLI wrapper that makes govc output LLM-ready: with 300x smaller responses, built-in safety gates, and zero changes to your vCenter workflow.

TL;DR (govcai wraps VMware’s govc CLI and transforms its verbose JSON into compact, LLM-optimized markdown. Drop it in, point it at your vCenter, and your AI agents get up to 4,760x smaller responses, 98.6% extraction accuracy (vs 42.2% with raw govc), and built-in safety gates that prevent accidental vm destroy. Same govc under the hood, same env vars) just smarter output. Open source, Apache 2.0. github.com/vchaindz/govcai

Why govcai?#

If you’re running LLM agents against VMware infrastructure today, you’re burning tokens and getting unreliable results. Raw govc output wasn’t designed for AI consumption, and it shows. govcai fixes that with a single wrapper, no vCenter changes, no new APIs.

In our previous post, we laid out five principles for making CLI tools work efficiently with LLM agents: structured output by default, response shaping, noun-verb command structure, deterministic error contracts, and built-in discovery. The response was clear: infrastructure teams want this, but they want working code, not just a blueprint.

Today we’re releasing govcai, an open source project that implements all five principles as a drop-in wrapper around VMware’s govc. It’s written in Go, requires zero changes to your vCenter environment, and works everywhere govc does.

What govcai Actually Does#

govcai sits between your LLM agent and govc. It runs the same govc commands against your vCenter, but intercepts the response and transforms it from verbose JSON into compact, structured markdown that an LLM can actually consume without burning through its context window.

There’s no new API to learn. If you know govc, you know govcai. Same environment variables (GOVC_URL, GOVC_USERNAME, GOVC_PASSWORD), same vCenter connection, same authentication. The difference is what comes back.

The Numbers: Before and After#

Here’s what the optimization looks like on a real vCenter environment with 41 VMs, 4 datastores, and 2 clusters.

Output Size Reduction#

Output Size Reduction#

The headline number, 316x reduction on VM listing, comes from extracting the 11 fields an agent actually needs from the 200+ fields govc returns per VM. But the real story is what this enables: an LLM agent can now hold an entire 41-VM inventory in ~1,400 tokens instead of ~427,000.

Real-World LLM Cost Impact#

We ran end-to-end benchmarks with Claude Code (Sonnet) against a production vCenter. Each task was executed 3 times to measure consistency.

Single-command tasks consistently complete in 2 tool-call turns with govcai versus 3 with govc. The third turn disappears because govcai returns pre-formatted markdown, Claude doesn’t need an extra round-trip to parse JSON and render a table.

LLM Accuracy#

Compact, structured output doesn’t just save tokens, it makes the LLM more accurate.

With govc, the LLM has to navigate 3-5 hops through nested JSON objects to find the answer. With govcai, the answer is 0-1 hops from the surface. Less noise, fewer extraction errors.

The Five Principles, Implemented#

Here’s how govcai maps to the design principles from the original blog post:

1. Structured Output by Default#

govcai outputs markdown tables by default, not because markdown is magic, but because it’s the format LLMs handle best. Tables compress naturally, column headers provide context, and the whole thing fits in a fraction of the tokens.

# govc: 1.7 MB of nested JSON govc vm.info -json

# govcai: 5.4 KB markdown table with the fields that matter govcai vm list

Need the raw JSON? --format raw passes through govc’s output untouched. Need JSON for scripting? --format json gives you govcai’s filtered result as JSON.

2. Response Shaping with Views and Fields#

This is where the biggest token savings come from. Instead of returning everything, govcai offers pre-built views that match common agent intents:

govcai vm info web-01 --view perf # CPU%, memory%, uptime govcai vm info web-01 --view config # CPU count, memory, disk, network govcai vm info web-01 --view status # Power, tools, IP, guest OS

govcai host info esxi-01 --view perf # CPU/memory utilization govcai host info esxi-01 --view config # Hardware specs

For maximum control, --fields lets you specify exactly which columns you want, and --token-budget caps the total output size.

3. Noun-Verb Command Structure#

Every command follows govcai <noun> <verb>: predictable enough that an LLM can infer commands it hasn’t seen:

govcai ├── vm (list, info, status, power-on, power-off, create, destroy, …) ├── host (list, info, status, performance, maintenance-enter, …) ├── datastore (list, info, usage, ls, rm, …) ├── cluster (summary, capacity, rule-list, host-list, …) ├── snapshot (tree, create, remove, revert, removeall) ├── metric (list, info, sample, interval-info, …) ├── tags (list, info, create, attach, detach, …) ├── disk (list, create, attach, detach, …) ├── role (list, usage, create, update, remove) ├── permissions (list, set, remove) ├── alarm (list, info) ├── license (list, info, assigned-list, add, …) ├── library (list, info, item-list, deploy, …) └── … (19 categories, 164 commands total)

4. Deterministic Error Contracts#

Every error is JSON with a machine-readable code, a target, and a retry hint. No stack traces, no ambiguous English paragraphs:

{"error": true, "code": "APPROVAL_REQUIRED", "message": "This operation requires --approve", "target": "vm.destroy", "retry": false}

The error codes (AUTH_FAILED, VM_NOT_FOUND, TIMEOUT, APPROVAL_REQUIRED, etc.) map directly to recovery actions. An agent can build retry logic without parsing natural language.

5. Built-in Discovery#

LLM agents shouldn’t need to read man pages. govcai provides three levels of self-documentation:

govcai --help-compact # ~576 tokens for all 164 commands govcai vm info --schema # JSON schema: args, views, risk level govcai --discover # Complete JSON schema dump

--help-compact gives roughly 16 tokens per command, compared to ~200 tokens for a typical man page entry. An agent can scan the entire command surface in a single tool call.

Safety: The Feature That Matters Most#

When you let an LLM agent run infrastructure commands, the risk profile changes fundamentally. A human reads vm destroy and thinks twice. An LLM might not.

govcai classifies every command by risk level:

Without --approve, any mutating or destructive command returns a structured error:

{"error": true, "code": "APPROVAL_REQUIRED", "message": "This operation requires --approve", "target": "vm.destroy", "retry": false}

This gives the LLM agent (or its orchestrator) a clear decision point: escalate to a human, or proceed with explicit approval. No accidental deletions.

Workflows and Bundles: Multi-Step Operations#

Real infrastructure tasks rarely involve a single command. govcai supports two patterns for multi-step operations:

Bundles aggregate related read-only commands into a single call:

govcai bundle cluster-status # system about + cluster summary + host list govcai bundle vm-health # vm list + system about govcai bundle full-inventory # complete infrastructure scan

Workflows are YAML-defined pipelines that can include variables, conditionals, and dry-run previews:

name: vm-health-check description: Comprehensive VM health assessment risk_level: low steps: - id: list-vms task: vm.list view: summary - id: system-info task: system.about

govcai workflow workflows/vm-health-check.yaml govcai workflow workflows/vm-health-check.yaml --dry-run # preview without executing

Coverage: Intentional, Not Incomplete#

govcai covers 164 of govc’s ~412 commands across 19 categories. Thirteen categories have 100% coverage.

The gap is intentional. Uncovered commands fall into four buckets: niche admin operations (SSO, VCSA appliance management), interactive commands (VM console, VNC), and high-privilege operations that shouldn’t be casually accessible to AI agents or its work in progress.

Every command govcai does expose has a purpose-built handler that converts verbose JSON into compact markdown, adding commands without proper handling would just pass through raw JSON and defeat the purpose.

Getting Started#

# Build from source git clone https://github.com/vchaindz/govcai.git cd govcai go build -o govcai ./cmd/govcai/

# Ensure govc is installed brew install govc # or download from github.com/vmware/govmomi/releases

# Configure vCenter connection (same as govc) export GOVC_URL=https://vcenter.example.com export GOVC_USERNAME=administrator@vsphere.local export GOVC_PASSWORD=secret export GOVC_INSECURE=true # GOVC_DATACENTER is auto-detected and cached for 24h

# Try it govcai system about govcai vm list govcai host list --view config govcai datastore usage govcai --help-compact

govcai auto-detects your datacenter when GOVC_DATACENTER isn’t set. If there’s exactly one, it’s used automatically. If there are multiple, govcai tells you which ones are available and asks you to specify.

What’s Next#

govcai is open source under the Apache 2.0 license. The immediate roadmap includes expanding coverage for content libraries (library.create, library.sync), adding OVF import/export support, and building more workflow templates for common operational patterns.

But the bigger goal is demonstrating a pattern. The principles behind govcai (response shaping, risk gates, deterministic errors, built-in discovery) aren’t VMware-specific. They apply to any CLI tool you want to make LLM-ready. We started with govc because it’s the CLI tool we know best, but the architecture is designed to be a reference for wrapping kubectl, terraform, esxcli, or any other infrastructure CLI.

If you’re building AI-driven infrastructure automation, we’d love your feedback. Try it, file issues, contribute new task handlers.

The project is at github.com/vchaindz/govcai.