Pp Beehiiv
Apps & Automationpp-beehiivPp Beehiiv is an Agent Skill for apps & automation published in the mvanhorn/printing-press-library repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Printing Press CLI for Beehiiv.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/mvanhorn/printing-press-library/blob/HEAD/cli-skills/pp-beehiiv/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/pp-beehiiv, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Beehiiv — Printing Press CLI
Prerequisites: Install the CLI
This skill drives the beehiiv-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/binon macOS/Linux and%LOCALAPPDATA%\Programs\PrintingPress\binon Windows:npx -y @mvanhorn/printing-press-library install beehiiv --cli-only - Verify:
beehiiv-pp-cli --version - Ensure the reported install directory is on
$PATHfor the agent/runtime that will invoke this skill.
If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer):
go install github.com/mvanhorn/printing-press-library/library/marketing/beehiiv/cmd/beehiiv-pp-cli@latest
If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.
Unique Capabilities
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 [email protected] --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
Command Reference
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
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...beehiiv-pp-cli condition-sets show— Retrieve a single active dynamic content condition set for a publication. Useexpand[]=statsto calculate and...
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...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...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...
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...
newsletter-lists — Manage newsletter lists
beehiiv-pp-cli newsletter-lists index— Newsletter Lists is currently in beta, the API is subject to change....beehiiv-pp-cli newsletter-lists show— Newsletter Lists is currently in beta, the API is subject to change....
polls — Manage polls
beehiiv-pp-cli polls index— Retrieve all polls belonging to a specific publication. Poll choices are always included. Useexpand[]=statsto...beehiiv-pp-cli polls show— Retrieve detailed information about a specific poll belonging to a publication. Useexpand[]=statsfor aggregate...
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...beehiiv-pp-cli posts delete— Delete or Archive a post. Any post that has been confirmed will have it's status changed toarchived. Posts in the...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...
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 — Usesubscriptionsoremailsinput to create a segment from...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...beehiiv-pp-cli subscriptions get-by-email— Please note that this endpoint requires the email to be URL encoded. Please reference your language's...beehiiv-pp-cli subscriptions get-by-id— In previous versions of the API, another endpoint existed to retrieve a subscription by the subscriber ID....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...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 publications-by-subscription-email— Retrieve all publications in the workspace that have a subscription for the specified email address. The workspace...
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
beehiiv-pp-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.
Auth Setup
Store your access token:
beehiiv-pp-cli auth set-token YOUR_TOKEN_HERE
Or set BEEHIIV_BEARER_AUTH as an environment variable.
Run beehiiv-pp-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
-
Pipeable — JSON on stdout, errors on stderr
-
Filterable —
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:beehiiv-pp-cli advertisement-opportunities mock-value --agent --select id,name,status -
Previewable —
--dry-runshows the request without sending -
Offline-friendly — sync/search commands can use the local SQLite store when available
-
Non-interactive — never prompts, every input is a flag
-
Explicit retries — use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
beehiiv-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
beehiiv-pp-cli feedback --stdin < notes.txt
beehiiv-pp-cli feedback list --json --limit 10
Entries are stored locally at ~/.beehiiv-pp-cli/feedback.jsonl. They are never POSTed unless BEEHIIV_FEEDBACK_ENDPOINT is set AND either --send is passed or BEEHIIV_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout | Default; write to stdout only |
file:<path> | Atomically write output to <path> (tmp + rename) |
webhook:<url> | POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
beehiiv-pp-cli profile save briefing --json
beehiiv-pp-cli --profile briefing advertisement-opportunities mock-value
beehiiv-pp-cli profile list --json
beehiiv-pp-cli profile show briefing
beehiiv-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or--help→ showbeehiiv-pp-cli --helpoutput - Starts with
install→ ends withmcp→ MCP installation; otherwise → see Prerequisites above - Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
claude mcp add beehiiv-pp-mcp -- beehiiv-pp-mcp
Verify: claude mcp list
Direct Use
- Check if installed:
which beehiiv-pp-cliIf not found, offer to install (see Prerequisites at the top of this skill). - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agentflag:beehiiv-pp-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help:
beehiiv-pp-cli <command> --help.