posthive-cli 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# posthive-cli
+
+Posthive CLI — schedule posts to 11 social platforms from the command line or any AI agent that can run shell commands (Claude Code, OpenClaw, Cursor, custom pipelines).
+
+**Supported platforms:** Bluesky, Threads, Instagram, LinkedIn, Mastodon, YouTube, Facebook Pages, Pinterest, Telegram, X (Twitter), Nostr
+
+Every command outputs structured JSON, so LLMs and scripts can parse results directly.
+
+---
+
+## Install
+
+```bash
+npm i -g posthive-cli
+# or run without installing
+npx posthive-cli help
+```
+
+## Setup
+
+You need a Posthive account and an API key ([posthive.co](https://posthive.co) → Settings → API Keys, Pro/Team plan).
+
+```bash
+export POSTHIVE_API_KEY=ph_your_key_here
+export POSTHIVE_API_URL=https://api.posthive.co   # or your self-hosted URL
+```
+
+## Usage
+
+```bash
+# List connected accounts (start here — you need account IDs)
+posthive accounts:list
+
+# Create a draft post (default: drafts require approval before publishing)
+posthive posts:create --content "Hello world" --accounts acc_1,acc_2
+
+# Schedule directly
+posthive posts:create --content "Launch day!" --accounts acc_1 --schedule 2026-07-10T09:00:00Z
+
+# First comment automation
+posthive posts:create --content "We shipped something big" --accounts acc_1 \
+  --first-comment "Full details: https://example.com"
+
+# Upload media, then attach it
+posthive upload ./screenshot.png
+posthive posts:create --content "Sneak peek" --accounts acc_1 --media <returned_url>
+
+# Manage the queue
+posthive posts:list --status draft
+posthive posts:get <post_id>
+posthive posts:update <post_id> --content "Fixed typo"
+posthive posts:approve <post_id> --schedule 2026-07-10T09:00:00Z
+posthive posts:duplicate <post_id>
+posthive posts:delete <post_id>
+
+# Templates
+posthive templates:list
+posthive templates:use <template_id> --accounts acc_1
+
+# Full command reference
+posthive help
+```
+
+## Use with AI agents
+
+The package ships with a [skill](./skills/posthive/SKILL.md) that teaches agents the full command set, platform character limits, and draft-first workflow. Works with Claude Code, OpenClaw, and any agent framework that supports skills or shell execution.
+
+Posts created by agents default to **drafts** — nothing publishes without approval unless `--schedule` is passed explicitly. Human in the loop by design.
+
+Prefer MCP? Use [`posthive-mcp`](https://www.npmjs.com/package/posthive-mcp) for Claude Desktop, Cursor, and other MCP clients.
+
+## Links
+
+- [Posthive](https://posthive.co)
+- [Documentation](https://posthive.co/docs)
+- [For Developers](https://posthive.co/for-developers)
+- [GitHub](https://github.com/AstaBlackClove/posthive)
+
+## License
+
+AGPL-3.0

package/dist/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Posthive CLI
+ *
+ * Schedule posts to 11 social platforms from the command line or any
+ * AI agent that can run shell commands (Claude Code, OpenClaw, Cursor).
+ *
+ * Every command outputs structured JSON for easy parsing by LLMs and scripts.
+ *
+ * Required env vars:
+ *   POSTHIVE_API_KEY  — API key from Posthive Settings → API Keys
+ *   POSTHIVE_API_URL  — Base URL of the Posthive API (default: https://api.posthive.co)
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+const API_KEY = process.env.POSTHIVE_API_KEY;
+const API_URL = (process.env.POSTHIVE_API_URL ?? "https://api.posthive.co").replace(/\/$/, "");
+// ─── Output helpers ──────────────────────────────────────────────────────────
+function out(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    process.exit(0);
+}
+function fail(message, code = 1) {
+    process.stdout.write(JSON.stringify({ error: message }, null, 2) + "\n");
+    process.exit(code);
+}
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = rest[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { command, positional, flags };
+}
+function str(flags, key) {
+    const v = flags[key];
+    return typeof v === "string" ? v : undefined;
+}
+function list(flags, key) {
+    const v = str(flags, key);
+    return v ? v.split(",").map(s => s.trim()).filter(Boolean) : undefined;
+}
+// ─── HTTP helper ─────────────────────────────────────────────────────────────
+async function api(method, path, body) {
+    let res;
+    try {
+        res = await fetch(`${API_URL}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (err) {
+        fail(`Cannot reach Posthive API at ${API_URL} — check POSTHIVE_API_URL and your network. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = { raw: text };
+    }
+    if (!res.ok) {
+        const rec = json;
+        const msg = rec?.error ?? rec?.message ?? text;
+        fail(`API ${res.status}: ${typeof msg === "string" ? msg : JSON.stringify(msg)}`);
+    }
+    return json;
+}
+// ─── Help text ───────────────────────────────────────────────────────────────
+const HELP = {
+    usage: "posthive <command> [args] [--flags]",
+    env: {
+        POSTHIVE_API_KEY: "required — API key from Posthive Settings → API Keys",
+        POSTHIVE_API_URL: "optional — API base URL (default: https://api.posthive.co)",
+    },
+    commands: {
+        "accounts:list": "List connected social accounts and their IDs",
+        "posts:create": "Create a post. --content <text> --accounts <id,id> [--schedule <ISO>] [--first-comment <text>] [--media <url,url>] [--media-type post|reel|story] [--youtube-type short|video] [--dry-run]. Saved as DRAFT unless --schedule is given.",
+        "posts:list": "List posts. [--status pending|draft|done|failed] [--limit <n>]",
+        "posts:get": "Get post details. posts:get <post_id>",
+        "posts:update": "Update a pending/draft post. posts:update <post_id> [--content <text>] [--schedule <ISO>] [--first-comment <text>]",
+        "posts:approve": "Approve a draft and schedule it. posts:approve <post_id> --schedule <ISO>",
+        "posts:duplicate": "Clone a post as a new draft. posts:duplicate <post_id>",
+        "posts:delete": "Delete a pending/draft post. posts:delete <post_id>",
+        "templates:list": "List saved post templates",
+        "templates:use": "Create a post from a template. templates:use <template_id> --accounts <id,id> [--content <override>] [--schedule <ISO>]",
+        "upload": "Upload an image or video. upload <file_path> — returns a media URL for posts:create --media",
+        "help": "Show this help",
+    },
+    notes: [
+        "All output is JSON.",
+        "Posts default to DRAFT status — review them in Posthive → Posts, or pass --schedule to schedule directly.",
+        "Get account IDs from accounts:list before creating posts.",
+    ],
+};
+// ─── Main ────────────────────────────────────────────────────────────────────
+const { command, positional, flags } = parseArgs(process.argv.slice(2));
+if (command === "help" || command === "--help" || command === "-h") {
+    out(HELP);
+}
+if (!API_KEY) {
+    fail("POSTHIVE_API_KEY environment variable is required. Get a key at Posthive → Settings → API Keys.");
+}
+switch (command) {
+    case "accounts:list": {
+        out(await api("GET", "/api/v1/accounts"));
+        break;
+    }
+    case "posts:create": {
+        const content = str(flags, "content");
+        const accounts = list(flags, "accounts");
+        if (!content)
+            fail("--content is required");
+        if (!accounts?.length)
+            fail("--accounts is required (comma-separated account IDs; see accounts:list)");
+        const schedule = str(flags, "schedule");
+        const body = {
+            content,
+            accountIds: accounts,
+            draft: !schedule,
+            ...(schedule ? { scheduledFor: schedule } : {}),
+            ...(list(flags, "media") ? { images: list(flags, "media") } : {}),
+            ...(str(flags, "media-type") ? { mediaType: str(flags, "media-type") } : {}),
+            ...(str(flags, "youtube-type") ? { youtubeType: str(flags, "youtube-type") } : {}),
+            ...(str(flags, "first-comment") ? { commentText: str(flags, "first-comment") } : {}),
+            ...(flags["dry-run"] === true ? { dryRun: true } : {}),
+        };
+        const data = await api("POST", "/api/v1/posts", body);
+        out({
+            ...data,
+            _note: schedule
+                ? "Post scheduled — will publish at the given time."
+                : "Post saved as DRAFT. Approve with posts:approve or review in Posthive → Posts.",
+        });
+        break;
+    }
+    case "posts:list": {
+        const params = new URLSearchParams();
+        const status = str(flags, "status");
+        const limit = str(flags, "limit");
+        if (status)
+            params.set("status", status);
+        if (limit)
+            params.set("limit", limit);
+        const qs = params.size ? `?${params}` : "";
+        out(await api("GET", `/api/v1/posts${qs}`));
+        break;
+    }
+    case "posts:get": {
+        const id = positional[0];
+        if (!id)
+            fail("Usage: posthive posts:get <post_id>");
+        out(await api("GET", `/api/v1/posts/${encodeURIComponent(id)}`));
+        break;
+    }
+    case "posts:update": {
+        const id = positional[0];
+        if (!id)
+            fail("Usage: posthive posts:update <post_id> [--content] [--schedule] [--first-comment]");
+        const body = {
+            ...(str(flags, "content") !== undefined ? { content: str(flags, "content") } : {}),
+            ...(str(flags, "schedule") !== undefined ? { scheduledFor: str(flags, "schedule") } : {}),
+            ...(str(flags, "first-comment") !== undefined ? { commentText: str(flags, "first-comment") } : {}),
+        };
+        if (Object.keys(body).length === 0) {
+            fail("Provide at least one of --content, --schedule, --first-comment");
+        }
+        out(await api("PATCH", `/api/v1/posts/${encodeURIComponent(id)}`, body));
+        break;
+    }
+    case "posts:approve": {
+        const id = positional[0];
+        const schedule = str(flags, "schedule");
+        if (!id)
+            fail("Usage: posthive posts:approve <post_id> --schedule <ISO datetime>");
+        if (!schedule)
+            fail("--schedule is required (ISO 8601 datetime, must be in the future)");
+        const data = await api("POST", `/api/v1/posts/${encodeURIComponent(id)}/approve`, { scheduledFor: schedule });
+        out({ ...data, _note: "Draft approved and scheduled." });
+        break;
+    }
+    case "posts:duplicate": {
+        const id = positional[0];
+        if (!id)
+            fail("Usage: posthive posts:duplicate <post_id>");
+        const data = await api("POST", `/api/v1/posts/${encodeURIComponent(id)}/duplicate`);
+        out({ ...data, _note: "Duplicated as a new draft." });
+        break;
+    }
+    case "posts:delete": {
+        const id = positional[0];
+        if (!id)
+            fail("Usage: posthive posts:delete <post_id>");
+        out(await api("DELETE", `/api/v1/posts/${encodeURIComponent(id)}`));
+        break;
+    }
+    case "templates:list": {
+        out(await api("GET", "/api/v1/templates"));
+        break;
+    }
+    case "templates:use": {
+        const id = positional[0];
+        const accounts = list(flags, "accounts");
+        if (!id)
+            fail("Usage: posthive templates:use <template_id> --accounts <id,id>");
+        if (!accounts?.length)
+            fail("--accounts is required (comma-separated account IDs)");
+        const schedule = str(flags, "schedule");
+        const body = {
+            accountIds: accounts,
+            draft: !schedule,
+            ...(schedule ? { scheduledFor: schedule } : {}),
+            ...(str(flags, "content") ? { contentOverride: str(flags, "content") } : {}),
+            ...(str(flags, "first-comment") ? { firstCommentOverride: str(flags, "first-comment") } : {}),
+        };
+        const data = await api("POST", `/api/v1/templates/${encodeURIComponent(id)}/use`, body);
+        out({
+            ...data,
+            _note: schedule ? "Post created from template and scheduled." : "Post created from template as DRAFT.",
+        });
+        break;
+    }
+    case "upload": {
+        const filePath = positional[0];
+        if (!filePath)
+            fail("Usage: posthive upload <file_path>");
+        let buf;
+        try {
+            buf = await readFile(filePath);
+        }
+        catch {
+            fail(`Cannot read file: ${filePath}`);
+        }
+        const form = new FormData();
+        form.append("file", new Blob([new Uint8Array(buf)]), basename(filePath));
+        let res;
+        try {
+            res = await fetch(`${API_URL}/upload`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${API_KEY}` },
+                body: form,
+            });
+        }
+        catch (err) {
+            fail(`Cannot reach Posthive API at ${API_URL} — check POSTHIVE_API_URL and your network. (${err instanceof Error ? err.message : String(err)})`);
+        }
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            json = { raw: text };
+        }
+        if (!res.ok) {
+            fail(`Upload failed (${res.status}): ${text}`);
+        }
+        out(json);
+        break;
+    }
+    default:
+        fail(`Unknown command: ${command}. Run "posthive help" for usage.`);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "posthive-cli",
+  "version": "0.1.0",
+  "description": "Posthive CLI — schedule posts to 11 social platforms from the command line or any AI agent (Claude Code, OpenClaw, Cursor)",
+  "type": "module",
+  "bin": {
+    "posthive": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "posthive",
+    "cli",
+    "social-media",
+    "scheduler",
+    "ai-agent",
+    "skill",
+    "claude",
+    "openclaw",
+    "bluesky",
+    "threads",
+    "linkedin",
+    "instagram",
+    "mastodon"
+  ],
+  "author": "Posthive",
+  "license": "AGPL-3.0",
+  "homepage": "https://posthive.co/for-developers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AstaBlackClove/posthive"
+  },
+  "bugs": {
+    "url": "https://github.com/AstaBlackClove/posthive/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "@types/node": "^20.14.12"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/posthive/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: posthive
+description: Schedule social media posts to 11 platforms (Bluesky, Threads, Instagram, LinkedIn, Mastodon, YouTube, Facebook Pages, Pinterest, Telegram, X/Twitter, Nostr) via the Posthive CLI. Use when the user asks to create, schedule, list, update, or delete social media posts, or manage their posting queue.
+---
+
+# Posthive — social media scheduling
+
+Schedule posts to 11 social platforms from the command line. Every command outputs structured JSON.
+
+## Setup
+
+Requires two environment variables:
+
+```bash
+export POSTHIVE_API_KEY=ph_xxx        # Posthive → Settings → API Keys (Pro/Team plan)
+export POSTHIVE_API_URL=https://api.posthive.co   # or your self-hosted URL
+```
+
+Run commands with `npx posthive-cli` or `posthive` if installed globally (`npm i -g posthive-cli`).
+
+## Workflow
+
+1. **Always start with `accounts:list`** to get valid account IDs — never guess IDs.
+2. Create posts with `posts:create`. **Posts are saved as DRAFTS by default** — the user reviews them in Posthive before anything publishes. Only pass `--schedule` when the user explicitly asks to schedule directly.
+3. Use `posts:approve` to promote a draft to the scheduled queue.
+
+## Commands
+
+```bash
+# List connected accounts (do this first)
+posthive accounts:list
+
+# Create a draft post
+posthive posts:create --content "Hello world" --accounts id1,id2
+
+# Create with first comment (link/hashtags go here, not the caption)
+posthive posts:create --content "Big launch today" --accounts id1 --first-comment "Details: https://example.com"
+
+# Schedule directly (skips draft review — only when user explicitly asks)
+posthive posts:create --content "Hello" --accounts id1 --schedule 2026-07-10T09:00:00Z
+
+# With media (upload first, then reference the returned URL)
+posthive upload ./image.png
+posthive posts:create --content "Check this out" --accounts id1 --media https://...returned-url...
+
+# Instagram Reel / Story (media required)
+posthive posts:create --content "New reel" --accounts ig_id --media <video_url> --media-type reel
+
+# YouTube Short
+posthive posts:create --content "Title here" --accounts yt_id --media <video_url> --youtube-type short
+
+# Queue management
+posthive posts:list --status draft
+posthive posts:get <post_id>
+posthive posts:update <post_id> --content "Fixed typo"
+posthive posts:approve <post_id> --schedule 2026-07-10T09:00:00Z
+posthive posts:duplicate <post_id>
+posthive posts:delete <post_id>
+
+# Templates
+posthive templates:list
+posthive templates:use <template_id> --accounts id1 --content "Optional override"
+
+# Dry run (full pipeline, no real API calls)
+posthive posts:create --content "Test" --accounts id1 --dry-run
+```
+
+## Platform notes
+
+| Platform | Char limit | Notes |
+|----------|-----------|-------|
+| Bluesky | 300 | |
+| Threads | 500 | |
+| Mastodon | 500 | |
+| X (Twitter) | 280 | Pro/Team plan, no links |
+| LinkedIn | 3,000 | Link in first comment performs better |
+| Instagram | 2,200 | Image/video required; use --media-type for reel/story |
+| YouTube | — | Video required; use --youtube-type short or video |
+| Pinterest | 500 | Image required |
+| Facebook Pages | 63,206 | |
+| Telegram | 4,096 | |
+| Nostr | — | |
+
+When posting to multiple platforms at once, keep content within the smallest char limit of the selected platforms, or create separate posts per platform with tailored content.
+
+## Best practices
+
+- Keep a human in the loop: default to drafts, let the user approve.
+- Timestamps are ISO 8601 UTC (e.g. `2026-07-10T09:00:00Z`). Confirm the user's timezone before scheduling.
+- Put links and hashtag walls in `--first-comment` rather than the main content on LinkedIn and Instagram.
+- On errors, the CLI exits non-zero and prints `{"error": "..."}` to stdout.