wingetCollections
  • Auto
  • Search
  • Awesome Collections
  • Awesome Programs
  • My Favorite Collections
  • My Collections
  • Account / Settings
  • Terms of Service
  • Privacy
  • About

© 2026 winget.ragerworks.com

Loading...
Install Beehiiv CLI using Winget - wingetCollections
  1. Go back
  2. Packages
  3. Beehiiv CLI
Beehiiv CLI logo

Beehiiv CLI Deldrid1

beehiiv cli golang
Use this command to install Beehiiv CLI:
winget install --id=Deldrid1.BeehiivCLI -e

Beehiiv CLI is a cross-platform command-line tool designed to interact with the Beehiiv V2 API, enabling users to manage their publications, subscribers, posts, and webhooks directly from the terminal. It provides a seamless interface for developers and content creators to automate tasks and integrate AI-driven workflows through Codex.

Key Features:

  • Secure Credential Management: Stores credentials securely using macOS Keychain or Windows Credential Manager.
  • User-Friendly Help System: Offers clear help output on every command, enhancing usability.
  • Guided Reports: Generates non-technical reports with options for CSV exports and ASCII charts, making data analysis accessible.

Audience & Benefits: Ideal for content creators, newsletter managers, developers requiring script automation, and teams leveraging Codex for AI-driven workflows. Beehiiv CLI streamlines resource management on Beehiiv, integrates seamlessly with Codex for conversational AI tasks, and supports shell scripting or CI/CD pipelines, enhancing efficiency and productivity.

This tool is available on Windows via winget, ensuring easy installation and setup.

README

Beehiiv CLI

A simple command-line app for interacting with the Beehiiv V2 API. Use it (with AI! 🤖) to extract data and work with your publications, subscribers, posts, and webhooks from your terminal.

Project Status

Ready for public use on macOS, Windows, and Linux. Install via Homebrew (macOS/Linux) or winget (Windows), or download a binary from the GitHub releases page. The Codex plugin ships both in-repo and as a release asset for team installs.

Quick Start

  1. Download the latest release from the GitHub releases page or install via a package manager:
brew tap deldrid1/homebrew-tap
brew install beehiiv
  1. Sign in — your browser opens automatically:
beehiiv login
  1. Try beehiiv publications list or beehiiv --help.

If you're setting up release publishing with an agent, start with docs/release-auth-setup.md. It includes the current token requirements, including the classic PAT requirement for winget publication.

Use with Codex

The repo includes a Codex-installable plugin at plugins/beehiiv-codex for teammates who would rather ask for outcomes in plain language than memorize CLI commands.

If your team already works in this repo:

  1. Pull the latest changes.
  2. Restart Codex.
  3. Open Plugins in Codex, then install Beehiiv from the Beehiiv Local Plugins marketplace.

If your team just wants the plugin:

  1. Download beehiiv-codex-plugin_VERSION.zip from the matching GitHub release.
  2. Extract beehiiv-codex into ~/.codex/plugins/ on macOS/Linux or %USERPROFILE%\\.codex\\plugins\\ on Windows.
  3. Add a personal marketplace file at ~/.agents/plugins/marketplace.json that points at ./.codex/plugins/beehiiv-codex.
  4. Restart Codex and install Beehiiv from that personal marketplace.

Example personal marketplace file:

