Posthell cli

posthell

Draft, schedule, and publish social posts across up to 15 networks with the posthell CLI. Every command prints JSON on stdout (parse with jq); errors print to stderr with a non-zero exit code.

⚠️ Hard rules (read first)

1. Auth is required. PH_API_KEY must be set to a ph_... key (from posthell Settings -> Agent access). If a command returns an auth error, tell the user to set it: export PH_API_KEY=ph_.... Do not invent a key.
2. draft never publishes. It queues a draft the user approves in the posthell dashboard. This is the SAFE default - prefer it unless the user clearly asked to publish now or on a schedule.
3. publish is opt-in and X-safe. It only works if the user enabled "Publishing" for the key, and it only sends to NON-X networks. X is always saved as a draft for the user to approve, because X posts cost money. You cannot override this - the server enforces it. If publish says publishing isn't enabled, tell the user to flip the key to "Publishing" in Settings -> Agent access; do not retry in a loop.
4. shape uses the user's monthly AI quota. Use it when notes need turning into a post, not on every call.
5. Never fabricate results. Report exactly what the JSON says (published vs drafted, which networks, any error).

Core workflow

1. Discover      posthell accounts                 # which networks are connected
2. (optional)    posthell shape "<rough notes>"    # notes -> 2-3 post angles
3a. Safe path    posthell draft "<text>" -p <networks>       # queue for approval
3b. Publish path posthell publish "<text>" -p <networks>     # only if user asked + key allows
4. Verify        posthell posts                    # confirm it is queued/live

Decision rule: if the user said "draft/prepare/queue" or the intent is unclear, use draft. Use publish only when the user explicitly wants it live now or scheduled.

Commands

posthell accounts
# -> { "accounts": [ { "platform": "linkedin", "handle": "...", "followers": 1200 }, ... ] }
# List connected networks. Call this first so you target networks the user actually has.

posthell shape "shipped dark mode today, 3 users had asked for it"
# -> { "angles": ["...","...","..."], "generationsRemainingThisMonth": 39 }
# Turn rough notes into 2-3 finished post angles in the user's voice. Pick one for -c below.

posthell draft "Dark mode is live." -p linkedin,threads
# -> { "draftId": "...", "status": "draft", "targets": ["linkedin (...)","threads (...)"] }
# Queue a DRAFT. Never publishes. Omit -p to target every connected account.
# Optional -s <ISO 8601> proposes a time that pre-fills the user's scheduler.

posthell publish "Dark mode is live." -p linkedin,bluesky
# -> { "postId": "...", "published": [ { "platform": "linkedin", "status": "publishing" } ],
#      "xDraftedForApproval": ["x (...)"], "xDraftPostId": "..." }   # X only if it was targeted
# Publish for real to NON-X networks now. Add -s <ISO 8601> to schedule instead of now.
# Any X target comes back under xDraftedForApproval as a separate draft to approve.

posthell posts --status draft
# -> { "posts": [ { "id": "...", "status": "draft", "platforms": [...], "body": "..." } ] }
# List recent posts/drafts. --status one of: draft|scheduled|posted|failed|partly_posted.
# -n / --limit sets how many (default 15). Call before drafting to avoid duplicates.

posthell growth
# -> { "totalGrowth7d": 84, "networks": [...], "read": "linkedin is growing fastest ..." }
# 7-day follower growth per network + where posting matters most.

Flags

Flag	Meaning
-c, --content <text>	Post text (or pass it as the trailing argument)
-p, --platforms <list>	Comma-separated networks, e.g. linkedin,threads,bluesky
-s, --schedule <iso>	ISO 8601 time, e.g. 2026-07-08T15:00:00Z (schedule instead of now)
--status <status>	Filter posts: draft|scheduled|posted|failed|partly_posted
-n, --limit <n>	Max posts to list (default 15)

Networks

x, linkedin, instagram, threads, bluesky, facebook, tiktok, youtube, pinterest, reddit, telegram, discord, snapchat, googlebusiness, whatsapp.

• Only x is metered (it costs credits; a link post costs ~13x a plain one). Every other network is free.
• Post the same text everywhere, or run per-network draft/publish calls with different -c text when a network needs its own phrasing (e.g. shorter for X).

Common gotchas (do X, not Y)

• Publishing fails with "not enabled" -> the KEY lacks publishing. Tell the user to enable it in Settings; do NOT keep retrying, and do NOT try to publish X another way.
• Want X posted -> you cannot auto-publish X. Use draft (or let publish draft it) and tell the user to approve it.
• No -p given -> the post goes to ALL connected accounts. Pass -p to be specific.
• Times must be ISO 8601 with an offset (2026-07-08T15:00:00Z), not "tomorrow 3pm".
• Rate limits (per key): shape 6/min, draft 12/min, publish 6/min, reads 30/min. On a 429, wait a moment and retry once - do not hammer.
• Don't call shape just to reword something small; it spends the AI quota.

Copy-paste setups (heartbeat, cron, weekly growth recap): see RECIPES.md in this package.

Full docs: https://www.posthell.com/mcp