Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your access token from your API provider's developer portal, then store it:
beehiiv-pp-cli auth set-token YOUR_TOKEN_HERE
Or set it via environment variable:
export BEEHIIV_BEARER_AUTH="your-token-here"
3. Verify Setup
beehiiv-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
beehiiv-pp-cli advertisement-opportunities mock-value
Unique Features
These capabilities aren't available in any other tool for this API.
Publication intelligence
-
insights growth-summary — Summarize publication, subscriber, post, referral, and custom-field health in one read-only response.
Use this first when an agent needs a compact account-level picture before choosing a narrower Beehiiv endpoint.
beehiiv-pp-cli insights growth-summary pub_00000000-0000-0000-0000-000000000000 --agent
-
insights post-performance — List recent posts with status, audience, publish timing, and any available expanded stats.
Use this when an agent needs to inspect content output before drilling into one post.
beehiiv-pp-cli insights post-performance pub_00000000-0000-0000-0000-000000000000 --limit 25 --agent
Audience intelligence
-
insights subscriber-sources — Group subscribers by UTM, channel, and referring-site fields to see where audience growth is coming from.
Use this when the question is about acquisition channels rather than individual subscribers.
beehiiv-pp-cli insights subscriber-sources pub_00000000-0000-0000-0000-000000000000 --limit 100 --agent
-
insights field-coverage — Inspect custom-field definitions alongside subscriber sample size for enrichment planning.
Use this before importing, enriching, or auditing subscriber metadata.
beehiiv-pp-cli insights field-coverage pub_00000000-0000-0000-0000-000000000000 --agent
-
insights subscriber-lookup — Find one subscriber by email or subscription ID and return a compact subscriber record.
Use this when the task is about one subscriber and broad list calls would waste context.
beehiiv-pp-cli insights subscriber-lookup pub_00000000-0000-0000-0000-000000000000 --email reader@example.com --agent
Growth loops
-
insights referral-health — Summarize referral-program configuration and subscriber referral-code coverage.
Use this when an agent needs to check whether referral growth is configured and visible in subscriber data.
beehiiv-pp-cli insights referral-health pub_00000000-0000-0000-0000-000000000000 --agent
Usage
Run beehiiv-pp-cli --help for the full command reference and flag list.
Commands
advertisement-opportunities
Manage advertisement opportunities
beehiiv-pp-cli advertisement-opportunities index - 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 create - Bulk create subscription OAuth Scope: subscriptions:write
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 index - 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.
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.
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 index - 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 show - 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 oauth-identify - 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 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.
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 id,name,status
# 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 id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- 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
Config file: ~/.config/beehiiv-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
BEEHIIV_BEARER_AUTH | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
beehiiv-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $BEEHIIV_BEARER_AUTH
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press