Skip to content

Commit 85c0135

Browse files
jamie-at-bunnyjamie-at-bunny
committed
add basic skills
1 parent 43601cb commit 85c0135

4 files changed

Lines changed: 502 additions & 0 deletions

File tree

‎skills/bunny-cli/SKILL.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
name: bunny-cli
3+
description: Manage bunny.net resources from the command line — databases, authentication, and raw API requests
4+
---
5+
6+
# Bunny CLI Skill
7+
8+
The Bunny CLI (`bunny`) manages bunny.net resources from the command line. Use `bunny <command> --help` for full flag details on any command.
9+
10+
## Critical: Authentication
11+
12+
Commands require an API key. Authenticate first with `bunny auth login`, which opens a browser-based OAuth flow and stores the key in a local profile. Alternatively, set `BUNNYNET_API_KEY` as an environment variable or pass `--api-key` directly.
13+
14+
Config is stored in (first match wins):
15+
16+
- `$XDG_CONFIG_HOME/bunnynet.json`
17+
- `~/.config/bunnynet.json`
18+
- `~/.bunnynet.json`
19+
- `/etc/bunnynet.json`
20+
21+
**When something goes wrong, check auth first** — run a quick `bunny api GET /user` to verify your key works. If using profiles, confirm the right one is active with `--profile`.
22+
23+
## Quick Start
24+
25+
```bash
26+
# authenticate
27+
bunny auth login
28+
29+
# make a raw API request
30+
bunny api GET /pullzone
31+
bunny api GET /user
32+
33+
# manage databases
34+
bunny db create
35+
bunny db list
36+
bunny db shell
37+
```
38+
39+
## Decision Tree
40+
41+
Use this to route to the correct reference file:
42+
43+
- **Authenticate or switch profiles** -> `references/auth.md`
44+
- **Database management (create, list, show, delete, shell, regions, tokens)** -> `references/database.md`
45+
- **Make raw API requests** -> `references/api.md`
46+
- **CLI doesn't have a command for it** -> use `bunny api` as a fallback (see `references/api.md`)
47+
48+
## Global Flags
49+
50+
Available on every command:
51+
52+
| Flag | Short | Default | Description |
53+
| ----------- | ----- | --------- | --------------------------------------------------------- |
54+
| `--profile` | `-p` | `default` | Configuration profile to use |
55+
| `--verbose` | `-v` | `false` | Enable verbose/debug output |
56+
| `--output` | `-o` | `text` | Output format: `text`, `json`, `table`, `csv`, `markdown` |
57+
| `--api-key` | | | API key (takes priority over profile and env) |
58+
59+
## Environment Variables
60+
61+
| Variable | Description |
62+
| ------------------------ | ---------------------------------------------------------------- |
63+
| `BUNNYNET_API_KEY` | API key (overrides profile) |
64+
| `BUNNYNET_API_URL` | API base URL (default: `https://api.bunny.net`) |
65+
| `BUNNYNET_DASHBOARD_URL` | Dashboard URL for OAuth flow (default: `https://dash.bunny.net`) |
66+
| `NO_COLOR` | Disable colored output |
67+
68+
## Anti-Patterns
69+
70+
- **Forgetting to authenticate**: Run `bunny auth login` first. Without it, commands fail with a missing API key error. Use `bunny api GET /user` to verify.
71+
- **Hardcoding API keys in scripts**: Use `BUNNYNET_API_KEY` env var or `--api-key` flag instead of embedding keys. Better yet, use `bunny auth login` profiles.
72+
- **Forgetting `--force` in CI/CD**: Interactive prompts block in non-TTY environments. Use `--force` to skip confirmations in automated pipelines.

