Improve cloudamqp-cli skill based on review and testing

Author: baelter

cmd/skills/cloudamqp-cli/SKILL.md

@@ -1,54 +1,41 @@
 ---
 name: cloudamqp-cli
-description: Manage CloudAMQP instances, VPCs, teams, and RabbitMQ/LavinMQ configuration from the command line. Use when the user needs to create, configure, monitor, upgrade, or troubleshoot CloudAMQP message broker instances.
-allowed-tools: Bash(cloudamqp:*)
+description: Manage CloudAMQP instances, VPCs, teams, and RabbitMQ/LavinMQ configuration using the cloudamqp CLI. Use this skill whenever the user wants to create, list, inspect, update, delete, upgrade, restart, or troubleshoot CloudAMQP instances — even if they just say "spin up a RabbitMQ", "check my instances", or "upgrade my broker". Also use it for VPC setup, team management, and RabbitMQ config changes.
+allowed-tools: Bash(cloudamqp:*), Bash(jq:*), Bash(cat:*), Bash(echo:*), Bash(chmod:*), Bash(grep:*), Bash(sleep:*)
 ---
 
 # CloudAMQP CLI
 
 ## Quick start
 
 ```bash
-# list all instances
 cloudamqp instance list
-
-# get instance details (includes connection URL and API key)
-cloudamqp instance get --id 1234
-
-# create an instance and wait for it to be ready
-cloudamqp instance create --name=my-instance --plan=bunny-1 --region=amazon-web-services::us-east-1 --wait
-
-# restart RabbitMQ on an instance
-cloudamqp instance restart-rabbitmq --id 1234
-
-# delete an instance
-cloudamqp instance delete --id 1234
+cloudamqp instance get --id <id>
+cloudamqp instance create --name=<name> --plan=<plan> --region=<region> --wait
+cloudamqp instance restart-rabbitmq --id <id>
+cloudamqp instance delete --id <id> --force
 ```
 
 ## Authentication
 
-Before running any commands, check that auth is configured — the CLI won't work without it and can't prompt interactively when run by an agent.
+Check auth before running anything — interactive prompts don't work in agent context:
 
 ```bash
-# check if already configured
 cat ~/.cloudamqprc 2>/dev/null || echo "not configured"
-
-# if not set up, ask the user for their API key, then write it:
-echo "YOUR_API_KEY" > ~/.cloudamqprc
-chmod 600 ~/.cloudamqprc
 ```
 
