Can I use Beehiiv as a CLI?

Yes. KosmoKrator exposes a Beehiiv CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Beehiiv through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Beehiiv tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Beehiiv credentials stored?

Beehiiv credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Beehiiv MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

newsletter

Beehiiv CLI for AI Agents

Use the Beehiiv CLI from KosmoKrator to call Beehiiv tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

10 functions 6 read 4 write API key auth

Submit Beehiiv feedback View package source

Beehiiv CLI Setup

Beehiiv can be configured headlessly with `kosmokrator integrations:configure beehiiv`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure beehiiv --set api_key="$BEEHIIV_API_KEY" --set publication_id="$BEEHIIV_PUBLICATION_ID" --enable --read allow --write ask --json
kosmokrator integrations:doctor beehiiv --json
kosmokrator integrations:status --json

Credentials

Authentication type: API key api_key. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`api_key`	`BEEHIIV_API_KEY`	Secret `secret`	yes	API Key
`publication_id`	`BEEHIIV_PUBLICATION_ID`	Text `string`	yes	Publication ID

Call Beehiiv Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call beehiiv.beehiiv_list_posts '{
  "status": "example_status",
  "limit": 1,
  "page": 1
}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:beehiiv beehiiv_list_posts '{
  "status": "example_status",
  "limit": 1,
  "page": 1
}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

kosmo integrations:docs beehiiv --json
kosmo integrations:docs beehiiv.beehiiv_list_posts --json
kosmo integrations:schema beehiiv.beehiiv_list_posts --json
kosmo integrations:search "Beehiiv" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Beehiiv.

`beehiiv.beehiiv_list_posts`

Read read

List posts from your Beehiiv publication. Filter by status (draft, confirmed, etc.) and paginate with limit/page.

Parameters: status, limit, page

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_list_posts '{"status":"example_status","limit":1,"page":1}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_list_posts '{"status":"example_status","limit":1,"page":1}' --json

`beehiiv.beehiiv_get_post`

Read read

Get a single post from your Beehiiv publication by its post ID.

Parameters: post_id

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_get_post '{"post_id":"example_post_id"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_get_post '{"post_id":"example_post_id"}' --json

`beehiiv.beehiiv_create_post`

Write write

Create a new post in your Beehiiv publication. Requires title and content. Set status to "draft" to save without publishing, or "confirmed" to publish.

Parameters: title, content, status, subtitle, audience, thumbnail_url, content_tags

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_create_post '{"title":"example_title","content":"example_content","status":"example_status","subtitle":"example_subtitle","audience":"example_audience","thumbnail_url":"example_thumbnail_url","content_tags":"example_content_tags"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_create_post '{"title":"example_title","content":"example_content","status":"example_status","subtitle":"example_subtitle","audience":"example_audience","thumbnail_url":"example_thumbnail_url","content_tags":"example_content_tags"}' --json

`beehiiv.beehiiv_update_post`

Write write

Update an existing post in your Beehiiv publication. Provide the post ID and the fields you want to change.

Parameters: post_id, title, content, status, subtitle, audience, thumbnail_url, content_tags

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_update_post '{"post_id":"example_post_id","title":"example_title","content":"example_content","status":"example_status","subtitle":"example_subtitle","audience":"example_audience","thumbnail_url":"example_thumbnail_url","content_tags":"example_content_tags"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_update_post '{"post_id":"example_post_id","title":"example_title","content":"example_content","status":"example_status","subtitle":"example_subtitle","audience":"example_audience","thumbnail_url":"example_thumbnail_url","content_tags":"example_content_tags"}' --json

`beehiiv.beehiiv_delete_post`

Write write

Delete a post from your Beehiiv publication. This action is irreversible.

Parameters: post_id

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_delete_post '{"post_id":"example_post_id"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_delete_post '{"post_id":"example_post_id"}' --json

`beehiiv.beehiiv_list_subscribers`

Read read

List subscribers for your Beehiiv publication. Filter by status (active, inactive, etc.) and paginate with limit/page.

Parameters: status, limit, page

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_list_subscribers '{"status":"example_status","limit":1,"page":1}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_list_subscribers '{"status":"example_status","limit":1,"page":1}' --json

`beehiiv.beehiiv_get_subscriber`

Read read

Get a single subscriber from your Beehiiv publication by their subscription ID.

Parameters: subscription_id

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_get_subscriber '{"subscription_id":"example_subscription_id"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_get_subscriber '{"subscription_id":"example_subscription_id"}' --json

`beehiiv.beehiiv_create_subscriber`

Write write

Add a new subscriber to your Beehiiv publication by email address.

Parameters: email, reactivate_existing, utm_source, utm_medium, utm_campaign, referring_pub

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_create_subscriber '{"email":"example_email","reactivate_existing":true,"utm_source":"example_utm_source","utm_medium":"example_utm_medium","utm_campaign":"example_utm_campaign","referring_pub":"example_referring_pub"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_create_subscriber '{"email":"example_email","reactivate_existing":true,"utm_source":"example_utm_source","utm_medium":"example_utm_medium","utm_campaign":"example_utm_campaign","referring_pub":"example_referring_pub"}' --json

`beehiiv.beehiiv_get_stats`

Read read

Get analytics and stats for your Beehiiv publication. Use the "intent" parameter to specify the type of stats (overview, traffic, growth, subscribers).