‎skills/bunny-cli/references/api.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# API Command
2+
3+
## `bunny api` — Make raw authenticated API requests
4+
5+
**Use `bunny api` when a CLI command doesn't exist for what you need.** Provides direct access to the bunny.net REST API with automatic authentication.
6+
7+
```bash
8+
bunny api GET /user # get current user
9+
bunny api GET /pullzone # list pull zones
10+
bunny api GET /database/v2/databases # list databases
11+
bunny api POST /database/v2/databases --body '{"name":"test","storage_region":"DE","primary_regions":["DE"]}'
12+
bunny api DELETE /dnszone/12345 # delete a resource
13+
```
14+
15+
## Syntax
16+
17+
```
18+
bunny api METHOD PATH [--body BODY]
19+
```
20+
21+
### Positional Arguments
22+
23+
| Argument | Required | Description |
24+
| -------- | -------- | --------------------------------------------------------------- |
25+
| `METHOD` | Yes | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
26+
| `PATH` | Yes | API endpoint path (e.g., `/pullzone`, `/database/v2/databases`) |
27+
28+
### Flags
29+
30+
| Flag | Short | Description |
31+
| -------- | ----- | ----------------- |
32+
| `--body` | `-b` | JSON request body |
33+
34+
## Request Body
35+
36+
The body can come from three sources (in priority order):
37+
38+
1. `--body` flag: `bunny api POST /path --body '{"key":"value"}'`
39+
2. STDIN (if not a TTY and method is not GET): `echo '{"key":"value"}' | bunny api POST /path`
40+
3. No body (default for GET requests)
41+
42+
The body must be valid JSON — the command validates it before sending.
43+
44+
## Headers
45+
46+
All requests automatically include:
47+
48+
- `AccessKey: {apiKey}` — from profile or `--api-key` flag
49+
- `User-Agent: bunny-cli/{VERSION}`
50+
- `Accept: application/json`
51+
- `Content-Type: application/json` (when body is provided)
52+
53+
## Output
54+
55+
- Always outputs JSON (pretty-printed with 2-space indent)
56+
- On error: extracts message from response fields (`detail`, `Message`, `title`) or falls back to HTTP status text
57+
- In verbose mode (`-v`): logs the request method, URL, body, and response status
58+
59+
## Examples
60+
61+
```bash
62+
# List all pull zones
63+
bunny api GET /pullzone
64+
65+
# Get a specific pull zone
66+
bunny api GET /pullzone/12345
67+
68+
# Create a DNS zone
69+
bunny api POST /dnszone --body '{"Domain":"example.com"}'
70+
71+
# Pipe body from a file
72+
cat payload.json | bunny api POST /database/v2/databases
73+
74+
# Use with a specific profile
75+
bunny api GET /user -p staging
76+
77+
# Verbose mode to debug requests
78+
bunny api GET /pullzone -v
79+
```

‎skills/bunny-cli/references/auth.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Authentication
2+
3+
## `bunny auth login` — Browser-based OAuth login
4+
5+
Opens a browser to authenticate with bunny.net and stores the API key in a local profile.
6+
7+
```bash
8+
bunny auth login # interactive login, saves to "default" profile
9+
bunny auth login -p staging # save to "staging" profile
10+
bunny auth login --force # overwrite existing profile without confirmation
11+
```
12+
13+
### How it works
14+
15+
1. Starts a local HTTP server on a random port
16+
2. Opens `https://dash.bunny.net/auth/login` in the default browser
17+
3. Waits up to 5 minutes for the OAuth callback
18+
4. Extracts the API key and saves it to the profile
19+
5. Fetches user details and prints a welcome message
20+
21+
### Flags
22+
23+
| Flag | Default | Description |
24+
| --------- | ------- | ----------------------------------------------- |
25+
| `--force` | `false` | Overwrite existing profile without confirmation |
26+
27+
### Notes
28+
29+
- If the browser doesn't open automatically, the URL is printed to the terminal
30+
- Exits with an error if the profile already exists (use `--force` to overwrite)
31+
- Uses `BUNNYNET_DASHBOARD_URL` env var if set (default: `https://dash.bunny.net`)
32+
33+
---
34+
35+
## `bunny auth logout` — Remove a profile
36+
37+
Deletes the stored API key for a profile.
38+
39+
```bash
40+
bunny auth logout # remove "default" profile (with confirmation)
41+
bunny auth logout -p staging # remove "staging" profile
42+
bunny auth logout --force # skip confirmation prompt
43+
```
44+
45+
### Flags
46+
47+
| Flag | Default | Description |
48+
| --------- | ------- | ------------------------ |
49+
| `--force` | `false` | Skip confirmation prompt |
50+
51+
### Notes
52+
53+
- Errors if the profile doesn't exist
54+
- Prompts "Are you sure?" before deleting (bypassed with `--force`)
55+
56+
---
57+
58+
## Custom API Endpoint
59+
60+
The CLI defaults to `https://api.bunny.net` but supports custom endpoints for staging or internal environments.
61+
62+
**Via environment variable** (takes priority over profile config):
63+
64+
```bash
65+
BUNNYNET_API_URL=https://api.staging.bunny.net bunny api GET /user
66+
```
67+
68+
**Via profile config** (set `api_url` in `~/.config/bunnynet.json`):
69+
70+
```json
71+
{
72+
"profiles": {
73+
"staging": {
74+
"api_key": "...",
75+
"api_url": "https://api.staging.bunny.net"
76+
}
77+
}
78+
}
79+
```
80+
81+
```bash
82+
bunny --profile staging api GET /user
83+
```
84+
85+
**Precedence**: `BUNNYNET_API_URL` env var always wins over the profile's `api_url` field.
86+
87+
---
88+
89+
## Config Resolution Precedence
90+
91+
Authentication is resolved in this order (first wins):
92+
93+
1. `--api-key` flag
94+
2. `BUNNYNET_API_KEY` environment variable
95+
3. Profile from config file (via `--profile`, default: `default`)
96+
4. Built-in defaults (empty API key — commands will fail)
97+
98+
The API base URL is resolved separately:
99+
100+
1. `BUNNYNET_API_URL` environment variable
101+
2. `api_url` from the active profile
102+
3. Default: `https://api.bunny.net`

0 commit comments

Comments
 (0)