---
name: pp-beehiiv
description: "Sync your Beehiiv audience to a local database and answer growth questions offline in one command. Trigger phrases: `check my beehiiv growth`, `subscriber sources`, `which send time works best`, `compare my publications`, `lookup subscriber email`, `use beehiiv`, `run beehiiv`."
author: "Kevin Magnan"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - beehiiv-pp-cli
---

# 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:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install beehiiv --cli-only
   ```
2. Verify: `beehiiv-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for 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.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
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.

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.

## When to Use This CLI

Use this CLI for offline audience analytics, bulk subscriber operations, scripting, and CI pipelines. Use it when you want agent-ready JSON output with select/compact/quiet modes and a local store that answers growth questions without API calls.

## Anti-triggers

Do not use this CLI for:
- Do not use this CLI for beehiv documentation search; use the official docs MCP at developers.beehiiv.com/_mcp/server
- Do not use this CLI for OAuth app authorization flows; it is an API-key client
- Creating a post with confirmed status and no scheduled_at publishes (sends) immediately; use --dry-run first to inspect the request

## Unique Capabilities

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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  beehiiv-pp-cli insights compare-publications --agent --select publications.name,publications.net_growth
  ```

## Command Reference

**advertisement-opportunities** — Manage advertisement opportunities

- `beehiiv-pp-cli advertisement-opportunities <publicationId>` — Get advertisement opportunities <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>

**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 <Badge intent='info' minimal outlined>OAuth Scope: automations:read</Badge>
- `beehiiv-pp-cli automations show` — Get automation <Badge intent='info' minimal outlined>OAuth Scope: automations:read</Badge>

**bulk-subscription-updates** — Manage bulk subscription updates

- `beehiiv-pp-cli bulk-subscription-updates index` — List subscription updates <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:read</Badge>
- `beehiiv-pp-cli bulk-subscription-updates show` — Get subscription update <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:read</Badge>

**bulk-subscriptions** — Manage bulk subscriptions

- `beehiiv-pp-cli bulk-subscriptions <publicationId>` — Bulk create subscription <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>

**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.
- `beehiiv-pp-cli condition-sets show` — Retrieve a single active dynamic content condition set for a publication.

**custom-fields** — Manage custom fields

- `beehiiv-pp-cli custom-fields create` — Create custom field <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:write</Badge>
- `beehiiv-pp-cli custom-fields delete` — Delete custom field <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:write</Badge>
- `beehiiv-pp-cli custom-fields index` — List custom fields <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:read</Badge>
- `beehiiv-pp-cli custom-fields patch` — Update custom field <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:write</Badge>
- `beehiiv-pp-cli custom-fields put` — Update custom field <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:write</Badge>
- `beehiiv-pp-cli custom-fields show` — Get custom field <Badge intent='info' minimal outlined>OAuth Scope: custom_fields:read</Badge>

**data-privacy** — Manage data privacy

- `beehiiv-pp-cli data-privacy data-deletion-create` — <Warning>This is a gated feature that requires enablement.
- `beehiiv-pp-cli data-privacy data-deletion-index` — <Warning>This is a gated feature that requires enablement.
- `beehiiv-pp-cli data-privacy data-deletion-show` — <Warning>This is a gated feature that requires enablement.

**email-blasts** — Manage email blasts

- `beehiiv-pp-cli email-blasts index` — List email blasts <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>
- `beehiiv-pp-cli email-blasts show` — Get email blast <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>

**engagements** — Manage engagements

- `beehiiv-pp-cli engagements <publicationId>` — Retrieve email engagement metrics for a specific publication over a defined date range and granularity.

**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` — <Note title='Currently in beta' icon='b'> Newsletter Lists is currently in beta, the API is subject to change.
- `beehiiv-pp-cli newsletter-lists show` — <Note title='Currently in beta' icon='b'> Newsletter Lists is currently in beta, the API is subject to change.

**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.
- `beehiiv-pp-cli polls show` — Retrieve detailed information about a specific poll belonging to a publication.

**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 <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>
- `beehiiv-pp-cli posts create` — <Note title='Currently in beta' icon='b'> This feature is currently in beta, the API is subject to change
- `beehiiv-pp-cli posts delete` — Delete or Archive a post. Any post that has been confirmed will have it's status changed to `archived`.
- `beehiiv-pp-cli posts index` — List posts <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>
- `beehiiv-pp-cli posts show` — Get post <Badge intent='info' minimal outlined>OAuth Scope: posts:read</Badge>
- `beehiiv-pp-cli posts update` — <Note title='Currently in beta' icon='b'> This feature is currently in beta, the API is subject to change

**publications** — Manage publications

- `beehiiv-pp-cli publications index` — List publications <Badge intent='info' minimal outlined>OAuth Scope: publications:read</Badge>
- `beehiiv-pp-cli publications show` — Get publication <Badge intent='info' minimal outlined>OAuth Scope: publications:read</Badge>

