@socifyr/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,272 @@
-# Temporary Holding Version
+# socifyr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Post to 10+ social platforms from your terminal. Powered by [`@socifyr/sdk`](../sdk/README.md).
+
+**Supported platforms:** Instagram, Facebook, X (Twitter), LinkedIn, TikTok, YouTube, Threads, Pinterest, Reddit, Bluesky
+
+## Installation
+
+```bash
+npm install -g @socifyr/cli
+# or
+bun add -g @socifyr/cli
+```
+
+From the monorepo (unpublished):
+
+```bash
+cd packages/cli
+bun install
+bun run build
+node dist/cli.js --help   # or link the bin: npm link
+```
+
+## Setup
+
+```bash
+socifyr configure --key sk_ac4f91eb... --workspace 6a206187ff07beb18995bb91
+# ✓ Configuration saved
+#   API key: sk_ac4f91e...
+#   Workspace: 6a206187ff07beb18995bb91
+```
+
+Get your API key at **https://socifyr.com/dashboard/integrations#api-keys**. Check what's stored:
+
+```bash
+socifyr configure --show
+# Current configuration:
+#   API key:    sk_ac4f91e...
+#   Workspace:  6a206187ff07beb18995bb91
+```
+
+### Environment variables (override stored config)
+
+Handy for CI and scripts — no `configure` step needed:
+
+```bash
+export SOCIFYR_API_KEY=sk_...
+export SOCIFYR_WORKSPACE_ID=6a206187ff07beb18995bb91
+export SOCIFYR_API_URL=https://api.socifyr.com/api   # optional, self-hosted
+```
+
+---
+
+## Commands
+
+### `socifyr connections`
+
+List connected accounts and their slugs — **always start here** to learn what you can post to:
+
+```bash
+socifyr connections
+# 3 connected accounts:
+#
+#   📸  instagram-mybrand
+#       instagram · @mybrand
+#   🎵  tiktok-mybrand
+#       tiktok · mybrand
+#   ▶️  youtube-mybrand
+#       youtube · My Brand Channel
+#
+# Use slugs with: socifyr post "text" --to <slug1,slug2>
+```
+
+Flags: `--json` (raw JSON array), alias `conn`. Warns when a token expires within 7 days.
+
+---
+
+### `socifyr post [text]`
+
+Post text, images, video, or documents. Content can come from an argument, `--file`, or stdin:
+
+```bash
+# Text post
+socifyr post "Just shipped v2.0 🚀" --to x-myhandle,linkedin-mybrand
+
+# Caption from a file
+socifyr post --file CHANGELOG.md --to linkedin-mybrand --ai
+
+# Pipe it
+cat release-notes.md | socifyr post --to linkedin-mybrand --wait
+```
+
+**Media — local files** (auto-detects image vs video by extension; uploads to your media library first):
+
+```bash
+socifyr post "New drop" --media photo1.jpg,photo2.jpg --to instagram-mybrand
+socifyr post --media video.mp4 --to tiktok-mybrand,instagram-mybrand --ai --wait
+```
+
+**Media — library IDs or public URLs** (no re-upload; library IDs are resolved to their type, so a video ID is never posted as a photo):
+
+```bash
+socifyr post "Reuse library asset" --media-id 6a04f715d3d7d93575e65d13 --to instagram-mybrand
+socifyr post "From URL" --media-id https://example.com/banner.jpg --to linkedin-mybrand
+socifyr post "Deck" --media-id 6a93c01f... --to linkedin-mybrand        # document (PDF)
+```
+
+**Scheduling & drafts:**
+
+```bash
+socifyr post "Deploy complete" --to x-myhandle --at 2026-06-01T09:00
+socifyr post "Maybe later" --to x-myhandle --draft
+```
+
+| Flag | Description |
+|---|---|
+| `-t, --to <slugs>` | Comma-separated connection slugs (required) |
+| `-f, --file <path>` | Read caption from a text file |
+| `-m, --media <paths>` | Comma-separated local file paths (jpg, png, gif, webp, heic, mp4, mov, avi, mkv, webm, m4v) |
+| `--media-id <refs>` | Comma-separated media library IDs or public URLs |
+| `--format <format>` | `short_video`, `story`, `feed_video`, `photo_single`, `photo_carousel`, `text_post`, `document_post` |
+| `-a, --at <datetime>` | Schedule (ISO 8601) |
+| `--ai` | Generate the caption with AI (platform-specific, derived from your `--to` slugs) |
+| `-w, --wait` | Poll until done and print per-platform results |
+| `--draft` | Save as draft instead of publishing |
+| `--json` | Output raw JSON |
+
+Output without `--wait`:
+
+```
+✓ Post submitted
+  ID: 6b1f0c2a9d3e4f5a6b7c8d9e
+  Check status: socifyr status 6b1f0c2a9d3e4f5a6b7c8d9e
+```
+
+Output with `--wait`:
+
+```
+✓ published
+
+  ✓  youtube → https://youtube.com/shorts/6zaztTmk3Ck
+  ✗  instagram
+      Requires instagram_content_publish permission
+```
+
+Validation rules enforced before submitting: only one video per post, recognized extensions, non-empty content, valid `--format`.
+
+---
+
+### `socifyr status <id>`
+
+Check a post by upload ID, draft ID, or requestId:
+
+```bash
+socifyr status 6b1f0c2a9d3e4f5a6b7c8d9e
+# Post 6b1f0c2a9d3e4f5a6b7c8d9e
+# Status: partial_failure
+#
+#   ✓  youtube → https://youtube.com/shorts/6zaztTmk3Ck
+#   ✗  instagram
+#       Requires instagram_content_publish permission
+```
+
+Flags: `--json`, `-w, --wait` (poll until terminal).
+
+---
+
+### `socifyr retry <id>`
+
+Re-publish only the **failed** channels of a partial/failed post:
+
+```bash
+socifyr retry 6b1f0c2a9d3e4f5a6b7c8d9e --wait
+# Retrying failed channels...
+# Waiting for results...
+#
+# Post 6b1f0c2a9d3e4f5a6b7c8d9e
+# Status: completed
+#
+#   ✓  youtube → https://youtube.com/shorts/6zaztTmk3Ck
+#   ✓  instagram → https://instagram.com/p/DEF123/
+```
+
+Flags: `--json`, `-w, --wait`.
+
+---
+
+### `socifyr publish <id>`
+
+Publish a saved draft immediately:
+
+```bash
+socifyr publish 6b1f0c2a9d3e4f5a6b7c8d9e --wait
+# Publishing draft...
+# Waiting for results...
+#
+# Post 6b1f0c2a9d3e4f5a6b7c8d9e
+# Status: completed
+```
+
+Flags: `--json`, `-w, --wait`.
+
+---
+
+### `socifyr media`
+
+Manage your media library.
+
+**`media list`** — flags: `--type <image|video|document>`, `--search <query>`, `--limit <n>` (default 20), `--json`:
+
+```bash
+socifyr media list --type video
+# Media library (2 total)
+#
+#   🎬  launch-teaser.mp4
+#       ID: 6a93a4bfaa1135c3d8dd3df5   Size: 8.4MB   video
+#   🎬  demo-full.mp4
+#       ID: 6a93b7c2d1e0f3a4b5c6d7e8   Size: 156.2MB   video
+```
+
+**`media upload <file>`** — flags: `--alt <text>` (alt text/description), `--json`:
+
+```bash
+socifyr media upload banner.png --alt "Product banner"
+# Uploading banner.png...
+# ✓ Uploaded
+#   ID:   6a937894df74747da8fdb8ba
+#   File: banner.png
+#   Size: 245.3KB
+#   URL:  https://cdn.socifyr.com/...
+```
+
+**`media get <id>`** — flags: `--json`:
+
+```bash
+socifyr media get 6a937894df74747da8fdb8ba
+# 🖼  banner.png
+#   ID:       6a937894df74747da8fdb8ba
+#   Type:     image
+#   Alt:      Product banner
+```
+
+**`media delete <ids...>`** — one or many (bulk-deletes when given several), flags: `--json`:
+
+```bash
+socifyr media delete 6a937894df74747da8fdb8ba
+# ✓ Deleted 1 item
+
+socifyr media delete 6a93... 6a93... 6a93...
+# ✓ Deleted 3 items
+```
+
+---
+
+## Exit codes
+
+`0` on success, `1` on any failure (missing config, API error, validation). The error message from the API is printed on stderr — safe for scripting:
+
+```bash
+socifyr post "hi" --to nonexistent-slug || echo "post failed"
+# ✗ Failed to post
+# Connection "nonexistent-slug" not found
+# post failed
+```
+
+## JSON mode
+
+Every command accepts `--json` for machine-readable output (consumed on stdout; progress messages go to stderr):
+
+```bash
+socifyr status 6b1f0c2a... --json | jq '.status'
+```

