# vm-cloud

Hetzner Cloud operator CLI (`vmc`) with audit-ready receipts, plan/apply safety, and a tamper-evident local ledger.

## Quick start

1) Install deps

```bash
npm install
```

2) Configure Hetzner token

Create `~/.env` (recommended) or a project `.env` with:

```bash
HCLOUD_TOKEN=xxx
```

3) Run

```bash
# dev (runs TS directly)
npm run dev -- --help

# or
./bin/vmc --help
```

## Commands

### Read-only

```bash
vmc servers list
vmc snapshot servers
vmc research new "Hetzner Baseline YYYY-MM-DD"
vmc research append --from outputs/hetzner/servers-*.json
```

### Mutations (safe)

All mutations:
- resolve server by id/name (exact first, partial only when unambiguous)
- require confirmation (or `--yes`)
- write a receipt to `outputs/receipts/`
- acquire a per-server lock (`~/.cache/vm-cloud/locks/<id>.lock`) to prevent concurrent ops

#### Plan (dry-run)

```bash
vmc servers labels <name|id> env=prod owner=ops --dry-run
# => outputs/plans/plan-*.json with SHA256+BLAKE3
```

#### Apply

```bash
vmc apply --plan outputs/plans/plan-*.json --yes --reason "change ticket / intent"
```

### Ledger + verification

```bash
vmc verify receipt outputs/receipts/<file>.json --head --plan --sig
vmc verify chain --head --sig
```

### Signing

```bash
vmc keygen
vmc sign receipt outputs/receipts/<file>.json
```

### Merkle receipts

```bash
vmc merkle receipts
# => outputs/ledger/merkle-*.json (root over receipt blake3 chain)
```

## Safety notes

- Never commit `.env` or `outputs/` or `node_modules/` (see `.gitignore`).
- Rotate any leaked tokens immediately.