Skip to content

Commit aedeb18

Browse files
diriendirien
authored
docs: add minectl Claude skill for CLI usage guidance
Add a Claude skill that helps users deploy and manage Minecraft servers with minectl across 16 cloud providers. Includes manifest schema reference, CLI command documentation, and cloud provider credential guide.
1 parent 0577aa1 commit aedeb18

File tree

4 files changed

+421
-0
lines changed

4 files changed

+421
-0
lines changed

‎minectl-skill/SKILL.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: minectl
3+
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."
4+
---
5+
6+
# minectl
7+
8+
minectl creates and manages Minecraft servers on 16 cloud providers via declarative YAML manifests.
9+
10+
## Creating a Manifest
11+
12+
Every operation starts with a manifest file:
13+
14+
```yaml
15+
apiVersion: minectl.ediri.io/v1alpha1
16+
kind: MinecraftServer
17+
metadata:
18+
name: my-minecraft
19+
spec:
20+
server:
21+
cloud: hetzner
22+
region: fsn1
23+
size: cx21
24+
ssh:
25+
port: 22
26+
publickeyfile: ~/.ssh/id_rsa.pub
27+
fail2ban:
28+
bantime: 1000
29+
maxretry: 3
30+
port: 25565
31+
minecraft:
32+
java:
33+
openjdk: 21
34+
xmx: 2G
35+
xms: 2G
36+
rcon:
37+
password: changeme
38+
port: 25575
39+
enabled: true
40+
edition: papermc
41+
version: "1.21"
42+
eula: true
43+
properties: |
44+
max-players=20
45+
difficulty=normal
46+
motd=My Minecraft Server
47+
```
48+
49+
### Choosing an Edition
50+
51+
| Edition | Best for |
52+
|---------|----------|
53+
| `java` | Vanilla experience, no mods |
54+
| `papermc` | Performance + plugin support (recommended) |
55+
| `spigot` | Bukkit plugin ecosystem |
56+
| `craftbukkit` | Legacy Bukkit plugins |
57+
| `fabric` | Lightweight mods |
58+
| `forge` | Large mod packs |
59+
| `purpur` | Paper + extra gameplay tweaks |
60+
| `bedrock` | Cross-platform (mobile/console/PC) |
61+
| `nukkit` | Java-based Bedrock server |
62+
| `powernukkit` | Extended Nukkit |
63+
64+
For proxy setups, use `kind: MinecraftProxy` with editions: `bungeecord`, `waterfall`, or `velocity`.
65+
66+
### Optional Features
67+
68+
Add to `spec.server`:
69+
- `spot: true` - Spot/preemptible instances (AWS, Azure, GCE) to save cost
70+
- `arm: true` - ARM instances (Hetzner, AWS, GCE)
71+
- `volumeSize: 50` - Extra storage in GB
72+
73+
Add to `spec`:
74+
- `monitoring: { enabled: true }` - Prometheus + Node Exporter
75+
76+
### Naming Rules
77+
78+
- `metadata.name` must be lowercase alphanumeric with hyphens only
79+
- SSH port must be 22 or between 1024-65535
80+
- `eula` must be `true`
81+
82+
## Server Lifecycle
83+
84+
```bash
85+
# Generate a manifest interactively
86+
minectl wizard
87+
88+
# Create a server (waits for startup by default)
89+
minectl create -f server.yaml
90+
91+
# Verify the server is running after creation
92+
minectl list -p hetzner -r fsn1
93+
# Expected: server appears with a valid ID and status. If absent, check credentials and quota.
94+
95+
# List running servers
96+
minectl list -p hetzner -r fsn1
97+
98+
# Connect via RCON for remote commands
99+
minectl rcon -f server.yaml --id <server-id>
100+
101+
# Upload a plugin
102+
minectl plugins -f server.yaml --id <server-id> -k ~/.ssh/id_rsa \
103+
-p myplugin.jar -d /minecraft/plugins
104+
105+
# Update Minecraft version (edit version in manifest first)
106+
minectl update -f server.yaml --id <server-id> -k ~/.ssh/id_rsa
107+
108+
# Delete the server
109+
minectl delete -f server.yaml --id <server-id> -y
110+
```
111+
112+
### Error Recovery
113+
114+
| Symptom | Likely cause | Action |
115+
|---------|--------------|--------|
116+
| `create` exits without a server ID | Authentication failure | Verify provider environment variables are exported (see [references/cloud-providers.md](references/cloud-providers.md)) |
117+
| `create` fails with quota/limit error | Cloud account quota exceeded | Switch region, use a smaller `size`, or request a quota increase from the provider |
118+
| `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 |
119+
| Plugin upload fails | SSH key mismatch | Confirm `-k` points to the private key matching `spec.server.ssh.publickeyfile` |
120+
| RCON connection refused | RCON not enabled or wrong port | Ensure `rcon.enabled: true` and the port in the manifest matches `rcon.port` |
121+
122+
## Cloud Provider Selection
123+
124+
When helping a user choose a provider, consider:
125+
- **Budget**: Civo, Hetzner, and DigitalOcean are cheapest. Use `spot: true` on AWS/Azure/GCE for savings.
126+
- **Region needs**: Check [references/cloud-providers.md](references/cloud-providers.md) for available regions.
127+
- **Local testing**: Use `multipass` for local VMs with no cloud account needed.
128+
129+
Each provider requires specific environment variables for authentication. See [references/cloud-providers.md](references/cloud-providers.md) for the full list.
130+
131+
## References
132+
133+
- **Cloud providers, credentials, and sizes**: [references/cloud-providers.md](references/cloud-providers.md)
134+
- **Full manifest schema**: [references/manifest-schema.md](references/manifest-schema.md)
135+
- **CLI command flags and details**: [references/cli-commands.md](references/cli-commands.md)

‎minectl-skill/references/cli-commands.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# CLI Command Reference
2+
3+
## Global Flags
4+
5+
```
6+
--verbose <level> Logging level: debug|info|warn|error|dpanic|panic|fatal
7+
--log-encoding <fmt> Log format: console|json (default: console)
8+
--headless CI mode: enables logging, disables interactive output
9+
```
10+
11+
## Commands
12+
13+
### create
14+
15+
Create a Minecraft server from a manifest file.
16+
17+
```bash
18+
minectl create -f <manifest.yaml> [--wait=true]
19+
```
20+
21+
| Flag | Short | Description |
22+
|------|-------|-------------|
23+
| `--filename` | `-f` | Path to manifest YAML file (required) |
24+
| `--wait` | `-w` | Wait for server startup (default: true) |
25+
26+
Output: table with ID, NAME, REGION, TAGS, IP.
27+
28+
### delete
29+
30+
Delete an existing Minecraft server.
31+
32+
```bash
33+
minectl delete -f <manifest.yaml> --id <server-id> [-y]
34+
```
35+
36+
| Flag | Short | Description |
37+
|------|-------|-------------|
38+
| `--filename` | `-f` | Path to manifest YAML file (required) |
39+
| `--id` | | Server ID (required) |
40+
| `--yes` | `-y` | Skip confirmation prompt |
41+
42+
### list
43+
44+
List all Minecraft servers for a provider/region.
45+
46+
```bash
47+
minectl list -p <provider> [-r <region>]
48+
```
49+
50+
| Flag | Short | Description |
51+
|------|-------|-------------|
52+
| `--provider` | `-p` | Cloud provider name (required) |
53+
| `--region` | `-r` | Region filter (required for civo, gce) |
54+
55+
### update
56+
57+
Update Minecraft version on an existing server via SSH.
58+
59+
```bash
60+
minectl update -f <manifest.yaml> --id <server-id> -k <ssh-key-path>
61+
```
62+
63+
| Flag | Short | Description |
64+
|------|-------|-------------|
65+
| `--filename` | `-f` | Path to manifest YAML file (required) |
66+
| `--id` | | Server ID (required) |
67+
| `--ssh-key` | `-k` | Path to SSH private key (required) |
68+
69+
### rcon
70+
71+
Connect to a server's RCON port for remote commands.
72+
73+
```bash
74+
minectl rcon -f <manifest.yaml> --id <server-id>
75+
```
76+
77+
| Flag | Short | Description |
78+
|------|-------|-------------|
79+
| `--filename` | `-f` | Path to manifest YAML file (required) |
80+
| `--id` | | Server ID (required) |
81+
82+
Opens an interactive RCON shell. RCON must be enabled in the manifest.
83+
84+
### plugins
85+
86+
Upload plugins/mods to a running server (beta).
87+
88+
```bash
89+
minectl plugins -f <manifest.yaml> --id <server-id> -k <ssh-key> -p <plugin.jar> -d <dest>
90+
```
91+
92+
| Flag | Short | Description |
93+
|------|-------|-------------|
94+
| `--filename` | `-f` | Path to manifest YAML file (required) |
95+
| `--id` | | Server ID (required) |
96+
| `--ssh-key` | `-k` | Path to SSH private key (required) |
97+
| `--plugin` | `-p` | Path to plugin JAR file |
98+
| `--destination` | `-d` | Server-side destination folder (e.g., `/minecraft/plugins`) |
99+
100+
### wizard
101+
102+
Interactive questionnaire to generate a manifest file.
103+
104+
```bash
105+
minectl wizard [-o <output-dir>]
106+
```
107+
108+
| Flag | Short | Description |
109+
|------|-------|-------------|
110+
| `--output` | `-o` | Output directory (default: `~/.minectl`) |
111+
112+
### version
113+
114+
Display version information.
115+
116+
```bash
117+
minectl version
118+
```
119+
120+
## Typical Workflow
121+
122+
```bash
123+
# 1. Generate manifest interactively
124+
minectl wizard -o ./configs
125+
126+
# 2. Create server
127+
minectl create -f ./configs/config-my-server.yaml
128+
129+
# 3. Connect via RCON
130+
minectl rcon -f ./configs/config-my-server.yaml --id <server-id>
131+
132+
# 4. Upload a plugin
133+
minectl plugins -f ./configs/config-my-server.yaml --id <server-id> \
134+
-k ~/.ssh/id_rsa -p ./myplugin.jar -d /minecraft/plugins
135+
136+
# 5. Update Minecraft version (edit manifest version first)
137+
minectl update -f ./configs/config-my-server.yaml --id <server-id> -k ~/.ssh/id_rsa
138+
139+
# 6. Delete when done
140+
minectl delete -f ./configs/config-my-server.yaml --id <server-id> -y
141+
```

‎minectl-skill/references/cloud-providers.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Cloud Provider Reference
2+
3+
## Supported Providers and Environment Variables
4+
5+
| Provider | `cloud` value | Required Environment Variables |
6+
|----------|--------------|-------------------------------|
7+
| Civo | `civo` | `CIVO_TOKEN` |
8+
| Scaleway | `scaleway` | `ACCESS_KEY`, `SECRET_KEY`, `ORGANISATION_ID` |
9+
| DigitalOcean | `do` | `DIGITALOCEAN_TOKEN` |
10+
| Hetzner | `hetzner` | `HCLOUD_TOKEN` |
11+
| Akamai (Linode) | `akamai` | `LINODE_TOKEN` |
12+
| OVHcloud | `ovh` | `OVH_ENDPOINT`, `APPLICATION_KEY`, `APPLICATION_SECRET`, `CONSUMER_KEY`, `SERVICENAME` |
13+
| Google Compute Engine | `gce` | `GCE_KEY` |
14+
| Vultr | `vultr` | `VULTR_API_KEY` |
15+
| Azure | `azure` | `AZURE_AUTH_LOCATION` |
16+
| Oracle Cloud (OCI) | `oci` | OCI SDK config (default) |
17+
| IONOS Cloud | `ionos` | `IONOS_USERNAME`, `IONOS_PASSWORD`, `IONOS_TOKEN` |
18+
| AWS | `aws` | Standard AWS SDK credentials |
19+
| VEXXHOST | `vexxhost` | OpenStack env vars |
20+
| Exoscale | `exoscale` | `EXOSCALE_API_KEY`, `EXOSCALE_API_SECRET` |
21+
| Fuga Cloud | `fuga` | OpenStack env vars |
22+
| Ubuntu Multipass | `multipass` | None (local) |
23+
24+
## Region Examples
25+
26+
| Provider | Example Regions |
27+
|----------|----------------|
28+
| Civo | `LON1`, `NYC1`, `FRA1` |
29+
| DigitalOcean | `fra1`, `nyc1`, `sfo1` |
30+
| Hetzner | `fsn1`, `nbg1`, `hel1` |
31+
| AWS | `eu-central-1`, `us-east-1`, `ap-southeast-1` |
32+
| GCE | `europe-west6-a`, `us-central1-a` |
33+
| Azure | `westeurope`, `eastus` |
34+
| Scaleway | `fr-par-1`, `nl-ams-1` |
35+
36+
## Size Examples
37+
38+
| Provider | Example Sizes |
39+
|----------|--------------|
40+
| Civo | `g3.large`, `g3.xlarge` |
41+
| DigitalOcean | `s-4vcpu-8gb` |
42+
| Hetzner | `cx21`, `cpx31` |
43+
| AWS | `t3.xlarge`, `m5.large` |
44+
| GCE | `e2-standard-2`, `e2-standard-4` |
45+
| Azure | `Standard_B2s` |
46+
47+
## Features by Provider
48+
49+
- **Spot instances**: AWS (`spot: true`), Azure (`spot: true`), GCE (`spot: true`)
50+
- **ARM support**: Hetzner (`arm: true`), AWS (`arm: true`), GCE (`arm: true`)
51+
- **Volumes**: All providers support `volumeSize` (in GB)

0 commit comments

Comments
 (0)