Feat/agent mode and mcp

.gitignore

@@ -3,6 +3,10 @@ bin/
 _output/
 verda
 
+# Git worktrees
+.worktrees/
+
+
 # Local smoke-test output (see test/run.sh)
 tmp/
 
@@ -240,6 +244,8 @@ cscope.po.out
 
 # Other names that would make sense
 *tests
+!tests/
+!tests/**
 *testsdir
 *testsfile
 *testsfiles

Makefile

@@ -1,6 +1,6 @@
 OUTPUT_DIR ?= bin
 
-.PHONY: all build clean lint lint.fix test fmt changelog hooks.install pre-commit help
+.PHONY: all build clean lint lint.fix test test.integration fmt changelog hooks.install pre-commit help
 
 ## Build -------------------------------------------------------------------
 
@@ -25,6 +25,10 @@ lint.fix: ## Run golangci-lint with auto-fix
 test: ## Run all tests
 	@go test -count=1 ./...
 
+test.integration: build ## Run integration tests (requires staging credentials in [test] profile)
+	@cp $(OUTPUT_DIR)/verda /usr/local/bin/verda-test
+	@VERDA_BIN=$(CURDIR)/$(OUTPUT_DIR)/verda go test -tags=integration -v -count=1 -timeout=5m ./tests/integration/
+
 fmt: ## Format code with gofmt and goimports
 	@gofmt -w .
 	@goimports -w -local github/verda-cloud/verda-cli .

README.md

@@ -2,6 +2,10 @@
 
 Command-line interface for [Verda Cloud](https://verda.com) — manage VMs, volumes, SSH keys, startup scripts, and more from your terminal.
 
+![verda vm create](docs/images/vm-create-demo.gif)
+
+Both interactive and non-interactive modes — use the wizard for quick tasks, flags for scripts and automation.
+
 ## Install
 
 ### Quick install (macOS / Linux)
@@ -16,56 +20,36 @@ Install to a custom directory:
 VERDA_INSTALL_DIR=~/.local/bin curl -sSL https://raw.githubusercontent.com/verda-cloud/verda-cli/main/scripts/install.sh | sh
 ```
 
-Install a specific version:
-
-```bash
-VERDA_VERSION=v1.0.0 curl -sSL https://raw.githubusercontent.com/verda-cloud/verda-cli/main/scripts/install.sh | sh
-```
-
 ### Manual download
 
 Download the binary for your platform from [GitHub Releases](https://github.com/verda-cloud/verda-cli/releases):
 
-
-| Platform              | File                                |
-| --------------------- | ----------------------------------- |
+| Platform | File |
+|----------|------|
 | macOS (Apple Silicon) | `verda_VERSION_darwin_arm64.tar.gz` |
-| macOS (Intel)         | `verda_VERSION_darwin_amd64.tar.gz` |
-| Linux (x86_64)        | `verda_VERSION_linux_amd64.tar.gz`  |
-| Linux (ARM64)         | `verda_VERSION_linux_arm64.tar.gz`  |
-| Windows (x86_64)      | `verda_VERSION_windows_amd64.zip`   |
-| Windows (ARM64)       | `verda_VERSION_windows_arm64.zip`   |
-
-
-Extract and move to your PATH:
+| macOS (Intel) | `verda_VERSION_darwin_amd64.tar.gz` |
+| Linux (x86_64) | `verda_VERSION_linux_amd64.tar.gz` |
+| Linux (ARM64) | `verda_VERSION_linux_arm64.tar.gz` |
+| Windows (x86_64) | `verda_VERSION_windows_amd64.zip` |
+| Windows (ARM64) | `verda_VERSION_windows_arm64.zip` |
 
 ```bash
 tar xzf verda_*.tar.gz
 sudo mv verda /usr/local/bin/
 ```
 
-### Go install (for Go developers)
+### Go install
 
 ```bash
 go install github.com/verda-cloud/verda-cli/cmd/verda@latest
 ```
 
-### Verify installation
-
-```bash
-verda version
-```
-
-### Update to latest version
-
-```bash
-verda update
-```
-
-Or install a specific version:
+### Verify & update
 
 ```bash
-verda update --version v1.0.0
+verda version            # verify installation
+verda update             # update to latest
+verda update --version v1.0.0  # specific version
 ```
 
 ## Getting Started
@@ -76,17 +60,15 @@ verda update --version v1.0.0
 verda auth login
 ```
 
-This starts an interactive wizard to save your API credentials to `~/.verda/credentials`.
-
-### 2. List your VMs
+### 2. Explore available resources
 
 ```bash
-verda vm list
+verda locations                        # datacenter locations
+verda instance-types --gpu             # GPU instance types with pricing
+verda availability --location FIN-01   # what's in stock
 ```
 
-### 3. Create a VM
-
-![verda vm create](docs/images/vm-create-demo.gif)
+### 3. Deploy a VM
 
 ```bash
 # Interactive wizard
@@ -102,202 +84,66 @@ verda vm create \
   --hostname gpu-runner
 ```
 
-## Commands
-
-```
-Auth Commands:
-  auth              Manage shared credentials and profiles
-
-VM Commands:
-  vm                Manage VM instances
-  ssh               SSH into a running VM instance
-
-Resource Commands:
-  availability      Check instance type availability
-  images            List available OS images
-  instance-types    List instance types with specs and pricing
-  locations         List datacenter locations
-  ssh-key           Manage SSH keys
-  startup-script    Manage startup scripts
-  volume            Manage volumes
-
-Info Commands:
-  cost              Cost estimation, pricing, and billing
-
-Other Commands:
-  completion        Generate shell completion scripts
-  settings          Manage CLI settings
-  update            Update Verda CLI to latest or specific version
-  version           Print version information
-```
-
-### VM
-
-
-| Command              | Description                                |
-| -------------------- | ------------------------------------------ |
-| `verda vm create`    | Create a VM (interactive wizard or flags)  |
-| `verda vm list`      | List and inspect VM instances              |
-| `verda vm describe`  | Show detailed info about a single VM       |
-| `verda vm action`    | Start, shutdown, hibernate, or delete a VM |
-
-
-### SSH
+### 4. Connect
 
 ```bash
-# Connect by hostname
 verda ssh gpu-runner
-
-# Connect with options
-verda ssh gpu-runner --user ubuntu --key ~/.ssh/id_ed25519
-
-# Port forwarding and other ssh args
-verda ssh gpu-runner -- -L 8080:localhost:8080
-```
-
-### Volume
-
-
-| Command                 | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| `verda volume create`   | Create a block storage volume                |
-| `verda volume list`     | List volumes                                 |
-| `verda volume describe` | Show detailed info about a single volume     |
-| `verda volume action`   | Detach, rename, resize, clone, or delete     |
-| `verda volume trash`    | List deleted volumes (restorable within 96h) |
-
-
-### Instance Types, Images, Locations & Availability
-
-```bash
-# Browse instance types with specs and pricing
-verda instance-types
-verda instance-types --gpu             # GPU only
-verda instance-types --cpu             # CPU only
-verda instance-types --spot            # spot pricing
-
-# List all OS images
-verda images
-verda images --type 1V100.6V          # compatible with instance type
-verda images --category ubuntu         # filter by category
-
-# List datacenter locations
-verda locations
-
-# Check capacity
-verda availability                     # full matrix
-verda availability --location FIN-01   # specific location
-verda availability --type 1V100.6V     # specific type
-verda availability --spot              # spot only
 ```
 
-### Cost & Billing
+## AI Agent Integration (MCP) — Beta
 
-```bash
-# Estimate costs before creating
-verda cost estimate --type 1V100.6V --os-volume 100 --storage 500
-verda cost estimate --type 1V100.6V --spot
+The Verda CLI includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets AI agents (Claude Code, Cursor, etc.) manage your infrastructure through natural language. This feature is in **beta** — feedback welcome.
 
-# See what your running instances are costing you
-verda cost running
+### Setup
 
-# Account balance
-verda cost balance
+```json
+{
+  "mcpServers": {
+    "verda": {
+      "command": "verda",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
 ```
 
-### SSH Keys & Startup Scripts
-
-
-| Command                                    | Description            |
-| ------------------------------------------ | ---------------------- |
-| `verda ssh-key list / add / delete`        | Manage SSH keys        |
-| `verda startup-script list / add / delete` | Manage startup scripts |
-
-
-### Settings
-
-
-| Command                         | Description                    |
-| ------------------------------- | ------------------------------ |
-| `verda settings theme`          | View or change the color theme |
-| `verda settings theme --select` | Interactive theme picker       |
-
-
-Available themes: `default`, `dracula`, `catppuccin`, `catppuccin-latte`, `nord`, `tokyonight`, `github-light`, `solarized-light`
-
-### Update
-
-
-| Command                         | Description                                       |
-| ------------------------------- | ------------------------------------------------- |
-| `verda update`                  | Update to the latest version                      |
-| `verda update --version v1.0.0` | Install a specific version (upgrade or downgrade) |
-| `verda update --list`           | List available versions                           |
+Add this to your agent's MCP config:
 
+| Agent | Config file |
+|-------|------------|
+| Claude Code | `.mcp.json` in project root |
+| Cursor | `~/.cursor/mcp.json` |
 
-### Auth
+### Usage
 
+Once configured, just talk to your agent:
 
-| Command                  | Description                               |
-| ------------------------ | ----------------------------------------- |
-| `verda auth login`       | Save API credentials (interactive wizard) |
-| `verda auth show`        | Show active profile and credentials path  |
-| `verda auth use PROFILE` | Switch active auth profile                |
-
-
-### Shell Completion
-
-```bash
-# Bash
-source <(verda completion bash)
-
-# Zsh (add to ~/.zshrc or run once)
-verda completion zsh > "${fpath[1]}/_verda"
-
-# Fish
-verda completion fish | source
 ```
-
-## Global Flags
-
-
-| Flag              | Description                                           |
-| ----------------- | ----------------------------------------------------- |
-| `--output, -o`    | Output format: `table`, `json`, `yaml` (default: table) |
-| `--debug`         | Enable debug output (API request/response details)    |
-| `--timeout`       | HTTP request timeout (default: 30s)                   |
-| `--base-url`      | Override API base URL                                 |
-| `--config`        | Path to config file (default: `~/.verda/config.yaml`) |
-
-### Structured Output
-
-All list and describe commands support `--output json` and `--output yaml` for scripting:
-
-```bash
-# Pipe to jq
-verda vm list -o json | jq '.[].hostname'
-
-# YAML output
-verda volume describe vol-123 -o yaml
-
-# Use in CI/CD scripts
-INSTANCE_ID=$(verda vm list -o json | jq -r '.[0].id')
+"What GPU types are available right now?"
+"How much does an 8x H100 cost per hour?"
+"I need a cheap GPU for testing — what's the best option?"
+"Deploy a V100 GPU VM with 100GB OS volume"
+"Show my running VMs and what they're costing me"
+"Shut down my training VM"
 ```
 
-### Wait for Operations
+Credentials are shared with the CLI — run `verda auth login` first.
 
-Async commands support `--wait` to poll until completion:
+### Agent Mode
+
+For scripts and agents that use the CLI directly (without MCP):
 
 ```bash
-verda vm create --hostname gpu-runner --wait --wait-timeout 10m
-verda vm action --id abc-123 --wait
-verda volume create --name data --size 500 --wait
+verda --agent vm list                  # JSON output, no prompts
+verda --agent vm create ...            # structured errors for missing flags
+verda --agent vm action --id X --action shutdown --yes
 ```
 
+See [Agent Error Format](docs/agent-errors.md) for the structured error specification.
 
 ## Configuration
 
-Credentials are stored in `~/.verda/credentials` (AWS-style INI format):
+Credentials are stored in `~/.verda/credentials` (INI format):
 
 ```ini
 [default]
@@ -306,9 +152,14 @@ verda_client_id     = your-client-id
 verda_client_secret = your-client-secret
 ```
 
-Settings (theme, etc.) are stored in `~/.verda/config.yaml`.
+Multiple profiles are supported — switch with `verda auth use PROFILE`.
+
+## Documentation
 
-Override the config directory with `VERDA_HOME` environment variable.
+| Doc | Description |
+|-----|-------------|
+| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples |
+| [Agent Error Format](docs/agent-errors.md) | Structured error specification for `--agent` mode |
 
 ## Contributing