@posteverywhere/cli 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @posteverywhere/cli
+
+The PostEverywhere CLI for AI agents — schedule and publish to Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Telegram and Discord from the command line. Every command outputs structured JSON for agents (Claude, Cursor, OpenClaw, …) to parse.
+
+## Quick start
+
+```bash
+export POSTEVERYWHERE_API_KEY=pe_live_...   # Settings → Developers in the dashboard
+
+npx @posteverywhere/cli whoami              # verify the key
+npx @posteverywhere/cli accounts            # list connected accounts (+ ids)
+npx @posteverywhere/cli post -c "Hello 🚀" -a 123,456          # publish now
+npx @posteverywhere/cli post -c "Later" -a 123 -s 2026-07-01T09:00:00Z   # schedule (UTC)
+```
+
+Run `npx @posteverywhere/cli help` for the full command list.
+
+## For AI agents
+
+This package ships a `SKILL.md` describing the commands for agent auto-discovery. Point your agent at it, or connect via MCP instead:
+
+- **Hosted MCP (no install):** `https://mcp.posteverywhere.ai` — see [docs](https://developers.posteverywhere.ai/integrations/mcp)
+- **Local MCP:** `npx -y @posteverywhere/mcp`
+
+## Auth & safety
+
+Your API key authenticates into **your PostEverywhere account** and acts only through it — the CLI never touches your social-platform credentials directly. Keep a human in the loop before publishing.

package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: posteverywhere
+description: Schedule and publish social media posts to Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Telegram and Discord. Use when the user asks to post, schedule, draft, or analyze social media content, or to list their connected social accounts.
+---
+
+# PostEverywhere
+
+Manage a user's social media through the PostEverywhere CLI. Every command prints JSON.
+
+## Setup (once)
+The user must set their API key (from posteverywhere.ai → Settings → Developers):
+```bash
+export POSTEVERYWHERE_API_KEY=pe_live_...
+```
+Run commands with `npx @posteverywhere/cli <command>` (or `posteverywhere <command>` if installed).
+
+## Always start here
+1. `posteverywhere whoami` — confirms the key works and shows the plan/quota.
+2. `posteverywhere accounts` — lists connected accounts. **You need the numeric account `id`s to post.** If empty, tell the user to connect accounts in the dashboard first.
+
+## Core workflow
+**Publish now** to accounts 123 and 456:
+```bash
+posteverywhere post -c "Launch day! 🚀" -a 123,456
+```
+**Schedule** (ISO-8601 UTC; include -s):
+```bash
+posteverywhere post -c "Weekly tips thread" -a 123 -s 2026-07-01T09:00:00Z
+```
+**With an image** — import it first, then attach the returned `media_id`:
+```bash
+posteverywhere upload https://example.com/photo.jpg      # → { "media_id": "..." }
+posteverywhere post -c "New drop" -a 123 -m <media_id>
+```
+
+## Checking results
+- `posteverywhere posts --status published --limit 10` — recent posts
+- `posteverywhere results <postId>` — per-platform success/failure for one post
+- `posteverywhere retry <postId>` — retry any failed platforms
+- `posteverywhere account:health <id>` — why an account can't post (e.g. needs reconnect)
+
+## Other
+- `posteverywhere caption -t "summer sale" --platform instagram --tone playful` — AI captions
+- `posteverywhere analytics --period month` — performance summary
+- `posteverywhere campaigns` — list campaigns
+
+## Rules
+- **Always `accounts` before `post`** — never guess account ids.
+- **Always confirm content + target accounts with the user before publishing.** Keep a human in the loop.
+- Times are UTC ISO-8601. Omit `-s` to publish immediately.
+- On error the CLI prints `{"error": "..."}` to stderr and exits non-zero — read it and relay the cause (often: account needs reconnect, out of quota, or media not ready).

package/dist/index.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * PostEverywhere CLI for AI agents (task #245, "skill" distribution).
+ *
+ * Thin wrapper over the public v1 REST API. Every command prints structured
+ * JSON to stdout so agents (Claude, Cursor, OpenClaw, etc.) can parse results.
+ * Auth: set POSTEVERYWHERE_API_KEY=pe_live_... (Settings → Developers).
+ *
+ * Same surface as the MCP server, for agents that run shell commands rather
+ * than speak MCP. See SKILL.md for the agent-facing command reference.
+ */
+const BASE = (process.env.POSTEVERYWHERE_API_URL || 'https://app.posteverywhere.ai').replace(/\/$/, '');
+const KEY = process.env.POSTEVERYWHERE_API_KEY || '';
+function out(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+function fail(message, code = 1) {
+    process.stderr.write(JSON.stringify({ error: message }) + '\n');
+    process.exit(code);
+}
+// Parse "cmd positional --flag value -f value --bool" into { _: [...], flags }.
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--') || a.startsWith('-')) {
+            const key = a.replace(/^-+/, '');
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                flags[key] = next;
+                i++;
+            }
+            else
+                flags[key] = true;
+        }
+        else
+            positional.push(a);
+    }
+    return { positional, flags };
+}
+async function api(method, path, body) {
+    if (!KEY || !KEY.startsWith('pe_live_')) {
+        fail('Missing or invalid POSTEVERYWHERE_API_KEY (must start with pe_live_). Create one at ' + BASE + ' → Settings → Developers.');
+    }
+    let resp;
+    try {
+        resp = await fetch(`${BASE}/api/v1${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${KEY}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (e) {
+        fail(`Network error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const json = await resp.json().catch(() => ({ error: { message: `HTTP ${resp.status}` } }));
+    if (json.error)
+        fail(typeof json.error === 'string' ? json.error : json.error.message || 'API error');
+    return json.data;
+}
+const csv = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : []);
+const num = (v) => csv(v).map(Number).filter((n) => !Number.isNaN(n));
+const HELP = `PostEverywhere CLI — manage social media from the command line / AI agents.
+
+Auth:  export POSTEVERYWHERE_API_KEY=pe_live_...   (Settings → Developers)
+
+Commands:
+  whoami                         Show the authed account, quota, and scopes
+  accounts                       List connected social accounts (+ their ids/health)
+  account:health <id>            Detailed health for one account
+  post -c <text> -a <ids> [-s <iso>] [-m <media_ids>]
+                                 Create/schedule a post (-a = comma account ids; omit -s = publish now)
+  posts [--status x] [--platform y] [--limit n]
+                                 List posts
+  results <postId>               Per-platform publish results for a post
+  retry <postId>                 Retry failed destinations of a post
+  upload <imageUrl>              Import an image by URL (one-call), returns media_id
+  caption -t <topic> [--platform x] [--tone y]
+                                 Generate AI captions
+  analytics [--period week|month|all]
+                                 Account analytics summary
+  campaigns                      List campaigns
+
+All output is JSON on stdout. Errors are JSON on stderr with a non-zero exit.
+Docs: https://developers.posteverywhere.ai/integrations/mcp`;
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    const { positional, flags } = parseArgs(rest);
+    const f = (k, alias) => (flags[k] ?? (alias ? flags[alias] : undefined));
+    switch (cmd) {
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            process.stdout.write(HELP + '\n');
+            return;
+        case 'whoami':
+            return out(await api('GET', '/me'));
+        case 'accounts':
+            return out(await api('GET', '/accounts'));
+        case 'account:health': {
+            const id = positional[0];
+            if (!id)
+                fail('Usage: posteverywhere account:health <accountId>');
+            return out(await api('GET', `/accounts/${id}/health`));
+        }
+        case 'post': {
+            const content = f('content', 'c');
+            const accounts = num(f('accounts', 'a'));
+            if (typeof content !== 'string' || !content)
+                fail('Usage: post -c "text" -a 123,456 [-s 2026-07-01T09:00:00Z] [-m mediaId1,mediaId2]');
+            if (!accounts.length)
+                fail('At least one account id is required (-a 123,456). Run `posteverywhere accounts` to list ids.');
+            const body = { content, account_ids: accounts };
+            const sched = f('schedule', 's');
+            if (typeof sched === 'string') {
+                body.scheduled_for = sched;
+                body.timezone = f('timezone') || 'UTC';
+            }
+            const media = csv(f('media', 'm'));
+            if (media.length)
+                body.media_ids = media;
+            return out(await api('POST', '/posts', body));
+        }
+        case 'posts': {
+            const q = new URLSearchParams();
+            if (typeof f('status') === 'string')
+                q.set('status', f('status'));
+            if (typeof f('platform') === 'string')
+                q.set('platform', f('platform'));
+            q.set('limit', String(f('limit') || 20));
+            return out(await api('GET', `/posts?${q.toString()}`));
+        }
+        case 'results': {
+            if (!positional[0])
+                fail('Usage: posteverywhere results <postId>');
+            return out(await api('GET', `/posts/${positional[0]}/results`));
+        }
+        case 'retry': {
+            if (!positional[0])
+                fail('Usage: posteverywhere retry <postId>');
+            return out(await api('POST', `/posts/${positional[0]}/retry`));
+        }
+        case 'upload': {
+            const url = positional[0] || f('url');
+            if (typeof url !== 'string')
+                fail('Usage: posteverywhere upload <imageUrl>');
+            return out(await api('POST', '/media/upload-from-url', { url }));
+        }
+        case 'caption': {
+            const topic = f('topic', 't');
+            if (typeof topic !== 'string')
+                fail('Usage: posteverywhere caption -t "topic" [--platform x] [--tone y]');
+            const body = { topic };
+            if (typeof f('platform') === 'string')
+                body.platform = f('platform');
+            if (typeof f('tone') === 'string')
+                body.tone = f('tone');
+            return out(await api('POST', '/ai/generate-caption', body));
+        }
+        case 'analytics': {
+            const period = f('period') || 'month';
+            return out(await api('GET', `/analytics/summary?period=${encodeURIComponent(period)}`));
+        }
+        case 'campaigns':
+            return out(await api('GET', '/campaigns'));
+        default:
+            fail(`Unknown command: ${cmd}. Run \`posteverywhere help\` for the command list.`);
+    }
+}
+main().catch((e) => fail(e instanceof Error ? e.message : String(e)));

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@posteverywhere/cli",
+  "version": "0.1.0",
+  "description": "PostEverywhere CLI for AI agents — schedule and publish to Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Telegram & Discord from the command line. Structured JSON output for Claude, Cursor, and other agents.",
+  "type": "module",
+  "bin": {
+    "posteverywhere": "dist/index.js"
+  },
+  "files": ["dist", "SKILL.md", "README.md"],
+  "engines": { "node": ">=18.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["social media", "cli", "ai agent", "claude", "mcp", "scheduling", "automation"],
+  "license": "MIT",
+  "devDependencies": { "typescript": "^5.6.0", "@types/node": "^20.0.0" }
+}