Vers CLI

A command-line interface for managing virtual machine/container-based development environments.

Development

Thin Command Architecture

Commands under cmd/ are intentionally thin: they parse flags/args and delegate to handlers in internal/handlers/, which coordinate services in internal/services/ and render results via internal/presenters/. A shared App container (in internal/app/) wires common deps (SDK client, IO, prompter, exec runner, timeouts) in cmd/root.go.

When adding a new command:

• Add a handler internal/handlers/<command>.go with Handle(ctx, app, Req) (View, error).
• Add a presenter internal/presenters/<command>_presenter.go to render View.
• Keep the Cobra file minimal: parse → build Req → call handler → render.

SDK Requests

If a request field needs a param.Field[T], wrap with vers.F(value). See the Go SDK Readme and existing handlers (e.g., run/run-commit/rename) for examples.

Features

• Environment Management: Start environments with run command
• State Inspection: Check environment status
• Command Execution: Run commands within environments
• Branching: Create branches from existing environments

Installation

Quick Install (Recommended)

Install the latest version using our installation script:

curl -fsSL https://raw.githubusercontent.com/hdresearch/vers-cli/main/install.sh | sh

This script will:

• Detect your OS and architecture automatically
• Download the appropriate prebuilt binary
• Verify the checksum for security
• Install to ~/.local/bin (or use INSTALL_DIR to customize)
• Make the binary executable

Custom installation directory:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/hdresearch/vers-cli/main/install.sh | sh

Install a specific version:

VERS_VERSION=v0.5.0 curl -fsSL https://raw.githubusercontent.com/hdresearch/vers-cli/main/install.sh | sh

Install from Source

If you have Go installed, you can build from source:

go install github.com/hdresearch/vers-cli/cmd/vers@latest

Manual Installation

Download prebuilt binaries from the releases page.

Usage

Available Commands

# Check the status of all VMs
vers status

# Check the status of a specific VM
vers status <vm-id>

# Start a development environment (creates a new VM)
vers run

# Execute a command on a VM
vers execute <vm-id> <command> [args...]

# Create a new branch from a VM
vers branch <vm-id>

Configuration

Vers CLI uses a vers.toml configuration file to define your environment. The file should be created manually and can be customized for your specific needs.

Example:

[meta]
project = "myapp"
type = "python"

[build]
builder = "docker"
build_command = "pip install -r requirements.txt"

[run]
command = "python main.py"

[env]
DATABASE_URL = "postgres://localhost:5432/mydb"

UI (experimental)

The vers ui command launches an interactive TUI that is currently EXPERIMENTAL. It may change or break; not recommended for production use. Expect rough edges and please report issues.

Development

To build the binary locally, run:

go build -o bin/vers ./cmd/vers

This repository uses Air for development with hot reloading. You can run

air

which will take the place of running the binary. So to develop on e.g. vers status you would run

air status

Testing

• Unit tests (includes MCP tests):

  make test        # or: make test-unit

• Integration tests (require env: VERS_URL, VERS_API_KEY):

  VERS_URL=https://... VERS_API_KEY=... make test-integration
  # Optional args passthrough
  VERS_URL=... VERS_API_KEY=... make test-integration ARGS='-run Copy -v'

MCP Server (built-in, experimental)

This repo includes an MCP server to expose Vers operations as tools and resources for agent clients (Claude Desktop/Code, etc.).

• Build:
  • make build (MCP server is included in the binary)
• Run (stdio transport for local agents):
  • VERS_URL=https://<vers-url> VERS_API_KEY=<token> ./bin/vers mcp serve --transport stdio
• Run over HTTP/SSE (for MCP connector):
  • export VERS_MCP_HTTP_TOKEN=<secret> (optional but recommended)
  • VERS_URL=... VERS_API_KEY=... ./bin/vers mcp serve --transport http --addr :3920
  • curl http://localhost:3920/healthz → ok

Tools exposed

• vers.status — snapshot of VMs (inputs: target?)
• vers.run — start a VM (inputs: memSizeMib?, vcpuCount?, rootfsName?, kernelName?, fsSizeVmMib?, vmAlias?)
• vers.execute — run a command in a VM (inputs: target?, command [required], timeoutSeconds?)
• vers.branch — create a VM from existing/HEAD (inputs: target?, alias?, checkout?)
• vers.kill — delete VMs (inputs: targets?, skipConfirmation [required], recursive?)
• vers.version — server info (no backend calls)
• vers.capabilities — server settings/tool list

Resources

• vers://status — global status as JSON

Notes

• Execute streams stdout/stderr via MCP logging messages; final summary + structured output returned.
• Destructive tools require skipConfirmation=true in MCP mode.
• Basic rate limits per minute are enforced per tool; hitting limits returns a coded MCP error.