package/dist/cli.js

@@ -0,0 +1,681 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/commands/configure.ts
+var import_chalk = __toESM(require("chalk"));
+
+// src/config.ts
+var import_os = require("os");
+var import_path = require("path");
+var import_fs = require("fs");
+var CONFIG_DIR = (0, import_path.join)((0, import_os.homedir)(), ".socifyr");
+var CONFIG_FILE = (0, import_path.join)(CONFIG_DIR, "config.json");
+function readConfig() {
+  if (!(0, import_fs.existsSync)(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse((0, import_fs.readFileSync)(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(patch) {
+  (0, import_fs.mkdirSync)(CONFIG_DIR, { recursive: true });
+  const current = readConfig();
+  (0, import_fs.writeFileSync)(CONFIG_FILE, JSON.stringify({ ...current, ...patch }, null, 2), "utf-8");
+}
+function resolveApiKey() {
+  return process.env.SOCIFYR_API_KEY || readConfig().apiKey;
+}
+function resolveWorkspaceId() {
+  return process.env.SOCIFYR_WORKSPACE_ID || readConfig().workspaceId;
+}
+function resolveApiUrl() {
+  return process.env.SOCIFYR_API_URL || readConfig().apiUrl || "https://api.socifyr.com/api";
+}
+
+// src/commands/configure.ts
+function registerConfigure(program2) {
+  program2.command("configure").description("Save your API key and workspace ID").option("-k, --key <key>", "API key (sk_...)").option("-w, --workspace <id>", "Workspace ID").option("--api-url <url>", "API base URL (for self-hosted)").option("--show", "Print current configuration").action((opts) => {
+    if (opts.show) {
+      const key = resolveApiKey();
+      const workspace = resolveWorkspaceId();
+      console.log(import_chalk.default.bold("Current configuration:"));
+      console.log(
+        `  API key:    ${key ? import_chalk.default.green(key.slice(0, 10) + "...") : import_chalk.default.dim("not set")}`
+      );
+      console.log(`  Workspace:  ${workspace ? import_chalk.default.green(workspace) : import_chalk.default.dim("not set")}`);
+      const config = readConfig();
+      if (config.apiUrl) console.log(`  API URL:    ${import_chalk.default.green(config.apiUrl)}`);
+      return;
+    }
+    if (!opts.key && !opts.workspace && !opts.apiUrl) {
+      console.log(import_chalk.default.yellow("Usage:"));
+      console.log(`  socifyr configure --key sk_... --workspace <id>`);
+      console.log(
+        `
+Get your API key and workspace ID at ${import_chalk.default.underline("https://socifyr.com/dashboard/integrations#api-keys")}`
+      );
+      return;
+    }
+    const patch = {};
+    if (opts.key) patch.apiKey = opts.key;
+    if (opts.workspace) patch.workspaceId = opts.workspace;
+    if (opts.apiUrl) patch.apiUrl = opts.apiUrl;
+    writeConfig(patch);
+    console.log(import_chalk.default.green("\u2713 Configuration saved"));
+    if (opts.key) console.log(`  API key: ${import_chalk.default.dim(opts.key.slice(0, 10) + "...")}`);
+    if (opts.workspace) console.log(`  Workspace: ${import_chalk.default.dim(opts.workspace)}`);
+  });
+}
+
+// src/commands/connections.ts
+var import_chalk3 = __toESM(require("chalk"));
+
+// src/client.ts
+var import_sdk = require("@socifyr/sdk");
+var import_chalk2 = __toESM(require("chalk"));
+function createClient() {
+  const apiKey = resolveApiKey();
+  const workspaceId = resolveWorkspaceId();
+  const apiUrl = resolveApiUrl();
+  if (!apiKey) {
+    console.error(import_chalk2.default.red("\u2717 No API key configured."));
+    console.error(
+      `  Run ${import_chalk2.default.cyan("socifyr configure --key sk_...")} or set ${import_chalk2.default.cyan("SOCIFYR_API_KEY")}`
+    );
+    console.error(
+      `  Get an API key at ${import_chalk2.default.underline("https://socifyr.com/dashboard/integrations#api-keys")}`
+    );
+    process.exit(1);
+  }
+  if (!workspaceId) {
+    console.error(import_chalk2.default.red("\u2717 No workspace ID configured."));
+    console.error(
+      `  Run ${import_chalk2.default.cyan("socifyr configure --workspace <id>")} or set ${import_chalk2.default.cyan("SOCIFYR_WORKSPACE_ID")}`
+    );
+    process.exit(1);
+  }
+  return new import_sdk.Socifyr({ apiKey, workspaceId, apiUrl });
+}
+
+// src/commands/connections.ts
+var PLATFORM_ICONS = {
+  instagram: "\u{1F4F8}",
+  facebook: "\u{1F465}",
+  twitter: "\u{1F426}",
+  x: "\u2715 ",
+  linkedin: "\u{1F4BC}",
+  tiktok: "\u{1F3B5}",
+  youtube: "\u25B6\uFE0F ",
+  pinterest: "\u{1F4CC}",
+  reddit: "\u{1F534}",
+  bluesky: "\u{1F98B}",
+  threads: "\u{1F9F5}",
+  mastodon: "\u{1F418}"
+};
+function registerConnections(program2) {
+  program2.command("connections").alias("conn").description("List connected social accounts").option("--json", "Output as JSON").action(async (opts) => {
+    const client = createClient();
+    const workspaceId = resolveWorkspaceId();
+    try {
+      const connections = await client.workspaces.listConnections(workspaceId);
+      const active = connections.filter((c) => !c.disconnectedAt);
+      if (opts.json) {
+        console.log(JSON.stringify(active, null, 2));
+        return;
+      }
+      if (active.length === 0) {
+        console.log(import_chalk3.default.yellow("No connected accounts found."));
+        console.log(`Connect accounts at ${import_chalk3.default.underline("https://socifyr.com/dashboard/integrations")}`);
+        return;
+      }
+      console.log(import_chalk3.default.bold(`
+${active.length} connected account${active.length === 1 ? "" : "s"}:
+`));
+      for (const c of active) {
+        const icon = PLATFORM_ICONS[c.platform] ?? "\u{1F517}";
+        const name = c.targetName ?? c.platformUsername;
+        const expiry = c.expiresAt ? new Date(c.expiresAt) : null;
+        const isExpiringSoon = expiry && expiry.getTime() - Date.now() < 7 * 24 * 60 * 60 * 1e3;
+        console.log(`  ${icon}  ${import_chalk3.default.bold(c.slug)}`);
+        console.log(`      ${import_chalk3.default.dim(c.platform)} \xB7 ${name}`);
+        if (isExpiringSoon) {
+          console.log(`      ${import_chalk3.default.yellow(`\u26A0 Token expires ${expiry.toLocaleDateString()}`)}`);
+        }
+      }
+      console.log();
+      console.log(import_chalk3.default.dim('Use slugs with: socifyr post "text" --to <slug1,slug2>'));
+    } catch (err) {
+      console.error(import_chalk3.default.red("\u2717 Failed to fetch connections"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/post.ts
+var import_fs2 = require("fs");
+var import_path2 = require("path");
+var import_chalk4 = __toESM(require("chalk"));
+var IMAGE_EXTS = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic"]);
+var VIDEO_EXTS = /* @__PURE__ */ new Set([".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v"]);
+function parseConnections(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseMediaPaths(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function detectMediaType(paths) {
+  if (paths.length === 0) return null;
+  const ext = (0, import_path2.extname)(paths[0]).toLowerCase();
+  if (IMAGE_EXTS.has(ext)) return "photo";
+  if (VIDEO_EXTS.has(ext)) return "video";
+  return null;
+}
+function formatStatus(status) {
+  switch (status) {
+    case "completed":
+      return import_chalk4.default.green("\u2713 published");
+    case "failed":
+      return import_chalk4.default.red("\u2717 failed");
+    case "partial_failure":
+      return import_chalk4.default.yellow("\u26A0 partial failure");
+    case "processing":
+      return import_chalk4.default.blue("\u27F3 processing");
+    case "publishing":
+      return import_chalk4.default.blue("\u27F3 publishing");
+    default:
+      return import_chalk4.default.dim(status);
+  }
+}
+function printResult(result) {
+  console.log(`
+${formatStatus(result.status)}
+`);
+  for (const ch of result.channels ?? []) {
+    const r = ch.result;
+    const icon = r?.status === "success" ? import_chalk4.default.green("\u2713") : import_chalk4.default.red("\u2717");
+    const link = r?.postUrl ? import_chalk4.default.dim(` \u2192 ${r.postUrl}`) : "";
+    console.log(`  ${icon}  ${import_chalk4.default.bold(ch.platform)}${link}`);
+    if (r?.error) console.log(`      ${import_chalk4.default.red(r.error)}`);
+  }
+  console.log();
+}
+var VALID_FORMATS = ["short_video", "story", "feed_video", "photo_single", "photo_carousel", "text_post", "document_post"];
+function registerPost(program2) {
+  program2.command("post [text]").description("Post to social platforms \u2014 text, images, or video").option("-t, --to <connections>", "Comma-separated connection slugs (e.g. twitter-me,linkedin-me)").option("-f, --file <path>", "Read caption from a text file").option("-m, --media <paths>", "Comma-separated local file paths (auto-detects image vs video)").option("--media-id <refs>", "Comma-separated media library IDs or public URLs (no upload needed)").option("--format <format>", `Content format: ${VALID_FORMATS.join(", ")}`).option("-a, --at <datetime>", "Schedule for a specific time (ISO 8601)").option("--ai", "Use AI to generate platform-specific captions").option("-w, --wait", "Wait for completion and show per-platform results").option("--json", "Output as JSON").option("--draft", "Save as draft without publishing").addHelpText("after", `
+Media examples:
+  $ socifyr post "Check this out!" --media photo.jpg --to instagram-me
+  $ socifyr post --media video.mp4 --to tiktok-me,instagram-me --ai --wait
+  $ socifyr post "New product" --media img1.jpg,img2.jpg --to instagram-me
+  $ socifyr post "Reuse library asset" --media-id 6a04f715d3d7d93575e65d13 --to instagram-me
+  $ socifyr post "From URL" --media-id https://example.com/banner.jpg --to linkedin-me
+  $ socifyr post "Reel" --media video.mp4 --format short_video --to instagram-me
+`).action(async (text, opts) => {
+    let caption = text ?? "";
+    if (opts.file) {
+      if (!(0, import_fs2.existsSync)(opts.file)) {
+        console.error(import_chalk4.default.red(`\u2717 File not found: ${opts.file}`));
+        process.exit(1);
+      }
+      caption = (0, import_fs2.readFileSync)(opts.file, "utf-8").trim();
+    }
+    if (!caption && !process.stdin.isTTY) {
+      caption = (0, import_fs2.readFileSync)("/dev/stdin", "utf-8").trim();
+    }
+    const mediaPaths = opts.media ? parseMediaPaths(opts.media) : [];
+    const mediaType = detectMediaType(mediaPaths);
+    if (mediaPaths.length > 0) {
+      for (const p of mediaPaths) {
+        if (!(0, import_fs2.existsSync)(p)) {
+          console.error(import_chalk4.default.red(`\u2717 Media file not found: ${p}`));
+          process.exit(1);
+        }
+      }
+      if (!mediaType) {
+        console.error(import_chalk4.default.red(`\u2717 Unrecognized media type: ${(0, import_path2.extname)(mediaPaths[0])}`));
+        console.error(`  Supported: ${[...IMAGE_EXTS, ...VIDEO_EXTS].join(", ")}`);
+        process.exit(1);
+      }
+    }
+    const mediaIdRefs = opts.mediaId ? parseMediaPaths(opts.mediaId) : [];
+    const client = createClient();
+    let effectiveMediaType = mediaType;
+    if (effectiveMediaType === null && mediaIdRefs.length > 0) {
+      const isUrlRef = (ref) => ref.startsWith("http://") || ref.startsWith("https://");
+      let libraryTypes = [];
+      try {
+        libraryTypes = await Promise.all(
+          mediaIdRefs.filter((ref) => !isUrlRef(ref)).map(async (id) => (await client.media.get(id)).type)
+        );
+      } catch (err) {
+        console.error(import_chalk4.default.red("\u2717 Failed to resolve media library ID"));
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+      const hasVideoRef = libraryTypes.includes("video") || mediaIdRefs.some(
+        (ref) => isUrlRef(ref) && VIDEO_EXTS.has((0, import_path2.extname)(ref.split("?")[0]).toLowerCase())
+      );
+      effectiveMediaType = hasVideoRef ? "video" : libraryTypes.includes("document") ? "document" : "photo";
+    }
+    if (effectiveMediaType === "video" && mediaPaths.length + mediaIdRefs.length > 1) {
+      console.error(import_chalk4.default.red("\u2717 Only one video file can be posted at a time"));
+      process.exit(1);
+    }
+    if (opts.format && !VALID_FORMATS.includes(opts.format)) {
+      console.error(import_chalk4.default.red(`\u2717 Invalid format: ${opts.format}`));
+      console.error(`  Valid formats: ${VALID_FORMATS.join(", ")}`);
+      process.exit(1);
+    }
+    if (!caption && !opts.ai && mediaPaths.length === 0 && mediaIdRefs.length === 0) {
+      console.error(import_chalk4.default.red("\u2717 No content provided."));
+      console.error("  Pass text inline, use --file, --media, --media-id, or pipe via stdin.");
+      process.exit(1);
+    }
+    if (!opts.to) {
+      console.error(import_chalk4.default.red("\u2717 No connections specified."));
+      console.error(`  Use ${import_chalk4.default.cyan("socifyr connections")} to see available slugs`);
+      process.exit(1);
+    }
+    const connections = parseConnections(opts.to);
+    try {
+      if (opts.ai) {
+        if (!opts.json) process.stderr.write(import_chalk4.default.dim("Generating AI captions...\n"));
+        const uploadType = effectiveMediaType ?? "text";
+        const platforms = Array.from(new Set(
+          connections.map((c) => c.split("-")[0]).filter(Boolean)
+        ));
+        const generated = await client.ai.generateContent({
+          uploadType,
+          platforms,
+          description: caption || void 0
+        });
+        const firstCaption = Object.values(generated.content ?? {})[0];
+        caption = firstCaption ?? caption;
+      }
+      const action = opts.draft ? "Saving draft" : opts.at ? `Scheduling for ${opts.at}` : "Publishing";
+      if (!opts.json) {
+        const totalMediaCount = mediaPaths.length + mediaIdRefs.length;
+        const typeLabel = effectiveMediaType === "video" ? "video" : effectiveMediaType === "document" ? `${totalMediaCount} document${totalMediaCount > 1 ? "s" : ""}` : effectiveMediaType === "photo" ? `${totalMediaCount} image${totalMediaCount > 1 ? "s" : ""}` : "text post";
+        process.stderr.write(import_chalk4.default.dim(`${action} ${typeLabel} to ${connections.length} account${connections.length === 1 ? "" : "s"}...
+`));
+      }
+      const baseParams = {
+        connections,
+        text: caption || void 0,
+        scheduledAt: opts.at,
+        saveDraft: opts.draft,
+        ...opts.format ? { contentFormat: opts.format } : {}
+      };
+      const uploadedIds = [];
+      for (const p of mediaPaths) {
+        if (!opts.json) {
+          process.stderr.write(import_chalk4.default.dim(`Uploading ${(0, import_path2.basename)(p)}...
+`));
+        }
+        const item = await client.media.upload((0, import_fs2.readFileSync)(p), (0, import_path2.basename)(p));
+        uploadedIds.push(item.id);
+      }
+      const allMedias = [...uploadedIds, ...mediaIdRefs];
+      let upload;
+      if (effectiveMediaType === "video") {
+        upload = await client.uploads.video({
+          ...baseParams,
+          medias: [allMedias[0]]
+        });
+      } else if (effectiveMediaType === "document") {
+        upload = await client.uploads.document({
+          ...baseParams,
+          medias: allMedias
+        });
+      } else if (effectiveMediaType === "photo") {
+        upload = await client.uploads.photos({
+          ...baseParams,
+          medias: allMedias
+        });
+      } else {
+        if (!caption) {
+          console.error(import_chalk4.default.red("\u2717 Text post requires non-empty content."));
+          process.exit(1);
+        }
+        upload = await client.uploads.text({ ...baseParams, text: caption });
+      }
+      if (opts.wait && !opts.draft) {
+        if (!opts.json) process.stderr.write(import_chalk4.default.dim("Waiting for results...\n"));
+        const result = await client.uploads.waitForCompletion(upload.id);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        printResult(result);
+        return;
+      }
+      if (opts.json) {
+        console.log(JSON.stringify(upload, null, 2));
+        return;
+      }
+      const postId = upload.id;
+      const actionLabel = opts.draft ? "Draft saved" : opts.at ? "Scheduled" : "Post submitted";
+      console.log(import_chalk4.default.green(`\u2713 ${actionLabel}`));
+      console.log(`  ID: ${import_chalk4.default.dim(postId)}`);
+      if (!opts.draft && !opts.at) {
+        console.log(`  Check status: ${import_chalk4.default.cyan(`socifyr status ${postId}`)}`);
+      }
+    } catch (err) {
+      console.error(import_chalk4.default.red("\u2717 Failed to post"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/status.ts
+var import_chalk5 = __toESM(require("chalk"));
+function statusColor(status) {
+  switch (status) {
+    case "completed":
+      return import_chalk5.default.green(status);
+    case "failed":
+      return import_chalk5.default.red(status);
+    case "partial_failure":
+      return import_chalk5.default.yellow(status);
+    case "processing":
+    case "publishing":
+      return import_chalk5.default.blue(status);
+    default:
+      return import_chalk5.default.dim(status);
+  }
+}
+function registerStatus(program2) {
+  program2.command("status <id>").description("Check the status of a post").option("--json", "Output as JSON").option("-w, --wait", "Poll until complete").action(async (id, opts) => {
+    const client = createClient();
+    try {
+      const result = opts.wait ? await client.uploads.waitForCompletion(id) : await client.uploads.getStatus(id);
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(`
+Post ${import_chalk5.default.bold(id)}`);
+      console.log(`Status: ${statusColor(result.status)}
+`);
+      for (const ch of result.channels ?? []) {
+        const r = ch.result;
+        const icon = r?.status === "success" ? import_chalk5.default.green("\u2713") : r?.status === "failed" ? import_chalk5.default.red("\u2717") : import_chalk5.default.dim("\xB7");
+        const link = r?.postUrl ? import_chalk5.default.dim(` \u2192 ${r.postUrl}`) : "";
+        console.log(`  ${icon}  ${import_chalk5.default.bold(ch.platform)}${link}`);
+        if (r?.error) console.log(`      ${import_chalk5.default.red(r.error)}`);
+      }
+      console.log();
+    } catch (err) {
+      console.error(import_chalk5.default.red("\u2717 Failed to fetch status"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/manage.ts
+var import_chalk6 = __toESM(require("chalk"));
+function registerManage(program2) {
+  program2.command("retry <id>").description("Retry failed channels for a post").option("--json", "Output as JSON").option("-w, --wait", "Wait for completion and show results").action(async (id, opts) => {
+    const client = createClient();
+    try {
+      if (!opts.json) process.stderr.write(import_chalk6.default.dim("Retrying failed channels...\n"));
+      const upload = await client.uploads.retry(id);
+      if (opts.wait) {
+        if (!opts.json) process.stderr.write(import_chalk6.default.dim("Waiting for results...\n"));
+        const result = await client.uploads.waitForCompletion(id);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(`
+Post ${import_chalk6.default.bold(id)}`);
+        console.log(`Status: ${import_chalk6.default.green(result.status)}
+`);
+        for (const ch of result.channels ?? []) {
+          const r = ch.result;
+          const icon = r?.status === "success" ? import_chalk6.default.green("\u2713") : r?.status === "failed" ? import_chalk6.default.red("\u2717") : import_chalk6.default.dim("\xB7");
+          const link = r?.postUrl ? import_chalk6.default.dim(` \u2192 ${r.postUrl}`) : "";
+          console.log(`  ${icon}  ${import_chalk6.default.bold(ch.platform)}${link}`);
+          if (r?.error) console.log(`      ${import_chalk6.default.red(r.error)}`);
+        }
+        console.log();
+        return;
+      }
+      if (opts.json) {
+        console.log(JSON.stringify(upload, null, 2));
+        return;
+      }
+      console.log(import_chalk6.default.green("\u2713 Retry queued"));
+      console.log(`  ID: ${import_chalk6.default.dim(upload.id)}`);
+      console.log(`  Check status: ${import_chalk6.default.cyan(`socifyr status ${upload.id}`)}`);
+    } catch (err) {
+      console.error(import_chalk6.default.red("\u2717 Failed to retry"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+  program2.command("publish <id>").description("Publish a saved draft").option("--json", "Output as JSON").option("-w, --wait", "Wait for completion and show results").action(async (id, opts) => {
+    const client = createClient();
+    try {
+      if (!opts.json) process.stderr.write(import_chalk6.default.dim("Publishing draft...\n"));
+      const upload = await client.uploads.publishDraft(id);
+      if (opts.wait) {
+        if (!opts.json) process.stderr.write(import_chalk6.default.dim("Waiting for results...\n"));
+        const result = await client.uploads.waitForCompletion(id);
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(`
+Post ${import_chalk6.default.bold(id)}`);
+        console.log(`Status: ${import_chalk6.default.green(result.status)}
+`);
+        for (const ch of result.channels ?? []) {
+          const r = ch.result;
+          const icon = r?.status === "success" ? import_chalk6.default.green("\u2713") : r?.status === "failed" ? import_chalk6.default.red("\u2717") : import_chalk6.default.dim("\xB7");
+          const link = r?.postUrl ? import_chalk6.default.dim(` \u2192 ${r.postUrl}`) : "";
+          console.log(`  ${icon}  ${import_chalk6.default.bold(ch.platform)}${link}`);
+          if (r?.error) console.log(`      ${import_chalk6.default.red(r.error)}`);
+        }
+        console.log();
+        return;
+      }
+      if (opts.json) {
+        console.log(JSON.stringify(upload, null, 2));
+        return;
+      }
+      console.log(import_chalk6.default.green("\u2713 Draft published"));
+      console.log(`  ID: ${import_chalk6.default.dim(upload.id)}`);
+      console.log(`  Check status: ${import_chalk6.default.cyan(`socifyr status ${upload.id}`)}`);
+    } catch (err) {
+      console.error(import_chalk6.default.red("\u2717 Failed to publish draft"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/media.ts
+var import_fs3 = require("fs");
+var import_path3 = require("path");
+var import_chalk7 = __toESM(require("chalk"));
+var TYPE_ICON = {
+  image: "\u{1F5BC} ",
+  video: "\u{1F3AC}",
+  document: "\u{1F4C4}"
+};
+function formatBytes(bytes) {
+  if (!bytes) return "\u2014";
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function registerMedia(program2) {
+  const media = program2.command("media").description("Manage your media library");
+  media.command("list").description("List media library items").option("--type <type>", "Filter by type: image, video, document").option("--search <query>", "Search by filename").option("--limit <n>", "Max results (default: 20)", "20").option("--json", "Output as JSON").action(async (opts) => {
+    const client = createClient();
+    try {
+      const result = await client.media.list({
+        type: opts.type,
+        search: opts.search,
+        limit: parseInt(opts.limit ?? "20", 10)
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const items = result.results ?? result.data ?? [];
+      if (!items || items.length === 0) {
+        console.log(import_chalk7.default.dim("No media found."));
+        return;
+      }
+      const total = result.total ?? items.length;
+      console.log(`
+${import_chalk7.default.bold("Media library")} (${total} total)
+`);
+      for (const item of items) {
+        const icon = TYPE_ICON[item.type] ?? "  ";
+        console.log(`  ${icon}  ${import_chalk7.default.bold(item.name)}`);
+        console.log(`      ${import_chalk7.default.dim(`ID: ${item.id}   Size: ${formatBytes(item.sizeBytes)}   ${item.type}`)}`);
+        if (item.alt) console.log(`      ${import_chalk7.default.dim(`Alt: ${item.alt}`)}`);
+      }
+      console.log();
+    } catch (err) {
+      console.error(import_chalk7.default.red("\u2717 Failed to list media"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+  media.command("upload <file>").description("Upload a file to the media library").option("--alt <text>", "Alt text / description").option("--json", "Output as JSON").action(async (file, opts) => {
+    if (!(0, import_fs3.existsSync)(file)) {
+      console.error(import_chalk7.default.red(`\u2717 File not found: ${file}`));
+      process.exit(1);
+    }
+    const client = createClient();
+    try {
+      if (!opts.json) process.stderr.write(import_chalk7.default.dim(`Uploading ${(0, import_path3.basename)(file)}...
+`));
+      const item = await client.media.upload((0, import_fs3.readFileSync)(file), (0, import_path3.basename)(file));
+      if (opts.alt) {
+        await client.media.update(item.id, { alt: opts.alt });
+      }
+      if (opts.json) {
+        console.log(JSON.stringify(item, null, 2));
+        return;
+      }
+      console.log(import_chalk7.default.green(`\u2713 Uploaded`));
+      console.log(`  ID:   ${import_chalk7.default.cyan(item.id)}`);
+      console.log(`  File: ${import_chalk7.default.dim(item.name)}`);
+      console.log(`  Size: ${import_chalk7.default.dim(formatBytes(item.sizeBytes))}`);
+      console.log(`  URL:  ${import_chalk7.default.dim(item.url)}`);
+    } catch (err) {
+      console.error(import_chalk7.default.red("\u2717 Upload failed"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+  media.command("get <id>").description("Get details of a media item").option("--json", "Output as JSON").action(async (id, opts) => {
+    const client = createClient();
+    try {
+      const item = await client.media.get(id);
+      if (opts.json) {
+        console.log(JSON.stringify(item, null, 2));
+        return;
+      }
+      const icon = TYPE_ICON[item.type] ?? "  ";
+      console.log(`
+${icon}  ${import_chalk7.default.bold(item.name)}`);
+      console.log(`  ID:       ${import_chalk7.default.cyan(item.id)}`);
+      console.log(`  Type:     ${import_chalk7.default.dim(item.type)}`);
+      console.log(`  Size:     ${import_chalk7.default.dim(formatBytes(item.sizeBytes))}`);
+      console.log(`  URL:      ${import_chalk7.default.dim(item.url)}`);
+      if (item.alt) console.log(`  Alt:      ${import_chalk7.default.dim(item.alt)}`);
+      if (item.description) console.log(`  Desc:     ${import_chalk7.default.dim(item.description)}`);
+      if (item.tags?.length) console.log(`  Tags:     ${import_chalk7.default.dim(item.tags.join(", "))}`);
+      console.log();
+    } catch (err) {
+      console.error(import_chalk7.default.red("\u2717 Failed to get media"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+  media.command("delete <ids...>").description("Delete one or more media items").option("--json", "Output as JSON").action(async (ids, opts) => {
+    const client = createClient();
+    try {
+      if (ids.length === 1) {
+        await client.media.delete(ids[0]);
+      } else {
+        await client.media.bulkDelete(ids);
+      }
+      if (opts.json) {
+        console.log(JSON.stringify({ deleted: ids }));
+        return;
+      }
+      console.log(import_chalk7.default.green(`\u2713 Deleted ${ids.length} item${ids.length === 1 ? "" : "s"}`));
+    } catch (err) {
+      console.error(import_chalk7.default.red("\u2717 Delete failed"));
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli.ts
+import_commander.program.name("socifyr").description("Post to 10+ social platforms from your terminal").version("0.1.0").addHelpText("after", `
+Examples:
+  $ socifyr configure --key sk_... --workspace <id>
+  $ socifyr connections
+  $ socifyr post "Just shipped v2.0 \u{1F680}" --to twitter-me,linkedin-me
+  $ socifyr post --file CHANGELOG.md --to linkedin-me --ai
+  $ socifyr post "Deploy complete" --to twitter-me --at "2026-06-01T09:00"
+  $ cat release-notes.md | socifyr post --to linkedin-me --wait
+  $ socifyr status <post-id>
+  $ socifyr retry <post-id> --wait
+  $ socifyr publish <draft-id>
+  $ socifyr media list --type image
+  $ socifyr media upload banner.png --alt "Product banner"
+  $ socifyr media delete <media-id>
+
+Env vars (override stored config):
+  SOCIFYR_API_KEY        Your API key
+  SOCIFYR_WORKSPACE_ID   Your workspace ID
+  SOCIFYR_API_URL        Custom API URL (self-hosted)
+`);
+registerConfigure(import_commander.program);
+registerConnections(import_commander.program);
+registerPost(import_commander.program);
+registerStatus(import_commander.program);
+registerManage(import_commander.program);
+registerMedia(import_commander.program);
+import_commander.program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@socifyr/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLI for Socifyr — post to 10+ social platforms from your terminal",
+  "license": "AGPL-3.0-or-later",
+  "bin": {
+    "socifyr": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@socifyr/sdk": "0.1.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^25.5.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.9",
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "socifyr",
+    "social-media",
+    "cli",
+    "instagram",
+    "twitter",
+    "linkedin",
+    "tiktok"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/socifyr/socifyr",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://socifyr.com/docs/cli"
+}