-The CLI checks in this order:
+If not configured, ask the user for their API key (from https://customer.cloudamqp.com/apikeys), then:
 
-1. `CLOUDAMQP_APIKEY` environment variable
-2. `~/.cloudamqprc` file (plain text, just the key)
-3. Interactive prompt (won't work in agent context — use one of the above)
+```bash
+echo "<api-key>" > ~/.cloudamqprc
+chmod 600 ~/.cloudamqprc
+```
 
-Base URL defaults to `https://customer.cloudamqp.com/api` (override with `CLOUDAMQP_URL`).
+Alternatively, set `CLOUDAMQP_APIKEY` in the environment. If neither is set, all commands will fail.
 
 ## Output
 
-All commands support `-o json` for machine-readable output and `-o table` (default) for human-readable output. Use `-fields` to select specific columns.
+Use `-o json` for parsing, `-o table` (default) for display. Use `--fields` to select columns.
 
 ## Commands
 
@@ -63,25 +50,18 @@ cloudamqp instance delete --id <id> [--force]
 cloudamqp instance resize-disk --id <id> --disk-size=<gb> [--allow-downtime]
 ```
 
-### Copy settings between instances
+### Copy settings between instances (dedicated only)
 
 ```bash
-cloudamqp instance create --name=staging --plan=bunny-1 --region=amazon-web-services::us-east-1 \
-  --copy-from-id=1234 --copy-settings=metrics,firewall,config,alarms,logs,definitions,plugins --wait
+cloudamqp instance create --name=staging --plan=<plan> --region=<region> \
+  --copy-from-id=<id> --copy-settings=metrics,firewall,config,alarms,logs,definitions,plugins --wait
 ```
 
-Only works between dedicated instances (not shared plans).
-
-### Node management
+### Node and plugin management
 
 ```bash
 cloudamqp instance nodes list --id <id>
 cloudamqp instance nodes versions --id <id>
-```
-
-### Plugin management
-
-```bash
 cloudamqp instance plugins list --id <id>
 ```
 
@@ -96,19 +76,19 @@ cloudamqp instance config set --id <id> --key <key> --value <value>
 ### Instance actions
 
 ```bash
-# restart
+# restarts (rolling for HA clusters)
 cloudamqp instance restart-rabbitmq --id <id> [--nodes=node1,node2]
-cloudamqp instance restart-cluster --id <id>
-cloudamqp instance restart-management --id <id> [--nodes=node1,node2]
+cloudamqp instance restart-cluster --id <id>          # full restart, causes downtime
+cloudamqp instance restart-management --id <id>
 
 # start/stop
-cloudamqp instance start --id <id> [--nodes=node1,node2]
-cloudamqp instance stop --id <id> [--nodes=node1,node2]
-cloudamqp instance reboot --id <id> [--nodes=node1,node2]
+cloudamqp instance start --id <id>
+cloudamqp instance stop --id <id>
+cloudamqp instance reboot --id <id>
 cloudamqp instance start-cluster --id <id>
 cloudamqp instance stop-cluster --id <id>
 
-# upgrades (async, return immediately)
+# upgrades — async, return immediately, poll until ready
 cloudamqp instance upgrade-erlang --id <id>
 cloudamqp instance upgrade-rabbitmq --id <id> --version=<version>
 cloudamqp instance upgrade-all --id <id>
@@ -118,7 +98,7 @@ cloudamqp instance upgrade-versions --id <id>
 ### VPC management
 
 ```bash
-cloudamqp vpc create --name=<name> --region=<region> --subnet=<cidr> [--tags=<tag>]
+cloudamqp vpc create --name=<name> --region=<region> --subnet=<cidr>
 cloudamqp vpc list
 cloudamqp vpc get --id <id>
 cloudamqp vpc update --id <id> --name=<name>
@@ -134,36 +114,26 @@ cloudamqp team update --user-id=<id> --role=<role>
 cloudamqp team remove --email=<email>
 ```
 
-### Audit log
+### Plans, regions, audit
 
 ```bash
+cloudamqp plans [--backend=rabbitmq|lavinmq]   # always fetch, never guess
+cloudamqp regions [--provider=<provider>]       # always fetch, never guess
 cloudamqp audit [--timestamp=2024-01]
-```
-
-### API key rotation
-
-```bash
 cloudamqp rotate-key
 ```
 
-## Important behavior
-
-- **Async operations**: Instance creation, disk resizes, and upgrades are async. Use `--wait` on create, or poll with `instance get --id <id>` until `ready: true`.
-- **Destructive commands** (delete, stop) prompt for confirmation. Use `--force` to skip in scripts.
-- **Multiple tags**: Use `--tags` multiple times: `--tags=prod --tags=web`.
-- **Shell completion**: Run `source <(cloudamqp completion zsh)` for tab completion of commands, instance IDs, plans, and regions.
-
-## Plans and regions
+## Key behaviors
 
-Always fetch live data — don't guess plan names or regions:
+- **Async**: creation, resizes, upgrades return immediately. Use `--wait` on create, or poll `instance get --id <id> -o json | jq -r '.ready'` until `"true"`.
+- **Destructive commands** prompt for confirmation — use `--force` to skip.
+- **Multiple tags**: repeat the flag: `--tags=prod --tags=web`.
+- **Plan/region names**: always run `cloudamqp plans` / `cloudamqp regions` first — never hardcode them.
 
-```bash
-cloudamqp plans [--backend=rabbitmq|lavinmq]
-cloudamqp regions [--provider=amazon-web-services]
-```
+## Reference guides
 
-## Specific tasks
+Read these before tackling the relevant task:
 
-* **Scripting and automation** [references/scripting.md](references/scripting.md)
-* **Instance upgrades and maintenance** [references/upgrades.md](references/upgrades.md)
-* **VPC and network setup** [references/vpc-setup.md](references/vpc-setup.md)
+- **Scripting, JSON parsing, batch ops** → [references/scripting.md](references/scripting.md)
+- **Upgrades, restarts, maintenance workflows** → [references/upgrades.md](references/upgrades.md)
+- **VPC creation and network setup** → [references/vpc-setup.md](references/vpc-setup.md)

cmd/skills/cloudamqp-cli/references/scripting.md

@@ -2,34 +2,36 @@
 
 ## JSON output for parsing
 
-All commands support `-o json` for structured output. Combine with `jq` for extraction:
+All commands support `-o json`. Combine with `jq`:
 
 ```bash
 # get connection URL for an instance
-cloudamqp instance get --id 1234 -o json | jq -r '.url'
+cloudamqp instance get --id <id> -o json | jq -r '.url'
 
-# list instance IDs matching a tag
-cloudamqp instance list -o json | jq -r '.[] | select(.tags[]? == "production") | .id'
+# find instances that aren't ready
+cloudamqp instance list -o json | jq -r '.[] | select(.ready == false) | "\(.id) \(.name)"'
 
-# get all instance names and plans
-cloudamqp instance list -o json | jq -r '.[] | "\(.id) \(.name) \(.plan)"'
+# get IDs matching a tag
+cloudamqp instance list -o json | jq -r '.[] | select(.tags[]? == "staging") | .id'
 ```
 
 ## Create and capture instance ID
 
 ```bash
-RESULT=$(cloudamqp instance create --name=temp --plan=lemming --region=amazon-web-services::us-east-1 -o json)
+# fetch a valid plan and region first
+PLAN=$(cloudamqp plans --backend=rabbitmq -o json | jq -r '.[0].name')
+REGION=$(cloudamqp regions -o json | jq -r '.[0].id')
+
+RESULT=$(cloudamqp instance create --name=temp --plan="$PLAN" --region="$REGION" -o json)
 INSTANCE_ID=$(echo "$RESULT" | jq -r '.id')
-echo "Created instance: $INSTANCE_ID"
 ```
 
 ## Wait for instance readiness
 
-Use the built-in `--wait` flag (default timeout: 15 minutes):
+Prefer the built-in flag:
 
 ```bash
-cloudamqp instance create --name=my-instance --plan=bunny-1 \
-  --region=amazon-web-services::us-east-1 --wait --wait-timeout=20m
+cloudamqp instance create --name=my-instance --plan=<plan> --region=<region> --wait --wait-timeout=20m
 ```
 
 Or poll manually:
@@ -42,27 +44,18 @@ while true; do
 done
 ```
 
-## Skip confirmations
-
-Use `--force` on destructive commands:
+## Skip confirmations in scripts
 
 ```bash
-cloudamqp instance delete --id 1234 --force
-```
-
-## Environment-based configuration
-
-```bash
-export CLOUDAMQP_APIKEY="your-api-key"
-cloudamqp instance list  # no prompts
+cloudamqp instance delete --id <id> --force
+cloudamqp vpc delete --id <id> --force
 ```
 
 ## Batch operations
 
 ```bash
 # restart all instances tagged "staging"
 for ID in $(cloudamqp instance list -o json | jq -r '.[] | select(.tags[]? == "staging") | .id'); do
-  echo "Restarting instance $ID"
   cloudamqp instance restart-rabbitmq --id "$ID"
 done
 ```
@@ -72,9 +65,11 @@ done
 ```bash
 cloudamqp instance create \
   --name=staging-copy \
-  --plan=bunny-1 \
-  --region=amazon-web-services::us-east-1 \
-  --copy-from-id=1234 \
+  --plan=<plan> \
+  --region=<region> \
+  --copy-from-id=<source-id> \
   --copy-settings=alarms,metrics,logs,firewall,config,definitions,plugins \
   --wait
 ```
+
+Only works between dedicated instances (not shared plans).