Parameters: intent, days, start_date, end_date

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_get_stats '{"intent":"example_intent","days":1,"start_date":"example_start_date","end_date":"example_end_date"}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_get_stats '{"intent":"example_intent","days":1,"start_date":"example_start_date","end_date":"example_end_date"}' --json

`beehiiv.beehiiv_get_current_user`

Read read

Verify your Beehiiv API key and list all publications you have access to. Use this to confirm the integration is working and to find your publication ID.

Parameters: none

Generic CLI call

kosmo integrations:call beehiiv.beehiiv_get_current_user '{}' --json

Provider shortcut

kosmo integrations:beehiiv beehiiv_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

`beehiiv.beehiiv_list_posts`

List posts from your Beehiiv publication. Filter by status (draft, confirmed, etc.) and paginate with limit/page.

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_list_posts --json

Parameter	Type	Required	Description
`status`	string	no	Filter by post status: "draft", "confirmed", "scheduled", "published". Omit to list all.
`limit`	integer	no	Maximum number of posts to return per page (default: 20, max: 100).
`page`	integer	no	Page number for pagination (default: 1).

`beehiiv.beehiiv_get_post`

Get a single post from your Beehiiv publication by its post ID.

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_get_post --json

Parameter	Type	Required	Description
`post_id`	string	yes	The ID of the post to retrieve.

`beehiiv.beehiiv_create_post`

Create a new post in your Beehiiv publication. Requires title and content. Set status to "draft" to save without publishing, or "confirmed" to publish.

Operation: Write write
Schema command: kosmo integrations:schema beehiiv.beehiiv_create_post --json

Parameter	Type	Required	Description
`title`	string	yes	The post title.
`content`	string	yes	The post content in HTML or Markdown.
`status`	string	no	Post status: "draft" or "confirmed". Default: "draft".
`subtitle`	string	no	Optional subtitle for the post.
`audience`	string	no	Audience: "free", "premium", or "all". Default: "free".
`thumbnail_url`	string	no	URL for the post thumbnail image.
`content_tags`	array	no	Array of tag strings for the post.

`beehiiv.beehiiv_update_post`

Update an existing post in your Beehiiv publication. Provide the post ID and the fields you want to change.

Operation: Write write
Schema command: kosmo integrations:schema beehiiv.beehiiv_update_post --json

Parameter	Type	Required	Description
`post_id`	string	yes	The ID of the post to update.
`title`	string	no	Updated post title.
`content`	string	no	Updated post content in HTML or Markdown.
`status`	string	no	Updated status: "draft", "confirmed", "scheduled".
`subtitle`	string	no	Updated subtitle.
`audience`	string	no	Updated audience: "free", "premium", or "all".
`thumbnail_url`	string	no	Updated thumbnail URL.
`content_tags`	array	no	Updated array of tag strings.

`beehiiv.beehiiv_delete_post`

Delete a post from your Beehiiv publication. This action is irreversible.

Operation: Write write
Schema command: kosmo integrations:schema beehiiv.beehiiv_delete_post --json

Parameter	Type	Required	Description
`post_id`	string	yes	The ID of the post to delete.

`beehiiv.beehiiv_list_subscribers`

List subscribers for your Beehiiv publication. Filter by status (active, inactive, etc.) and paginate with limit/page.

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_list_subscribers --json

Parameter	Type	Required	Description
`status`	string	no	Filter by subscriber status: "active", "inactive", "pending". Omit to list all.
`limit`	integer	no	Maximum number of subscribers to return per page (default: 20, max: 100).
`page`	integer	no	Page number for pagination (default: 1).

`beehiiv.beehiiv_get_subscriber`

Get a single subscriber from your Beehiiv publication by their subscription ID.

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_get_subscriber --json

Parameter	Type	Required	Description
`subscription_id`	string	yes	The subscription ID of the subscriber to retrieve.

`beehiiv.beehiiv_create_subscriber`

Add a new subscriber to your Beehiiv publication by email address.

Operation: Write write
Schema command: kosmo integrations:schema beehiiv.beehiiv_create_subscriber --json

Parameter	Type	Required	Description
`email`	string	yes	Email address of the new subscriber.
`reactivate_existing`	boolean	no	Whether to reactivate the subscription if the email already exists. Default: false.
`utm_source`	string	no	UTM source to attribute the subscription to.
`utm_medium`	string	no	UTM medium to attribute the subscription to.
`utm_campaign`	string	no	UTM campaign to attribute the subscription to.
`referring_pub`	string	no	Referring publication ID.

`beehiiv.beehiiv_get_stats`

Get analytics and stats for your Beehiiv publication. Use the "intent" parameter to specify the type of stats (overview, traffic, growth, subscribers).

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_get_stats --json

Parameter	Type	Required	Description
`intent`	string	no	Type of stats to retrieve: "overview", "traffic", "growth", "subscribers". Default: "overview".
`days`	integer	no	Number of days to look back (default: 30).
`start_date`	string	no	Start date for custom range (ISO 8601, e.g., "2026-01-01").
`end_date`	string	no	End date for custom range (ISO 8601, e.g., "2026-01-31").

`beehiiv.beehiiv_get_current_user`

Verify your Beehiiv API key and list all publications you have access to. Use this to confirm the integration is working and to find your publication ID.

Operation: Read read
Schema command: kosmo integrations:schema beehiiv.beehiiv_get_current_user --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.