| name | cli-reference |
| description | Reference and lightweight wrapper for the official Buttondown CLI (github.com/buttondown/cli). Use when the user prefers CLI operations over raw API calls — sending drafts, listing subscribers, managing emails from the terminal. Resolves the API key for the active newsletter. |
CLI Reference
Upstream: https://github.com/buttondown/cli
Detect
command -v buttondown >/dev/null && buttondown --version
If not installed, point the user at the upstream README for install instructions (it changes — don't hardcode here).
Auth (multi-newsletter)
The CLI reads the API key from the env var documented upstream. Pick the right newsletter, resolve its api_key_ref, then export:
DATA_ROOT="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/buttondown-mgmt"
SLUG="<newsletter-slug>"
REF=$(jq -r ".newsletters.\"$SLUG\".api_key_ref" "$DATA_ROOT/config.json")
export BUTTONDOWN_API_KEY="$(op read "$REF")"
Always print which newsletter the env was set for before running CLI commands so the user can catch a wrong-newsletter mistake.
Usage
Before constructing any CLI invocation, consult the cached docs (docs-lookup skill) for current command syntax — the CLI evolves.
Common operations:
- List recent emails / drafts
- Create a draft from a local markdown file in the newsletter's
user_dir
- Send a draft (confirm first)
- List or export subscribers
