| name | buttondown-cli |
| description | Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. MANDATORY: Execute Buttondown operations using the `buttondown` CLI tool. Manage Buttondown subscribers, emails (including rendered HTML), tags, RSS-to-email feeds, event-driven automations, multi-newsletter authentication profiles, and cache through the Buttondown REST API. Triggers: buttondown, buttondown cli, buttondown subscribers, buttondown emails, buttondown tags, buttondown feeds, buttondown automations, buttondown render, list buttondown subscribers, create buttondown email, manage buttondown tags, buttondown rss, buttondown rss-to-email, buttondown external feed, buttondown automation, render buttondown email, my buttondown, buttondown newsletter data, buttondown profile, atalearning, psforsysadmins, brickbuddybeta |
Execute Buttondown operations using the `buttondown` CLI. All Buttondown API interactions should use this CLI.
<quick_start>
The buttondown CLI follows this pattern:
buttondown [--profile NAME] <command-group> <action> [arguments] [options]
| Task | Command |
|---|
| Check authentication | buttondown auth status |
| List profiles | buttondown auth profiles list --table |
| Create or switch profiles | buttondown auth profiles create PROFILE |
| Use a specific newsletter | buttondown --profile atalearning emails list |
| List subscribers | buttondown subscribers list --limit 25 |
| Get a subscriber | buttondown subscribers get SUBSCRIBER_ID_OR_EMAIL |
| Create a draft email | buttondown emails create --subject "Subject" --body-file ./draft.md |
| List draft emails | buttondown emails list --filter "status:eq:draft" |
| Render an email as HTML | buttondown --profile atalearning emails render EMAIL_ID --output /tmp/email.html |
| Preview an email in browser | buttondown --profile atalearning emails render EMAIL_ID --open |
| List RSS feeds | buttondown --profile atalearning feeds list --table |
| Inspect an RSS feed | buttondown --profile atalearning feeds get FEED_ID |
| List automations | buttondown --profile atalearning automations list --table |
| Inspect an automation | buttondown --profile atalearning automations get AUTOMATION_ID |
| List tags | buttondown tags list --table |
| Get tag analytics | buttondown tags analytics TAG_ID |
| </quick_start> | |
**MANDATORY: Consult the adjacent `usage.json` at `/_repo/skills/-cli/usage.json` before executing ANY `buttondown` command.**
This file contains complete command syntax, all arguments, all options, and usage instructions for every command. Never guess at command syntax.
- **auth** -- Login, logout, status, auth tests, and nested `auth profiles` management.
- **cache** -- Clear cached Buttondown CLI responses.
- **automations** -- List, get, create, update, and delete event-driven automations (e.g., welcome sequences triggered by `subscriber.confirmed`). Requires the newsletter's `automations` feature.
- **emails** -- List, get, create, update, delete, send draft, and render emails (HTML for inbox or web archive).
- **feeds** -- List, get, create, update, and delete RSS-to-email external feeds. Requires the newsletter's `rss` feature.
- **subscribers** -- List, get, create, update, delete, send magic links, and send reminders.
- **tags** -- List, get, create, update, delete, and inspect tag analytics.
`feeds` and `automations` are per-newsletter features. The CLI refuses to run them under a profile whose newsletter lacks the feature and prints the enabled_features list. Never guess which profile to use — call `buttondown auth profiles list --table` first, then pick the profile whose newsletter has the required feature.
<reference_index>
usage.json -- Complete command tree with arguments, options, defaults, and usage instructions for every command.
</reference_index>
<domain_knowledge>
Context: Applies when maintaining or extending buttondown subscribers list, buttondown emails list, or buttondown tags list.
Key Facts: The Buttondown OpenAPI spec exposes page_size for /tags, but not for /subscribers or /emails. Keep page_size scoped to tags. Subscribers and emails should use the documented paginated response next link and stop after the requested --limit.
Gotchas: Do not add undocumented limit or page_size query parameters to subscribers or emails unless the OpenAPI spec changes.
**Context:** The Buttondown account backing this CLI has multiple newsletters, each with its own per-newsletter API key. Use `--profile NAME` to target a specific newsletter.
**Key Facts:**
- Each `.env.NAME` file holds the API key for one newsletter.
- `buttondown auth profiles list --table` shows the available profiles.
- `/v1/accounts/me` returns the username scoped to a given API key; `/v1/newsletters` lists every newsletter visible to the key together with its `enabled_features`.
- Real newsletter profiles configured by default: `atalearning` (rss + automations), `psforsysadmins`, `brickbuddybeta` (archives/portal/api/tags/metadata only).
**Gotchas:** The bare `default` profile key may be scoped to a newsletter with limited features — if a feature gate fires, pass `--profile atalearning` (or another feature-enabled profile) explicitly.
**Context:** These features live behind separate REST endpoints that only respond when the newsletter has the matching feature flag.
**Key Facts:**
- RSS feeds: `/v1/external_feeds` (list/create) and `/v1/external_feeds/{id}` (get/patch/delete). Feed IDs start with `rss_`. Feed schema: `url`, `cadence` (every|daily|weekly|monthly), `behavior` (draft|emails), `cadence_metadata`, `filters` (FilterGroup object), `subject`, `body`, `label`, `metadata`, `skip_old_items`, `status` (active|failing|inactive|deleted).
- Automations: `/v1/automations`, `/v1/automations/{id}`. Automation IDs start with `aut_`. Schema: `name`, `trigger` (e.g., `subscriber.confirmed`, `email.sent`, etc.), `actions[]` (each has `type`, `metadata.email_id`, `timing.time`, `timing.delay`), `filters` (FilterGroup), `status` (active|inactive), `metadata`, `should_evaluate_filter_after_delay`.
- Required newsletter features: `rss` for `feeds`, `automations` for `automations`.
**Gotchas:** The endpoint path is `external_feeds` (underscore), NOT `rss-feeds`, `feeds`, or `rss`. Creating an RSS feed requires a non-null `filters` object like `{"filters":[],"groups":[],"predicate":"and"}`.
**Context:** The `emails render` command returns fully rendered HTML from Buttondown's render endpoint. Works for drafts, scheduled, sent, and RSS-managed emails.
**Key Facts:**
- Endpoint: `GET /v1/emails/{id}/renders?target=email|html`.
- `--target email` returns the inbox-inlined rendering; `--target html` returns the web archive rendering. Both are fetched from the same endpoint with different query params.
- `--output FILE` writes to file; `--open` writes to a temp file and opens it in the default browser via `open`; neither prints the HTML to stdout.
- The command fails loudly on 404 / 403 / 400. There is no fallback to scraping `absolute_url`.
<success_criteria>
- Command executes without error
- Output is displayed in requested format
- Correct command and flags used (verified against usage.json)
- For
feeds / automations, the chosen --profile has the matching feature enabled
</success_criteria>