{
  "name": "beehiiv-personal-plugins",
  "interface": {
    "displayName": "Beehiiv Personal Plugins"
  },
  "plugins": [
    {
      "name": "beehiiv-codex",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/beehiiv-codex"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
Versions
0.2.1
0.2.0
0.1.6
Website
github.com
License
Last updated
4/21/2026
Download latest version

Use with Claude Code

The repo includes a Claude Code plugin at plugins/beehiiv-claude with a beehiiv-reporting-assistant skill that translates plain-language requests ("summarize the last 14 days", "export subscribers to CSV") into the right beehiiv commands.

Install from this repo:

/plugin marketplace add /absolute/path/to/beehiiv-cli
/plugin install beehiiv-claude@beehiiv-local-plugins

Or install from GitHub:

/plugin marketplace add deldrid1/beehiiv-cli
/plugin install beehiiv-claude@beehiiv-local-plugins

If you prefer to use the skill without the plugin wrapper, copy it into your personal skills directory:

cp -r plugins/beehiiv-claude/skills/beehiiv-reporting-assistant ~/.claude/skills/

See plugins/beehiiv-claude/README.md for details and suggested prompts.

Features

  • Friendly --help output on every command
  • One-command sign-in via OAuth — no API key setup required
  • Secure credential storage in the macOS Keychain or Windows Credential Manager
  • Handy shortcuts for common subscriber, publication, post, and webhook tasks
  • Guided reports workflows for non-technical stats, charts, and CSV exports
  • JSON output for scripts, with table output when you want something easier to read
  • Automatic pagination with --all
  • Built-in retry and rate-limit handling

CLI vs Beehiiv MCP Server

Beehiiv ships an official MCP server for AI-assisted workflows. The table below compares it with this CLI so you can choose the right tool — or use both.

Capability coverage

ResourceCLIMCPNotes
Publications (list, get, stats)✅✅
Posts (list, get, stats)✅✅
Post content (free/paid audience views)✅✅MCP adds audience-scoped rendering
Post ISP deliverability breakdown❌✅MCP-only; per-domain metrics for 50+ subscriber domains
Post click tracking (per-link)❌✅MCP-only; includes per-subscriber click lists
Subscriptions (list, get, filter)✅✅
Authors✅✅
Tiers✅✅
Custom fields✅✅
Content tags❌✅MCP-only
Polls + poll responses✅✅
Surveys + survey responses❌✅MCP-only
Automations + journeys✅✅MCP adds per-step subscriber counts
Automation email content❌✅MCP-only; rendered email from a step
Segments (list, get, recalculate)✅❌CLI-only
Segment members / results✅❌CLI-only
Referral program✅❌CLI-only
Advertisement opportunities✅❌CLI-only
Webhooks (CRUD + test)✅❌CLI-only
Email blasts✅❌CLI-only
Engagements✅❌CLI-only
Newsletter lists✅❌CLI-only (Beta)
Workspaces✅✅
Post templates✅❌CLI-only
Condition sets✅❌CLI-only
Beehiiv documentation search❌✅MCP-only; search and read support articles

Write operations

OperationCLIMCP
Create / update / delete posts✅❌
Create / update / delete subscriptions✅❌
Bulk import subscriptions✅❌
Bulk update subscriptions✅❌
Create / update / delete custom fields✅❌
Create / update / delete webhooks✅❌
Create / update tiers✅❌
Create automation journeys✅❌
Delete segments✅❌
Add subscription tags✅❌

The MCP is read-only (v1) — Beehiiv has announced write support for a future v2.

Cross-cutting features

FeatureCLIMCP
Full pagination (--all aggregation)✅Capped at 100/page
CSV export✅❌
ASCII charts in terminal✅❌
Publication summary reports✅❌
Table, JSON, and raw output✅JSON only
Rate-limit handling + retry✅Managed server-side
OAuth sign-in (no API key)✅✅ (managed auth)
API key auth✅❌
Works on free Beehiiv plan✅❌ (paid plans only)
Shell scripting / CI pipelines✅❌
AI agent integration (MCP)❌✅
Verbose request debugging✅❌

When to use which

  • CLI — scripting, bulk operations, CI/CD, CSV exports, anything that writes data, free-tier accounts, or when you need the full API surface (71 operations across 28 resource groups).
  • MCP — conversational AI workflows, asking questions about your newsletter in natural language, deliverability analysis (ISP breakdown), and survey data.
  • Both — the CLI and MCP complement each other. Use the MCP for exploration and analysis, then use the CLI to act on what you find.

Requirements

  • For normal use: a Beehiiv account (OAuth sign-in is built in — no API key needed)
  • To build from source: Go 1.26 or newer
  • For publication-scoped commands: a Beehiiv publication ID

For CI/CD or programmatic use you can also pass an API key directly. See Beehiiv's Create an API Key guide.

Build from Source

From the Go module root:

make build

Cross-platform examples:

CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o ./dist/beehiiv-darwin-arm64 ./cmd/beehiiv
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o ./dist/beehiiv-darwin-amd64 ./cmd/beehiiv
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o ./dist/beehiiv-windows-amd64.exe ./cmd/beehiiv

Install from a Release

macOS

  1. Download the correct archive for your machine from the latest release: beehiiv_VERSION_darwin_arm64.tar.gz on Apple Silicon or beehiiv_VERSION_darwin_x86_64.tar.gz on Intel.
  2. Extract it:
tar -xzf beehiiv_VERSION_darwin_arm64.tar.gz
  1. Move beehiiv somewhere on your PATH, for example:
mv ./beehiiv /usr/local/bin/beehiiv
  1. Run:
beehiiv auth login

The CLI stores its config at:

~/Library/Application Support/beehiiv-cli/config.json

Secrets are stored in the macOS Keychain by default.

Windows

Install via winget (requires Windows 10 1809+ or Windows 11):

winget install Deldrid1.BeehiivCLI

Then sign in:

beehiiv login

If winget is not available, download the correct archive from the latest release (e.g. beehiiv_VERSION_windows_x86_64.zip), extract it into a folder such as C:\Tools\beehiiv\, and add that folder to your PATH.

The CLI stores its config at %AppData%\beehiiv-cli\config.json. Secrets are stored in the Windows Credential Manager by default.

Linux

  1. Download the correct archive from the latest release, for example beehiiv_VERSION_linux_x86_64.tar.gz.
  2. Extract it:
tar -xzf beehiiv_VERSION_linux_x86_64.tar.gz
  1. Move beehiiv somewhere on your PATH, for example:
sudo mv ./beehiiv /usr/local/bin/beehiiv

Package Managers

Homebrew:

brew tap deldrid1/homebrew-tap
brew install beehiiv

Winget (Windows 10 1809+ or Windows 11):

winget install Deldrid1.BeehiivCLI

Maintainer setup and publication notes live in packaging/winget/README.md, packaging/homebrew/README.md, and docs/release-auth-setup.md.

Authentication

Sign in with a single command — no API key required:

beehiiv login

Your browser opens the Beehiiv authorization page. After you approve, credentials are saved securely in the OS keyring. The OAuth client is pre-configured; nothing extra to set up.

If you prefer not to open a browser automatically:

beehiiv login --no-browser

API key authentication (CI/CD)

For non-interactive environments, pass your API key directly:

beehiiv login --api-key YOUR_API_KEY
beehiiv login --api-key YOUR_API_KEY --publication-id pub_123

If --publication-id is omitted the CLI looks up your publications and selects automatically if there is only one, or prompts you to choose.

Auth management

beehiiv auth status          # show masked credential state
beehiiv auth logout          # remove saved credentials (revokes OAuth token)
beehiiv auth path            # print the config file location

Custom OAuth app (advanced)

If you are building your own Beehiiv OAuth integration:

beehiiv auth oauth login --client-id YOUR_CLIENT_ID
beehiiv auth oauth login --client-id YOUR_CLIENT_ID --scope all
beehiiv auth oauth login --client-id YOUR_CLIENT_ID --no-browser

The redirect URI defaults to http://localhost:3008/callback and must match your Beehiiv OAuth app settings. PKCE is used automatically.

Configuration

The CLI checks configuration in this order:

  1. Command-line flags
  2. Environment variables
  3. Stored session secrets in the OS keychain or keyring plus config.json settings
  4. Built-in defaults

Supported environment variables:

BEEHIIV_API_KEY
BEEHIIV_BEARER_TOKEN
BEEHIIV_PUBLICATION_ID
BEEHIIV_BASE_URL
BEEHIIV_RATE_LIMIT_RPM
BEEHIIV_OAUTH_CLIENT_ID
BEEHIIV_OAUTH_CLIENT_SECRET
BEEHIIV_OAUTH_REDIRECT_URI
BEEHIIV_OAUTH_SCOPES

The CLI stores non-secret settings in config.json. Secrets are kept out of that file.

Auth status example:

beehiiv auth status

Common Commands

Start with help:

beehiiv
beehiiv --help

List publications:

beehiiv publications list
beehiiv pubs list

List all subscribers:

beehiiv subscriptions list --all --query limit=100

Use repeatable query flags when an endpoint accepts multiple values:

beehiiv subscriptions list \
  --query expand=stats,custom_fields \
  --query status=active

Show a subscriber by ID:

beehiiv subscriptions show sub_123

Inspect automations and their related email activity:

beehiiv automations list --query expand=stats
beehiiv automations show aut_123 --query expand=stats
beehiiv automations emails aut_123

Inspect segments and poll responses:

beehiiv segments members segment_123 --query expand=stats,custom_fields
beehiiv polls show poll_123 --query expand=stats
beehiiv polls responses poll_123

Look up a subscriber by email:

beehiiv subscriptions find person@example.com

Create a custom field from inline JSON:

beehiiv custom-fields create --body '{"kind":"string","display":"Favorite Airport"}'

Create a webhook from a file:

beehiiv webhooks create --body @webhook.json
beehiiv hooks ping endpoint_123

Check the current sign-in state safely:

beehiiv auth status

Show a table instead of JSON:

beehiiv subscriptions list --output table

Create a friendly publication summary, chart engagement trends, or export a CSV:

beehiiv reports summary
beehiiv reports chart --metric unique_opens --days 14
beehiiv reports export subscriptions --file subscriptions.csv

Print the raw API response body:

beehiiv subscriptions get sub_123 --raw

Print request and response details to stderr for troubleshooting:

beehiiv subscriptions get sub_123 --verbose

Pagination

  • List commands return one page by default.
  • Add --all to fetch everything.
  • For endpoints like subscriptions, the CLI prefers cursor pagination unless you explicitly pass --query page=....
  • Aggregated --all output looks like:
{
  "data": [],
  "pagination": {
    "mode": "cursor",
    "pages_fetched": 3,
    "items_returned": 250,
    "has_more": false,
    "next_cursor": null
  }
}

Rate Limiting

The CLI defaults to an internal limit of 150 requests per minute and also honors Beehiiv rate-limit headers. When Beehiiv responds with 429, the client waits for the reset window and retries automatically.

Development

Useful local commands:

make build
make docs
make test
make fmt
make fmt-check
make lint

Generated CLI reference docs land in docs/reference/cli/, generated manpages land in share/man/man1/, and generated shell completions land in share/completions/.

To enable the local pre-commit hook:

git config core.hooksPath .githooks

See CONTRIBUTING.md for the contributor workflow, SECURITY.md for responsible disclosure guidance, and CHANGELOG.md for release history.

Override the internal limiter if needed:

beehiiv subscriptions list --rate-limit-rpm 120

Testing

Run the local unit and integration suite:

go test ./...

Run the gated live Beehiiv suite:

BEEHIIV_LIVE_TESTS=1 \
BEEHIIV_API_KEY=your_api_key \
BEEHIIV_PUBLICATION_ID=pub_your_publication \
go test ./... -run Live

The live tests look for BEEHIIV_API_KEY first, then BEEHIIV_BEARER_TOKEN. They also require BEEHIIV_PUBLICATION_ID.