pp-beehiiv

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/beehiiv/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# 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.3 or newer):

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

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

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

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

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

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

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

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

**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. Use `expand[]=stats` to calculate and...

**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. Contact support to enable Data Deletion API access for...
- `beehiiv-pp-cli data-privacy data-deletion-index` — <Warning>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` — <Warning>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 <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.<br><br> By...

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

**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...
- `beehiiv-pp-cli polls show` — Retrieve detailed information about a specific poll belonging to a publication. Use `expand[]=stats` for aggregate...

**post-templates*