beehiiv

Beehiiv API v2 skill for managing newsletter posts and drafts. All commands go through a single entry point: node <base_directory>/beehiiv.js <command> [flags]. Each command has its own doc file with the full reference for flags and behavior.

[!SETUP] Before first use, check whether <base_directory>/node_modules exists. If it does NOT exist, run npm install --prefix <base_directory>. Then check whether <base_directory>/dist/beehiiv.js exists. If it does NOT exist, run npm run build --prefix <base_directory>. NEVER cd into the skill directory; use --prefix to target it without changing your working directory.

[!COMMANDS]

Reading: a) publications — list all publications associated with the API key. @docs/publications.md. b) publication — get a single publication's details and stats. @docs/publication.md. c) posts — list posts with filters (status, tags, authors, audience, platform). This is the primary search mechanism. @docs/posts.md. d) get — retrieve a single post by ID with full HTML content. @docs/get.md.

Writing: e) draft — create a draft post from a title + optional .md/.html file. Enterprise-only endpoint (beta). @docs/draft.md.

Utility: f) templates — list available post templates. @docs/templates.md.

[!CREDENTIALS] One variable is REQUIRED: BEEHIIV_API_KEY. One variable is OPTIONAL: BEEHIIV_PUBLICATION_ID (default publication — if set, commands use it automatically; if not, pass --pub-id <id>). They resolve from the first source that provides them: a) .env.local in cwd, b) .env in cwd, c) .env.local in the plugin directory, d) .env in the plugin directory, e) environment variables. Obtain the API key from the Beehiiv dashboard (Settings > Integrations > API).