bhv — A CLI for beehiiv

Command-line interface for the beehiiv newsletter platform API

Manage your beehiiv newsletter from the terminal. Check subscriber counts, pull post stats, export lists, look up individual subscribers, and more — all without leaving your shell.

---

Installation

Option 1: pip (recommended)

pip install bhv

After install, bhv is available as a command.

Option 2: Clone + symlink

git clone https://github.com/insightslab-ai/bhv.git
cd bhv
chmod +x bhv bhv.py

# Add to your PATH (pick one):
ln -s "$(pwd)/bhv" /usr/local/bin/bhv      # system-wide
# or
echo 'export PATH="$(pwd):$PATH"' >> ~/.zshrc  # current dir on PATH

Dependencies

bhv uses the requests library if available, and falls back to Python's built-in urllib otherwise. For best results:

pip install requests

---

Quick Start

1. Get your credentials

• API key: beehiiv dashboard → Settings → API
• Publication ID: beehiiv dashboard → Settings → Publication → Publication ID (format: pub_xxxxxxxxxx)

2. Set credentials

Option A — environment variables (great for CI/scripts):

export BEEHIIV_API_KEY="your_api_key_here"
export BEEHIIV_PUB_ID="pub_xxxxxxxxxxxxxxxxxx"

Option B — secrets file (recommended for daily use):

mkdir -p ~/.config/beehiiv
cat > ~/.config/beehiiv/secrets.env << 'EOF'
BEEHIIV_API_KEY=your_api_key_here
BEEHIIV_PUB_ID=pub_xxxxxxxxxxxxxxxxxx
EOF
chmod 600 ~/.config/beehiiv/secrets.env

3. Run your first command

bhv subscribers --count
bhv stats --days 30
bhv posts --limit 5

---

Commands

bhv subscribers — Subscriber management

Count subscribers by status:

bhv subscribers --count

──────────────────────────────────────────────────
  Subscriber Counts
──────────────────────────────────────────────────
  Active                       4,821
  Inactive                       312
  Pending                         47
  ────────────────────         ──────────
  Total                        5,180
──────────────────────────────────────────────────

List subscribers (default: 25 active):

bhv subscribers --list --limit 25
bhv subscribers --list --limit 100 --status inactive
bhv subscribers --list --since 2025-01-01
bhv subscribers --list --by-utm twitter

Export to CSV:

bhv subscribers --export-csv subscribers.csv
bhv subscribers --export-csv active.csv --status active

Flags:

Flag	Description	Default
--count	Show counts by status	—
--list	Show subscriber table	—
--export-csv PATH	Export all to CSV file	—
--status STATUS	Filter: active, inactive, pending, all	active
--limit N	Max rows to display	25
--by-utm SOURCE	Filter by utm_source	—
--since YYYY-MM-DD	Only subscribers created after date	—
--json	Output raw JSON	—

---

bhv stats — Publication statistics

bhv stats
bhv stats --days 30
bhv stats --json

Shows total subscribers, active/inactive breakdown, new subscribers in the lookback window, and estimated growth rate.

Flags:

Flag	Description	Default
--days N	Lookback period for new subscriber count	7
--json	Output raw JSON	—

---

bhv posts — List posts with metrics

bhv posts
bhv posts --limit 10
bhv posts --json
bhv posts --csv > posts.csv

Shows recent posts with open rates, click rates, and send counts.

Flags:

Flag	Description	Default
--limit N	Number of posts to show	10
--json	Output raw JSON	—
--csv	Output as CSV (stdout)	—

---

bhv post <id> — Single post detail

bhv post post_abc123def456
bhv post post_abc123def456 --json

Shows full detail for a single post: status, publish date, recipients, opens, clicks, open rate, click rate, unsubscribes.

---

bhv subscriber <email> — Look up a subscriber

bhv subscriber user@example.com
bhv subscriber user@example.com --json

Shows status, tags, custom fields, UTM parameters, referral count and code.

---

bhv segments — List segments

bhv segments
bhv segments --json

Lists all segments with name, type, subscriber count, and creation date.

---

bhv custom-fields — List custom fields

bhv custom-fields
bhv custom-fields --json

Lists all custom fields defined on your publication.

---

bhv automations — List automations

bhv automations
bhv automations --json

Lists all automations with name, status, and trigger type.

---

bhv export-hashed <path> — Export hashed emails

bhv export-hashed hashes.txt

Exports all active subscriber emails as SHA-256 hashes (lowercase, trimmed), one per line. Use for uploading custom audiences to Meta Ads without sharing raw email addresses.

---

Configuration

Credential priority

bhv looks for credentials in this order:

1. Environment variables already set in the shell
   (BEEHIIV_API_KEY, BEEHIIV_PUB_ID)
2. Default secrets file: ~/.config/beehiiv/secrets.env
3. Custom config file: --config /path/to/secrets.env

Secrets file format

# ~/.config/beehiiv/secrets.env
BEEHIIV_API_KEY=your_api_key_here
BEEHIIV_PUB_ID=pub_xxxxxxxxxxxxxxxxxx

Supports # comments, quoted values, and KEY=VALUE format. Keep this file mode 600.

Using --config

bhv --config /path/to/other-pub.env subscribers --count

Useful for managing multiple publications.

---

Global Flags

Flag	Description
--version	Print version and exit
--config PATH	Path to alternative secrets file

All subcommands support --json to output raw API responses for piping to jq or scripting.

---

Examples

# Morning dashboard
bhv stats --days 7
bhv posts --limit 5

# Export for analysis
bhv subscribers --export-csv ~/Downloads/subscribers-$(date +%Y%m%d).csv
bhv posts --csv > posts.csv

# Pipe to jq
bhv posts --json | jq '[.[] | {title: .subject, opens: .stats.email.unique_opens}]'

# Upload to Meta Ads
bhv export-hashed meta-audience.txt

# Check a specific subscriber
bhv subscriber hello@example.com

---

Scripting / CI

When using in scripts or CI, set credentials via environment variables:

BEEHIIV_API_KEY="..." BEEHIIV_PUB_ID="..." bhv subscribers --count

Or export them before running:

export BEEHIIV_API_KEY="..."
export BEEHIIV_PUB_ID="..."
bhv stats --json

---

API Reference

beehiiv API documentation: https://developers.beehiiv.com/docs/v2

---

License

MIT — see LICENSE

---

Built by Insights Lab