Feat/cli improvements (#5)

* feat: add structured output, shell completion, ssh, describe, and wait

Add five CLI improvements to close the gap with modern cloud CLIs:

1. `--output json|yaml|table` global flag (-o) for structured output
   across all list and describe commands, enabling scripting and
   automation pipelines (e.g. `verda vm list -o json | jq`).

2. `verda completion` command for bash, zsh, fish, and powershell
   shell completions using Cobra's built-in generation.

3. `verda ssh <instance>` command to SSH into a running VM by
   hostname or ID. Resolves IP from the API and exec's into ssh.
   Supports --user, --key, and pass-through args via --.

4. `verda vm describe` and `verda volume describe` commands to
   show detailed info about a single resource (aliased as get/show),
   with full --output flag support.

5. `--wait` and `--wait-timeout` flags on vm create, vm action,
   volume create, and volume action. Generic polling utility with
   animated spinner for interactive use and silent mode for
   structured output.

Includes 33 new unit tests covering all features.

* docs: update README with new commands and global flags

Add documentation for ssh, describe, completion commands,
--output flag, structured output examples, and --wait flag.


* feat: add images, availability, and cost commands

Add three new command groups:

- `verda images` — browse OS images with --type and --category
  filters. Shows name, category, and details (e.g., CUDA version).

- `verda availability` — check instance type availability per
  location. Supports --location, --type, and --spot flags.
  Single-type check returns a boolean; full matrix shows all
  available types per datacenter.

- `verda cost` — cost estimation, pricing, and billing:
  - `estimate` — calculate hourly/daily/monthly costs for an
    instance type + optional volumes, with spot pricing support
  - `price-history` — show historical fixed and dynamic pricing
  - `balance` — display current account balance

All commands support --output json/yaml for scripting.
Includes tests for cost math, formatting, and filtering logic.

* fix(cost): use list-all endpoint instead of single-type lookup

The /instance-types/{type} endpoint returns 404. Fetch all instance
types and filter client-side instead.

* fix(cost): use lowercase currency to match API expectations

The Verda API requires lowercase 'usd', not 'USD'.

* fix(cost): remove price-history subcommand

The /instance-types/price-history endpoint has been removed by the
API (410 Gone). Dynamic pricing is no longer supported.

* feat: add verda locations command

List available datacenter locations with code, name, and country.
Supports --output json/yaml.

* test+docs: add locations tests and update README

* feat(cost): add running subcommand and live test script

- `verda cost running` shows burn rate of all running instances
  with per-instance breakdown including attached volume costs
- Add scripts/live-test.sh for automated integration testing

* test+docs: add running cost tests and update README

* fix: suppress spinners for structured output

When --output is json or yaml, return nil from Factory.Status()
so spinners don't write escape codes to stdout and break piping.

* feat: add instance-types command and non-interactive vm list

- `verda instance-types` lists all types with specs and pricing,
  with --gpu, --cpu, and --spot filters. Groups output by GPU vs CPU.

- `verda vm list` now prints a static table when stdout is piped
  or redirected, instead of launching the interactive picker.
  Interactive mode still works in a terminal.

* fix(instance-types): clean GPU descriptions and improve formatting

- Strip duplicate count prefix from API GPU descriptions
  (e.g., "1x 1x H100 SXM5 80GB" → "1x H100 SXM5")
- Strip trailing VRAM from description (shown in separate column)
- Format large RAM values as TB (e.g., 1440GB → 1.4TB)
- Widen GPU column for longer names

* fix(vm list): dynamic hostname column width in table mode

Compute max hostname length so columns stay aligned with long names.

* docs: add instance-types to README

* refactor: move renderVolumeSummary to dedicated view.go

* refactor: extract UniqueVolumeIDs to shared util

* feat: code review fixes, interactive pickers, and test infrastructure

- Separate "Flags" from "Global Flags" in help output
- Register --output flag completion values (json/yaml/table)
- Remove dead JSON bool field from vm list options
- Fix Poll() timeout to return error instead of nil
- Consolidate duplicate polling code from status_view.go into shared wait.go
- Centralize status messages and terminal statuses in status_messages.go
- Add interactive picker for verda ssh (no-arg shows running instances)
- Add interactive picker for vm describe and volume describe (no-arg shows list)
- Add reusable TestFactory in cmd/util/testing.go for command-level tests
- Add arg-validation and status message tests
- Fix pre-existing lint issues (stuttering type names, hugeParam, goimports)
- Ignore .ai/notes/ and docs/plans/ in .gitignore

* fix: version output and instance card display issues

- Version: show human-readable text by default, JSON only with -o json
- Image: show image slug instead of volume name, append OS name if different
- Compute: strip duplicate "1x" prefix from GPU description
- Pricing: remove redundant field (only fixed pricing exists)
- Storage Status: show actual status (attached/detached) with "(OS)" label

* fix(version): show only version and platform by default

Full build details still available via verda version -o json.

* feat(vm): add availability command showing instance specs and pricing

Joins instance type specs, pricing, and live availability data into a
single view — sorted by price, filterable by location, type, kind, and
spot. Addresses user request for a native alternative to the Python
availability script.

Usage:
  verda vm availability
  verda vm availability --location FIN-01 --kind gpu --spot
  verda vm availability -o json

* fix: resolve gosec G204 and G602 lint warnings

- ssh.go: suppress G204 for intentional syscall.Exec into ssh
- images_test.go, instancetypes_test.go: use empty slice instead of nil
  to avoid G602 false positive on nil range

---------

Co-authored-by: Milosz Szewczak <milosz@datacrunch.io>

Author: hi-lei

.gitignore

@@ -1,6 +1,7 @@
 # Build artifacts
 bin/
 _output/
+verda
 
 # Local smoke-test output (see test/run.sh)
 tmp/
@@ -360,3 +361,15 @@ tmp-test-*/
 
 # VHS demo recordings
 vhs/
+
+# Live test script (contains local testing logic)
+scripts/live-test.sh
+
+# Claude Code local config (absolute paths, machine-specific)
+.claude/settings.json
+.claude/commands/
+.claude/topic-switch.json
+
+# AI working notes and implementation plans (not shipped)
+.ai/notes/
+docs/plans/

README.md

@@ -110,13 +110,22 @@ Auth Commands:
 
 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
@@ -125,23 +134,76 @@ Other Commands:
 ### VM
 
 
-| Command           | Description                                |
-| ----------------- | ------------------------------------------ |
-| `verda vm create` | Create a VM (interactive wizard or flags)  |
-| `verda vm list`   | List and inspect VM instances              |
-| `verda vm action` | Start, shutdown, hibernate, or delete a 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
+
+```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 action` | Detach, rename, resize, clone, or delete     |
-| `verda volume trash`  | List deleted volumes (restorable within 96h) |
+| 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
+
+```bash
+# Estimate costs before creating
+verda cost estimate --type 1V100.6V --os-volume 100 --storage 500
+verda cost estimate --type 1V100.6V --spot
+
+# See what your running instances are costing you
+verda cost running
+
+# Account balance
+verda cost balance
+```
 
 ### SSH Keys & Startup Scripts
 
@@ -183,15 +245,54 @@ Available themes: `default`, `dracula`, `catppuccin`, `catppuccin-latte`, `nord`
 | `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                                           |
-| ------------ | ----------------------------------------------------- |
-| `--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`) |
+| 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')
+```
+
+### Wait for Operations
+
+Async commands support `--wait` to poll until completion:
+
+```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
+```
 
 
 ## Configuration

go.mod

@@ -13,7 +13,10 @@ require (
 	go.yaml.in/yaml/v3 v3.0.4
 )
 
-require gopkg.in/ini.v1 v1.67.1
+require (
+	github.com/charmbracelet/x/term v0.2.2
+	gopkg.in/ini.v1 v1.67.1
+)
 
 require (
 	charm.land/bubbles/v2 v2.1.0 // indirect
@@ -23,7 +26,6 @@ require (
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/ultraviolet v0.0.0-20260205113103-524a6607adb8 // indirect
 	github.com/charmbracelet/x/ansi v0.11.6 // indirect
-	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
 	github.com/charmbracelet/x/windows v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect