vers-cli

Vers CLI

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

Installation

Quick Install (Recommended)

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

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

Manual Installation

Download prebuilt binaries from the releases page.

Usage

VMs

# Start a new VM
vers run

# List all VMs
vers status

# List just VM IDs (for scripting)
vers status -q

# Full JSON output
vers status --json

# Detailed metadata for a VM (IP, lineage, timestamps)
vers get <vm-id>
vers get --json

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

# Create a branch from a VM
vers branch <vm-id> [--count N] [--checkout]

# Pause / resume a VM
vers pause <vm-id>
vers resume <vm-id>

# Resize a VM's disk
vers resize <vm-id> --size <mib>

# Delete VMs
vers kill <vm-id>
vers kill <vm-1> <vm-2> <vm-3>
vers kill -r <vm-id>              # recursive (include children)

Commits

# Commit the current HEAD VM
vers commit

# Commit a specific VM
vers commit <vm-id>

# Commit + tag + publish in one shot
vers commit create <vm-id> --tag my-app:v1.2 --tag my-app:latest --public
# --tag <repo>:<tag>  (repeatable)  creates the tag, or updates an existing one
#                                    to point at the new commit
# --public                           publishes the new commit (is_public=true)

# List your commits
vers commit list
vers commit list -q               # just IDs
vers commit list --json
vers commit list --public         # public commits

# View commit history (parent chain)
vers commit history <commit-id>

# Make a commit public/private
vers commit publish <commit-id>
vers commit unpublish <commit-id>

# Delete commits
vers commit delete <commit-id>
vers commit delete <id-1> <id-2>

Tags

Named pointers to commits — like git tags.

# Create a tag
vers tag create <name> <commit-id>
vers tag create production abc-123 -d "stable release"

# List all tags
vers tag list
vers tag list -q                  # just names
vers tag list --json

# Get tag details
vers tag get <name>

# Move a tag to a different commit
vers tag update <name> --commit <new-id>
vers tag update <name> --description "updated desc"

# Delete tags
vers tag delete <name>
vers tag delete <name-1> <name-2>

Feedback

Report friction (or anything else) about the CLI. Entries are appended to a local JSONL journal at ~/.vers/feedback.jsonl.

# Record locally
vers feedback "the --tier flag rejects 'enterprise' but docs list it as valid"

# List recent entries
vers feedback list
vers feedback list --limit 5 --json

# Opt-in upstream delivery: when VERS_FEEDBACK_ENDPOINT is set, the entry is
# also POSTed there (application/json, 5s timeout). Failures are logged to
# stderr but the local journal entry is still written.
VERS_FEEDBACK_ENDPOINT=https://example.com/cli-feedback \
  vers feedback "race condition in --wait when job completes during first poll"

Override the journal path with VERS_FEEDBACK_PATH (primarily for testing).

Shell Composition

Commands with -q output are designed to compose with standard Unix tools:

# Kill all VMs
vers kill $(vers status -q)

# Delete all commits
vers commit delete $(vers commit list -q)

# Delete all tags
vers tag delete $(vers tag list -q)

# Get info on the first VM
vers get $(vers status -q | head -1)

# JSON piped to jq
vers status --json | jq '.[].vm_id'
vers get <vm-id> --json | jq '.ip'

ps is an alias for status:

vers ps -q

Job Ledger

Every --wait invocation of run, branch, deploy, resume, or run-commit appends an entry to a durable JSONL ledger at ~/.vers/jobs.jsonl (override with VERS_JOBS_DIR). Use vers jobs to introspect:

vers jobs list --json                     # all jobs as JSON
vers jobs list --status failed            # only failed jobs
vers jobs get job_<id>                    # full record for one job
vers jobs prune --older-than 7d           # trim entries older than 7 days
vers jobs prune --all --dry-run           # preview clearing the ledger

Phase 1 ships journaling only. The ledger is written best-effort: a write failure never causes the underlying command to fail. Resumption of in-flight jobs is not yet implemented.

Configuration

Vers CLI uses a vers.toml configuration file to define your environment.

[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"

Development

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 for examples.

Building

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

This repository uses Air for hot reloading during development:

air status

Testing

Unit tests:

make test        # or: make test-unit

Integration tests (require VERS_URL and VERS_API_KEY):

VERS_URL=https://... VERS_API_KEY=... make test-integration

# Run a specific test
VERS_URL=... VERS_API_KEY=... make test-integration ARGS='-run TagLifecycle -v'

MCP Server (experimental)

Built-in MCP server to expose Vers operations as tools for agent clients (Claude Desktop/Code, etc.).

# stdio transport (local agents)
VERS_URL=https://<url> VERS_API_KEY=<token> vers mcp serve --transport stdio

# HTTP/SSE transport
VERS_MCP_HTTP_TOKEN=<secret> VERS_URL=... VERS_API_KEY=... vers mcp serve --transport http --addr :3920

Tools: vers.status, vers.run, vers.execute, vers.branch, vers.kill, vers.version, vers.capabilities

Resources: vers://status