Sync your Beehiiv audience to a local database and answer growth questions offline in one command.
Beehiiv-pp-cli mirrors publications, subscribers, segments, posts, podcasts, and more into SQLite. Insights commands compute source attribution, churn sources, send-time performance, and cross-publication comparisons with zero API calls. The full v2 surface, including 2026-09 additions like podcasts, exports, and complimentary access, ships as typed commands with dry-run and agent output.
Authentication
Create an API key at app.beehiiv.com (Settings > API Keys) and export BEEHIIV_API_KEY. The key is a bearer token scoped to your organization; 180 requests per minute are shared per org.
Quick Start
# Verify the binary and auth wiring without calling the API
beehiiv-pp-cli doctor --dry-run
# Mirror the growth-critical entities into local SQLite
beehiiv-pp-cli sync --resources publications,subscriptions,posts --max-pages 50
# Full-text search across synced posts offline
beehiiv-pp-cli search "welcome" --type posts --limit 5
# One-command health snapshot computed from the local store
beehiiv-pp-cli insights growth-summary pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7
Unique Features
These capabilities aren't available in any other tool for this API.
Growth answers from the local store
-
insights subscriber-sources — See exactly where new subscribers come from: UTM, channel, and referring site, grouped in one call.
Reach for this when a growth question needs source attribution without paging the full subscriber list through the API.
beehiiv-pp-cli insights subscriber-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
-
insights post-performance — Review recent sends with status, timing, and expanded stats in one compact table.
Reach for this after a send to review performance without burning per-post API calls.
beehiiv-pp-cli insights post-performance pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 10 --agent
-
insights referral-health — Check referral-program config and how many subscribers actually carry referral codes.
Reach for this when tuning referral loops to see configuration versus real coverage.
beehiiv-pp-cli insights referral-health pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
-
insights subscriber-lookup — Find one subscriber by email or subscription ID and get a compact record instantly.
Reach for this for support questions about a single subscriber when offline speed matters.
beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 reader@example.com --agent --select subscription.email,subscription.status
-
insights churn-sources — See which sources, channels, and campaigns drive unsubscribes.
Reach for this when unsubscribes spike and you need the offending channel fast.
beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
-
insights send-times — Find your best send slot: open rate by weekday and hour from your own history.
Reach for this when scheduling the next send and you want evidence over habit.
beehiiv-pp-cli insights send-times pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
-
insights compare-publications — Side-by-side growth and engagement across every synced publication.
Reach for this when managing several publications and a client report needs one comparison table.
beehiiv-pp-cli insights compare-publications --agent --select publications.name,publications.net_growth
Recipes
Mirror the audience
beehiiv-pp-cli sync --resources publications,subscriptions,segments,posts --max-pages 100
Cursor-paginated sync of the four growth-critical entities into SQLite.
Agent-ready growth snapshot
beehiiv-pp-cli insights growth-summary pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
Single read-only health summary computed from the local store.
Narrow a deep lookup
beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 reader@example.com --agent --select subscription.email,subscription.status
Pair --agent with --select dotted paths to return only the fields an agent needs.
Attribute a churn spike
beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20
Group unsubscribes by source, channel, UTM, and referrer offline.
Ship a subscriber CSV
beehiiv-pp-cli search "@example.com" --type subscriptions --limit 1000 --csv > subscribers.csv
Every list and search command emits CSV for spreadsheets.
Usage
Run beehiiv-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
BEEHIIV_CONFIG_DIR, BEEHIIV_DATA_DIR, BEEHIIV_STATE_DIR, or BEEHIIV_CACHE_DIR
--home <dir> for this invocationBEEHIIV_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export BEEHIIV_HOME=/srv/beehiiv
beehiiv-pp-cli doctor
Under BEEHIIV_HOME=/srv/beehiiv, the four dirs resolve to /srv/beehiiv/config, /srv/beehiiv/data, /srv/beehiiv/state, and /srv/beehiiv/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"beehiiv": {
"command": "beehiiv-pp-mcp",
"env": {
"BEEHIIV_HOME": "/srv/beehiiv"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as BEEHIIV_DATA_DIR overrides an explicit --home for that kind. Use BEEHIIV_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting BEEHIIV_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run beehiiv-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
advertisement-opportunities
Manage advertisement opportunities
beehiiv-pp-cli advertisement-opportunities <publicationId> - Get advertisement opportunities OAuth Scope: posts:read
authors
Manage authors
beehiiv-pp-cli authors index - Retrieve a list of authors available for the publication.beehiiv-pp-cli authors show - Retrieve a single author from a publication.
automations
Manage automations
beehiiv-pp-cli automations index - List automations OAuth Scope: automations:readbeehiiv-pp-cli automations show - Get automation OAuth Scope: automations:read
bulk-subscription-updates
Manage bulk subscription updates
beehiiv-pp-cli bulk-subscription-updates index - List subscription updates OAuth Scope: subscriptions:readbeehiiv-pp-cli bulk-subscription-updates show - Get subscription update OAuth Scope: subscriptions:read
bulk-subscriptions
Manage bulk subscriptions
beehiiv-pp-cli bulk-subscriptions <publicationId> - Bulk create subscription OAuth Scope: subscriptions:write
complimentary-access
Manage complimentary access
beehiiv-pp-cli complimentary-access index - Retrieve complimentary access objects for the publication.beehiiv-pp-cli complimentary-access show - Retrieve a single complimentary access object.
condition-sets
Manage condition sets
beehiiv-pp-cli condition-sets index - Retrieve all active condition sets for a publication. Condition sets define reusable audience segments for targeting content to specific subscribers. Use the purpose parameter to filter by a specific use case.beehiiv-pp-cli condition-sets show - Retrieve a single active dynamic content condition set for a publication. Use expand[]=stats to calculate and return the active subscriber count synchronously.
custom-fields
Manage custom fields
beehiiv-pp-cli custom-fields create - Create custom field OAuth Scope: custom_fields:writebeehiiv-pp-cli custom-fields delete - Delete custom field OAuth Scope: custom_fields:writebeehiiv-pp-cli custom-fields index - List custom fields OAuth Scope: custom_fields:readbeehiiv-pp-cli custom-fields patch - Update custom field OAuth Scope: custom_fields:writebeehiiv-pp-cli custom-fields put - Update custom field OAuth Scope: custom_fields:writebeehiiv-pp-cli custom-fields show - Get custom field OAuth Scope: custom_fields:read
data-privacy
Manage data privacy
beehiiv-pp-cli data-privacy data-deletion-create - This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.
Creates a data deletion request for a subscriber within your organization. The subscriber's data will be redacted from all publications in the organization after a 14-day safety delay. This action cannot be undone once processing begins.
beehiiv-pp-cli data-privacy data-deletion-index - This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.
List all data deletion requests for your organization.
beehiiv-pp-cli data-privacy data-deletion-show - This is a gated feature that requires enablement. Contact support to enable Data Deletion API access for your organization.
Retrieve the details and current status of a specific data deletion request.
email-blasts
Manage email blasts
beehiiv-pp-cli email-blasts index - List email blasts OAuth Scope: posts:readbeehiiv-pp-cli email-blasts show - Get email blast OAuth Scope: posts:read
engagements
Manage engagements
beehiiv-pp-cli engagements <publicationId> - Retrieve email engagement metrics for a specific publication over a defined date range and granularity. By default, the endpoint returns metrics for the past day, aggregated daily. The max number of days allowed is 31. All dates and times are in UTC.
exports
Manage exports
beehiiv-pp-cli exports subscription-create - Start a subscription export. Returns an existing in-progress export instead of starting a duplicate.beehiiv-pp-cli exports subscription-index - List subscription exports for the publication, newest first.beehiiv-pp-cli exports subscription-show - Get a subscription export. Poll until status is completed, then read download_url. Gated feature requiring enablement.
newsletter-lists
Manage newsletter lists
beehiiv-pp-cli newsletter-lists index -
Newsletter Lists is currently in beta, the API is subject to change.
List all newsletter lists for a publication.
beehiiv-pp-cli newsletter-lists show -
Newsletter Lists is currently in beta, the API is subject to change.
Retrieve a single newsletter list belonging to a specific publication.
podcasts
Manage podcasts
beehiiv-pp-cli podcasts index - List podcasts for the publication.beehiiv-pp-cli podcasts show - Retrieve a single podcast.
polls
Manage polls
beehiiv-pp-cli polls index - Retrieve all polls belonging to a specific publication. Poll choices are always included. Use expand[]=stats to include aggregate vote counts per choice.beehiiv-pp-cli polls show - Retrieve detailed information about a specific poll belonging to a publication. Use expand[]=stats for aggregate vote counts, or expand[]=poll_responses for individual subscriber responses.
post-templates
Manage post templates
beehiiv-pp-cli post-templates <publicationId> - Retrieve a list of post templates available for the publication.
posts
Manage posts
beehiiv-pp-cli posts aggregate-stats - Get aggregate stats OAuth Scope: posts:readbeehiiv-pp-cli posts create -
This feature is currently in beta, the API is subject to change, and available only to Enterprise users.To inquire about Enterprise pricing,
please visit our Enterprise page.
Create a post for a specific publication. For a detailed walkthrough including setup, testing workflows, and working with custom HTML and templates, see the Using the Send API and Create Post Endpoint guide.
Content methods
There are three ways to provide content for a post. You must provide either blocks or body_content, but not both.
1. Blocks
Use the blocks field to build your post with structured content blocks such as paragraphs, images, headings, buttons, tables, and more. Each block has a type and its own set of properties. This method gives you fine-grained control over individual content elements and supports features like visual settings, visibility settings, and dynamic content targeting.
2. Raw HTML (body_content)
Use the body_content field to provide a single string of raw HTML. The HTML is wrapped in an htmlSnippet block internally. This is useful when you have pre-built HTML content or are migrating from another platform.
3. HTML blocks within blocks
Use type: html blocks inside the blocks array to embed raw HTML snippets alongside other structured blocks. This lets you mix structured content (paragraphs, images, etc.) with custom HTML where needed.
CSS and styling guardrails
beehiiv processes all HTML content through a sanitization pipeline. When using body_content or html blocks, be aware of the following:
<style> tags are removed. All <style> block elements are stripped during sanitization. Do not rely on embedded stylesheets.<link> tags are removed. External stylesheet references are not allowed.- Inline styles are preserved. Styles applied directly to elements via the
style attribute (e.g., <div style="color: red;">) are kept intact.
- CSS classes have no effect. While class attributes are not stripped, no corresponding stylesheets are loaded to apply them.
- beehiiv's email template wraps your content. Your HTML is rendered inside beehiiv's email table structure, which applies its own layout and spacing. This may affect the appearance of your content.
- Use inline styles for all visual styling. Since
<style> and <link> tags are removed, inline styles on individual elements are the only reliable way to control appearance.
beehiiv-pp-cli posts delete - Delete or Archive a post. Any post that has been confirmed will have it's status changed to archived. Posts in the draft status will be permanently deleted.beehiiv-pp-cli posts index - List posts OAuth Scope: posts:readbeehiiv-pp-cli posts show - Get post OAuth Scope: posts:readbeehiiv-pp-cli posts update -
This feature is currently in beta, the API is subject to change, and available only to Enterprise users.To inquire about Enterprise pricing,
please visit our Enterprise page.
Update an existing post for a specific publication. Only the fields provided in the request body will be updated — all other fields remain unchanged. For a detailed walkthrough of content methods and working with custom HTML, see the Using the Send API and Create Post Endpoint guide.
To update post content, provide either blocks or body_content (not both). If neither is provided, the existing content is preserved. The same content methods and CSS guardrails described in the create endpoint apply here.
publications
Manage publications
beehiiv-pp-cli publications index - List publications OAuth Scope: publications:readbeehiiv-pp-cli publications show - Get publication OAuth Scope: publications:read
referral-program
Manage referral program
beehiiv-pp-cli referral-program <publicationId> - Get referral program OAuth Scope: referral_program:read
segments
Manage segments
beehiiv-pp-cli segments create - Create a new segment. Manual segments — Use subscriptions or emails input to create a segment from an explicit list of subscription IDs or email addresses. The segment is processed synchronously and returns with status: completed. Net new email addresses will be ignored; create subscriptions using the Create Subscription endpoint. Dynamic segments — Use custom_fields input to create a segment that filters subscribers by custom field values. The segment is processed asynchronously and returns with status: pending. Results will be available in the List Segment Subscribers endpoint after processing is complete.beehiiv-pp-cli segments delete - Delete a segment. Deleting the segment does not effect the subscriptions in the segment.beehiiv-pp-cli segments index - List segments OAuth Scope: segments:readbeehiiv-pp-cli segments show - Get segment OAuth Scope: segments:read
subscriptions
Manage subscriptions
beehiiv-pp-cli subscriptions bulk-updates-patch - Update subscriptions OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions bulk-updates-patch-status - Update subscriptions' status OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions bulk-updates-put - Update subscriptions OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions bulk-updates-put-status - Update subscriptions' status OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions create - Create subscription OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions delete - This cannot be undone. All data associated with the subscription will also be deleted. We recommend unsubscribing when possible instead of deleting. If a premium subscription is deleted they will no longer be billed. Deletes a subscription.beehiiv-pp-cli subscriptions get-by-email - Please note that this endpoint requires the email to be URL encoded. Please reference your language's documentation for the correct method of encoding. Retrieve a single subscription belonging to a specific email address in a specific publication.beehiiv-pp-cli subscriptions get-by-id - In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID. This endpoint is now deprecated and will be removed in a future version of the API. Please use this endpoint instead. The subscription ID can be found by exporting a list of subscriptions either via the Settings > Publications > Export Data or by exporting a CSV in a segment. Retrieve a single subscription belonging to a specific publication.beehiiv-pp-cli subscriptions get-by-subscriber-id - Get subscription by subscriber ID OAuth Scope: subscriptions:readbeehiiv-pp-cli subscriptions index - Retrieve all subscriptions belonging to a specific publication.
New: This endpoint now supports cursor-based pagination for better performance and consistency. Use the cursor parameter instead of page for new integrations.
Deprecation Notice: Offset-based pagination (using page parameter) is deprecated and limited to 100 pages maximum. Please migrate to cursor-based pagination. See our Pagination Guide for details.
beehiiv-pp-cli subscriptions patch - Update subscription by ID OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions put - Update subscription by ID OAuth Scope: subscriptions:writebeehiiv-pp-cli subscriptions update-by-email - Update subscription by email OAuth Scope: subscriptions:write
tiers
Manage tiers
beehiiv-pp-cli tiers create - Create a tier OAuth Scope: tiers:writebeehiiv-pp-cli tiers index - List tiers OAuth Scope: tiers:readbeehiiv-pp-cli tiers patch - Update a tier OAuth Scope: tiers:writebeehiiv-pp-cli tiers put - Update a tier OAuth Scope: tiers:writebeehiiv-pp-cli tiers show - Get tier OAuth Scope: tiers:read
users
Manage users
beehiiv-pp-cli users - Identify user OAuth Scope: identify:read
webhooks
Manage webhooks
beehiiv-pp-cli webhooks create - Create a webhook OAuth Scope: webhooks:writebeehiiv-pp-cli webhooks delete - Delete a webhook OAuth Scope: webhooks:writebeehiiv-pp-cli webhooks index - List webhooks OAuth Scope: webhooks:readbeehiiv-pp-cli webhooks show - Get webhook OAuth Scope: webhooks:readbeehiiv-pp-cli webhooks update - Update webhook OAuth Scope: webhooks:write
workspaces
Manage workspaces
beehiiv-pp-cli workspaces identify - Identify workspace OAuth Scope: identify:readbeehiiv-pp-cli workspaces permissions-show - Retrieve the permissions granted to the OAuth or API token for this workspace.beehiiv-pp-cli workspaces publications-by-subscription-email - Retrieve all publications in the workspace that have a subscription for the specified email address. The workspace is determined by the provided API key.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
beehiiv-pp-cli recall <query> - Look up cached resources for a query before running discoverybeehiiv-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)beehiiv-pp-cli learnings list - Inspect taught rowsbeehiiv-pp-cli learnings forget <query> - Undo a teachbeehiiv-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectbeehiiv-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsbeehiiv-pp-cli teach-pattern - Install a query/resource template up frontbeehiiv-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set BEEHIIV_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of beehiiv-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
beehiiv-pp-cli advertisement-opportunities mock-value
# JSON for scripting and agents
beehiiv-pp-cli advertisement-opportunities mock-value --json
# Filter to specific fields
beehiiv-pp-cli advertisement-opportunities mock-value --json --select advertisement_kind,advertiser_name,id
# Dry run — show the request without sending
beehiiv-pp-cli advertisement-opportunities mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
beehiiv-pp-cli advertisement-opportunities mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
beehiiv-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run beehiiv-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/beehiiv-pp-cli/config.toml; --home, BEEHIIV_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
BEEHIIV_API_KEY | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, beehiiv-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
beehiiv-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $BEEHIIV_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 INVALID_API_KEY on every call — export BEEHIIV_API_KEY=
- 429 Too Many Requests — The CLI applies adaptive backoff; wait for the Retry-After window and reduce concurrent jobs
- List endpoints cap at page 100 — Use cursor pagination; the CLI sync already prefers cursor tokens
- Export download_url is null — Poll beehiiv-pp-cli exports subscription-show until status is completed, then read download_url
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press