Add minectl Claude skill for CLI usage

minectl-skill/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: minectl
+description: "Deploy and manage Minecraft servers across 16 cloud providers using the minectl CLI. Use when the user wants to create, delete, update, or list Minecraft servers, write minectl YAML manifests, connect via RCON, upload plugins, or choose cloud providers and server editions for Minecraft hosting. Triggers on: Minecraft server deployment, minectl commands, Minecraft manifest files, cloud-hosted game servers, or Minecraft edition selection."
+---
+
+# minectl
+
+minectl creates and manages Minecraft servers on 16 cloud providers via declarative YAML manifests.
+
+## Creating a Manifest
+
+Every operation starts with a manifest file:
+
+```yaml
+apiVersion: minectl.ediri.io/v1alpha1
+kind: MinecraftServer
+metadata:
+  name: my-minecraft
+spec:
+  server:
+    cloud: hetzner
+    region: fsn1
+    size: cx21
+    ssh:
+      port: 22
+      publickeyfile: ~/.ssh/id_rsa.pub
+      fail2ban:
+        bantime: 1000
+        maxretry: 3
+    port: 25565
+  minecraft:
+    java:
+      openjdk: 21
+      xmx: 2G
+      xms: 2G
+      rcon:
+        password: changeme
+        port: 25575
+        enabled: true
+    edition: papermc
+    version: "1.21"
+    eula: true
+    properties: |
+      max-players=20
+      difficulty=normal
+      motd=My Minecraft Server
+```
+
+### Choosing an Edition
+
+| Edition | Best for |
+|---------|----------|
+| `java` | Vanilla experience, no mods |
+| `papermc` | Performance + plugin support (recommended) |
+| `spigot` | Bukkit plugin ecosystem |
+| `craftbukkit` | Legacy Bukkit plugins |
+| `fabric` | Lightweight mods |
+| `forge` | Large mod packs |
+| `purpur` | Paper + extra gameplay tweaks |
+| `bedrock` | Cross-platform (mobile/console/PC) |
+| `nukkit` | Java-based Bedrock server |
+| `powernukkit` | Extended Nukkit |
+
+For proxy setups, use `kind: MinecraftProxy` with editions: `bungeecord`, `waterfall`, or `velocity`.
+
+### Optional Features
+
+Add to `spec.server`:
+- `spot: true` - Spot/preemptible instances (AWS, Azure, GCE) to save cost
+- `arm: true` - ARM instances (Hetzner, AWS, GCE)
+- `volumeSize: 50` - Extra storage in GB
+
+Add to `spec`:
+- `monitoring: { enabled: true }` - Prometheus + Node Exporter
+
+### Naming Rules
+
+- `metadata.name` must be lowercase alphanumeric with hyphens only
+- SSH port must be 22 or between 1024-65535
+- `eula` must be `true`
+
+## Server Lifecycle
+
+```bash
+# Generate a manifest interactively
+minectl wizard
+
+# Create a server (waits for startup by default)
+minectl create -f server.yaml
+
+# Verify the server is running after creation
+minectl list -p hetzner -r fsn1
+# Expected: server appears with a valid ID and status. If absent, check credentials and quota.
+
+# List running servers
+minectl list -p hetzner -r fsn1
+
+# Connect via RCON for remote commands
+minectl rcon -f server.yaml --id <server-id>
+
+# Upload a plugin
+minectl plugins -f server.yaml --id <server-id> -k ~/.ssh/id_rsa \
+  -p myplugin.jar -d /minecraft/plugins
+
+# Update Minecraft version (edit version in manifest first)
+minectl update -f server.yaml --id <server-id> -k ~/.ssh/id_rsa
+
+# Delete the server
+minectl delete -f server.yaml --id <server-id> -y
+```
+
+### Error Recovery
+
+| Symptom | Likely cause | Action |
+|---------|--------------|--------|
+| `create` exits without a server ID | Authentication failure | Verify provider environment variables are exported (see [references/cloud-providers.md](references/cloud-providers.md)) |
+| `create` fails with quota/limit error | Cloud account quota exceeded | Switch region, use a smaller `size`, or request a quota increase from the provider |
+| `create` succeeds but server absent from `list` | Wrong region or provider flag | Re-run `minectl list` with the exact `-p` and `-r` values from the manifest |
+| Plugin upload fails | SSH key mismatch | Confirm `-k` points to the private key matching `spec.server.ssh.publickeyfile` |
+| RCON connection refused | RCON not enabled or wrong port | Ensure `rcon.enabled: true` and the port in the manifest matches `rcon.port` |
+
+## Cloud Provider Selection
+
+When helping a user choose a provider, consider:
+- **Budget**: Civo, Hetzner, and DigitalOcean are cheapest. Use `spot: true` on AWS/Azure/GCE for savings.
+- **Region needs**: Check [references/cloud-providers.md](references/cloud-providers.md) for available regions.
+- **Local testing**: Use `multipass` for local VMs with no cloud account needed.
+
+Each provider requires specific environment variables for authentication. See [references/cloud-providers.md](references/cloud-providers.md) for the full list.
+
+## References
+
+- **Cloud providers, credentials, and sizes**: [references/cloud-providers.md](references/cloud-providers.md)
+- **Full manifest schema**: [references/manifest-schema.md](references/manifest-schema.md)
+- **CLI command flags and details**: [references/cli-commands.md](references/cli-commands.md)