**referral-program** — Manage referral program

- `beehiiv-pp-cli referral-program <publicationId>` — Get referral program <Badge intent='info' minimal outlined>OAuth Scope: referral_program:read</Badge>

**segments** — Manage segments

- `beehiiv-pp-cli segments create` — Create a new segment.
- `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 <Badge intent='info' minimal outlined>OAuth Scope: segments:read</Badge>
- `beehiiv-pp-cli segments show` — Get segment <Badge intent='info' minimal outlined>OAuth Scope: segments:read</Badge>

**subscriptions** — Manage subscriptions

- `beehiiv-pp-cli subscriptions bulk-updates-patch` — Update subscriptions <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions bulk-updates-patch-status` — Update subscriptions' status <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions bulk-updates-put` — Update subscriptions <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions bulk-updates-put-status` — Update subscriptions' status <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions create` — Create subscription <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions delete` — <Warning>This cannot be undone. All data associated with the subscription will also be deleted.
- `beehiiv-pp-cli subscriptions get-by-email` — <Info>Please note that this endpoint requires the email to be URL encoded.
- `beehiiv-pp-cli subscriptions get-by-id` — <Info>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 <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:read</Badge>
- `beehiiv-pp-cli subscriptions index` — Retrieve all subscriptions belonging to a specific publication.
- `beehiiv-pp-cli subscriptions patch` — Update subscription by ID <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions put` — Update subscription by ID <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>
- `beehiiv-pp-cli subscriptions update-by-email` — Update subscription by email <Badge intent='info' minimal outlined>OAuth Scope: subscriptions:write</Badge>

**tiers** — Manage tiers

- `beehiiv-pp-cli tiers create` — Create a tier <Badge intent='info' minimal outlined>OAuth Scope: tiers:write</Badge>
- `beehiiv-pp-cli tiers index` — List tiers <Badge intent='info' minimal outlined>OAuth Scope: tiers:read</Badge>
- `beehiiv-pp-cli tiers patch` — Update a tier <Badge intent='info' minimal outlined>OAuth Scope: tiers:write</Badge>
- `beehiiv-pp-cli tiers put` — Update a tier <Badge intent='info' minimal outlined>OAuth Scope: tiers:write</Badge>
- `beehiiv-pp-cli tiers show` — Get tier <Badge intent='info' minimal outlined>OAuth Scope: tiers:read</Badge>

**users** — Manage users

- `beehiiv-pp-cli users` — Identify user <Badge intent='info' minimal outlined>OAuth Scope: identify:read</Badge>

**webhooks** — Manage webhooks

- `beehiiv-pp-cli webhooks create` — Create a webhook <Badge intent='info' minimal outlined>OAuth Scope: webhooks:write</Badge>
- `beehiiv-pp-cli webhooks delete` — Delete a webhook <Badge intent='info' minimal outlined>OAuth Scope: webhooks:write</Badge>
- `beehiiv-pp-cli webhooks index` — List webhooks <Badge intent='info' minimal outlined>OAuth Scope: webhooks:read</Badge>
- `beehiiv-pp-cli webhooks show` — Get webhook <Badge intent='info' minimal outlined>OAuth Scope: webhooks:read</Badge>
- `beehiiv-pp-cli webhooks update` — Update webhook <Badge intent='info' minimal outlined>OAuth Scope: webhooks:write</Badge>

**workspaces** — Manage workspaces

- `beehiiv-pp-cli workspaces identify` — Identify workspace <Badge intent='info' minimal outlined>OAuth Scope: identify:read</Badge>
- `beehiiv-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.


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
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.

## Recipes

### Mirror the audience

```bash
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

```bash
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

```bash
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

```bash
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

```bash
beehiiv-pp-cli search "@example.com" --type subscriptions --limit 1000 --csv > subscribers.csv
```

Every list and search command emits CSV for spreadsheets.

## Auth Setup

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.

Run `beehiiv-pp-cli doctor` to verify setup.

## Agent Mode

Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`.

- **Pipeable** — JSON on stdout, errors on stderr
- **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  ```bash
  beehiiv-pp-cli advertisement-opportunities mock-value --agent --select advertisement_kind,advertiser_name,id
  ```
- **Previewable** — `--dry-run` shows 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 confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear
- **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only 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:

```json
{
  "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 AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

## Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

- Use `--home <dir>` for one invocation, or set `BEEHIIV_HOME=<dir>` to relocate all four path kinds under one root.
- Use per-kind env vars only when a specific kind must diverge: `BEEHIIV_CONFIG_DIR`, `BEEHIIV_DATA_DIR`, `BEEHIIV_STATE_DIR`, `BEEHIIV_CACHE_DIR`.
- Resolution order is per-kind env var, `--home`, `BEEHIIV_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults.
- `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files.
- Stored secrets live in `cre