minectl-skill/references/cli-commands.md

@@ -0,0 +1,141 @@
+# CLI Command Reference
+
+## Global Flags
+
+```
+--verbose <level>     Logging level: debug|info|warn|error|dpanic|panic|fatal
+--log-encoding <fmt>  Log format: console|json (default: console)
+--headless            CI mode: enables logging, disables interactive output
+```
+
+## Commands
+
+### create
+
+Create a Minecraft server from a manifest file.
+
+```bash
+minectl create -f <manifest.yaml> [--wait=true]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--filename` | `-f` | Path to manifest YAML file (required) |
+| `--wait` | `-w` | Wait for server startup (default: true) |
+
+Output: table with ID, NAME, REGION, TAGS, IP.
+
+### delete
+
+Delete an existing Minecraft server.
+
+```bash
+minectl delete -f <manifest.yaml> --id <server-id> [-y]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--filename` | `-f` | Path to manifest YAML file (required) |
+| `--id` | | Server ID (required) |
+| `--yes` | `-y` | Skip confirmation prompt |
+
+### list
+
+List all Minecraft servers for a provider/region.
+
+```bash
+minectl list -p <provider> [-r <region>]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--provider` | `-p` | Cloud provider name (required) |
+| `--region` | `-r` | Region filter (required for civo, gce) |
+
+### update
+
+Update Minecraft version on an existing server via SSH.
+
+```bash
+minectl update -f <manifest.yaml> --id <server-id> -k <ssh-key-path>
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--filename` | `-f` | Path to manifest YAML file (required) |
+| `--id` | | Server ID (required) |
+| `--ssh-key` | `-k` | Path to SSH private key (required) |
+
+### rcon
+
+Connect to a server's RCON port for remote commands.
+
+```bash
+minectl rcon -f <manifest.yaml> --id <server-id>
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--filename` | `-f` | Path to manifest YAML file (required) |
+| `--id` | | Server ID (required) |
+
+Opens an interactive RCON shell. RCON must be enabled in the manifest.
+
+### plugins
+
+Upload plugins/mods to a running server (beta).
+
+```bash
+minectl plugins -f <manifest.yaml> --id <server-id> -k <ssh-key> -p <plugin.jar> -d <dest>
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--filename` | `-f` | Path to manifest YAML file (required) |
+| `--id` | | Server ID (required) |
+| `--ssh-key` | `-k` | Path to SSH private key (required) |
+| `--plugin` | `-p` | Path to plugin JAR file |
+| `--destination` | `-d` | Server-side destination folder (e.g., `/minecraft/plugins`) |
+
+### wizard
+
+Interactive questionnaire to generate a manifest file.
+
+```bash
+minectl wizard [-o <output-dir>]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output directory (default: `~/.minectl`) |
+
+### version
+
+Display version information.
+
+```bash
+minectl version
+```
+
+## Typical Workflow
+
+```bash
+# 1. Generate manifest interactively
+minectl wizard -o ./configs
+
+# 2. Create server
+minectl create -f ./configs/config-my-server.yaml
+
+# 3. Connect via RCON
+minectl rcon -f ./configs/config-my-server.yaml --id <server-id>
+
+# 4. Upload a plugin
+minectl plugins -f ./configs/config-my-server.yaml --id <server-id> \
+  -k ~/.ssh/id_rsa -p ./myplugin.jar -d /minecraft/plugins
+
+# 5. Update Minecraft version (edit manifest version first)
+minectl update -f ./configs/config-my-server.yaml --id <server-id> -k ~/.ssh/id_rsa
+
+# 6. Delete when done
+minectl delete -f ./configs/config-my-server.yaml --id <server-id> -y
+```

minectl-skill/references/cloud-providers.md

@@ -0,0 +1,51 @@
+# Cloud Provider Reference
+
+## Supported Providers and Environment Variables
+
+| Provider | `cloud` value | Required Environment Variables |
+|----------|--------------|-------------------------------|
+| Civo | `civo` | `CIVO_TOKEN` |
+| Scaleway | `scaleway` | `ACCESS_KEY`, `SECRET_KEY`, `ORGANISATION_ID` |
+| DigitalOcean | `do` | `DIGITALOCEAN_TOKEN` |
+| Hetzner | `hetzner` | `HCLOUD_TOKEN` |
+| Akamai (Linode) | `akamai` | `LINODE_TOKEN` |
+| OVHcloud | `ovh` | `OVH_ENDPOINT`, `APPLICATION_KEY`, `APPLICATION_SECRET`, `CONSUMER_KEY`, `SERVICENAME` |
+| Google Compute Engine | `gce` | `GCE_KEY` |
+| Vultr | `vultr` | `VULTR_API_KEY` |
+| Azure | `azure` | `AZURE_AUTH_LOCATION` |
+| Oracle Cloud (OCI) | `oci` | OCI SDK config (default) |
+| IONOS Cloud | `ionos` | `IONOS_USERNAME`, `IONOS_PASSWORD`, `IONOS_TOKEN` |
+| AWS | `aws` | Standard AWS SDK credentials |
+| VEXXHOST | `vexxhost` | OpenStack env vars |
+| Exoscale | `exoscale` | `EXOSCALE_API_KEY`, `EXOSCALE_API_SECRET` |
+| Fuga Cloud | `fuga` | OpenStack env vars |
+| Ubuntu Multipass | `multipass` | None (local) |
+
+## Region Examples
+
+| Provider | Example Regions |
+|----------|----------------|
+| Civo | `LON1`, `NYC1`, `FRA1` |
+| DigitalOcean | `fra1`, `nyc1`, `sfo1` |
+| Hetzner | `fsn1`, `nbg1`, `hel1` |
+| AWS | `eu-central-1`, `us-east-1`, `ap-southeast-1` |
+| GCE | `europe-west6-a`, `us-central1-a` |
+| Azure | `westeurope`, `eastus` |
+| Scaleway | `fr-par-1`, `nl-ams-1` |
+
+## Size Examples
+
+| Provider | Example Sizes |
+|----------|--------------|
+| Civo | `g3.large`, `g3.xlarge` |
+| DigitalOcean | `s-4vcpu-8gb` |
+| Hetzner | `cx21`, `cpx31` |
+| AWS | `t3.xlarge`, `m5.large` |
+| GCE | `e2-standard-2`, `e2-standard-4` |
+| Azure | `Standard_B2s` |
+
+## Features by Provider
+
+- **Spot instances**: AWS (`spot: true`), Azure (`spot: true`), GCE (`spot: true`)
+- **ARM support**: Hetzner (`arm: true`), AWS (`arm: true`), GCE (`arm: true`)
+- **Volumes**: All providers support `volumeSize` (in GB)