superx-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1280 @@
+#!/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/index.ts
+var import_yargs = __toESM(require("yargs"));
+var import_helpers = require("yargs/helpers");
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(status2, code, message, retryAfter = null) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status2;
+    this.code = code;
+    this.retryAfter = retryAfter;
+  }
+};
+var SuperXAPI = class {
+  constructor(config) {
+    /** Rate-limit headers from the most recent authenticated response. */
+    this.lastRateLimit = null;
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl.replace(/\/+$/, "");
+  }
+  buildUrl(endpoint, query) {
+    let url = `${this.apiUrl}${endpoint}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== null && value !== "") {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    return url;
+  }
+  captureRateLimit(headers) {
+    const num = (name) => {
+      const v = headers.get(name);
+      if (v === null) return null;
+      const n = Number(v);
+      return Number.isFinite(n) ? n : null;
+    };
+    if (headers.get("x-ratelimit-limit") !== null) {
+      this.lastRateLimit = {
+        limit: num("x-ratelimit-limit"),
+        remaining: num("x-ratelimit-remaining"),
+        reset: num("x-ratelimit-reset")
+      };
+    }
+  }
+  /** Perform a request. Non-2xx responses throw ApiError with the API's code. */
+  async request(endpoint, options = {}) {
+    const url = this.buildUrl(endpoint, options.query);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...options.headers
+    };
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method: options.method || "GET",
+        headers,
+        body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+      });
+    } catch (err) {
+      throw new ApiError(0, "network_error", `Could not reach ${this.apiUrl} (${err?.message || err})`);
+    }
+    this.captureRateLimit(response.headers);
+    const text = await response.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    if (!response.ok) {
+      const retryHeader = response.headers.get("retry-after");
+      const retryAfter = retryHeader !== null && Number.isFinite(Number(retryHeader)) ? Number(retryHeader) : null;
+      let code = `http_${response.status}`;
+      let message = `Request failed with HTTP ${response.status}`;
+      const errField = json?.error;
+      if (errField && typeof errField === "object" && typeof errField.code === "string") {
+        code = errField.code;
+        if (typeof errField.message === "string") message = errField.message;
+      } else if (typeof errField === "string") {
+        code = errField.split(":")[0].trim() || code;
+        message = errField;
+      }
+      throw new ApiError(response.status, code, message, retryAfter);
+    }
+    return { status: response.status, headers: response.headers, json };
+  }
+  // --- Identity ---
+  async me() {
+    return (await this.request("/me")).json;
+  }
+  async accounts(query = {}) {
+    return (await this.request("/accounts", { query })).json;
+  }
+  // --- Posts and analytics ---
+  async listPosts(query = {}) {
+    return (await this.request("/posts", { query })).json;
+  }
+  async postsAnalytics(query = {}) {
+    return (await this.request("/posts/analytics", { query })).json;
+  }
+  async listReplies(query = {}) {
+    return (await this.request("/replies", { query })).json;
+  }
+  async receivedReplies(query = {}) {
+    return (await this.request("/replies/received", { query })).json;
+  }
+  // --- Inspiration ---
+  async searchInspiration(query = {}) {
+    return (await this.request("/inspiration", { query })).json;
+  }
+  // --- Contacts ---
+  async listContacts(query = {}) {
+    return (await this.request("/contacts", { query })).json;
+  }
+  async contactReplies(contactId, query = {}) {
+    return (await this.request(`/contacts/${encodeURIComponent(contactId)}/replies`, { query })).json;
+  }
+  // --- Contact lists ---
+  async listContactLists(query = {}) {
+    return (await this.request("/contact-lists", { query })).json;
+  }
+  async listListMembers(listId, query = {}) {
+    return (await this.request(`/contact-lists/${encodeURIComponent(listId)}/members`, { query })).json;
+  }
+  async addListMember(listId, body) {
+    return (await this.request(`/contact-lists/${encodeURIComponent(listId)}/members`, { method: "POST", body })).json;
+  }
+  async removeListMember(listId, memberId) {
+    return (await this.request(
+      `/contact-lists/${encodeURIComponent(listId)}/members/${encodeURIComponent(memberId)}`,
+      { method: "DELETE" }
+    )).json;
+  }
+  // --- Signals ---
+  async listSignalAgents(query = {}) {
+    return (await this.request("/signals/agents", { query })).json;
+  }
+  async listSignalLeads(query = {}) {
+    return (await this.request("/signals/leads", { query })).json;
+  }
+  async createSignalAgent(body, idempotencyKey) {
+    const headers = {};
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    const res = await this.request("/signals/agents", { method: "POST", body, headers });
+    return { json: res.json, replayed: res.headers.get("idempotency-replayed") === "true" };
+  }
+  async setSignalAgentStatus(id, status2) {
+    return (await this.request(`/signals/agents/${id}`, { method: "PATCH", body: { status: status2 } })).json;
+  }
+  async deleteSignalAgent(id) {
+    return (await this.request(`/signals/agents/${id}`, { method: "DELETE" })).json;
+  }
+  // --- Scheduled posts ---
+  async listScheduled(query = {}) {
+    return (await this.request("/scheduled-posts", { query })).json;
+  }
+  async createScheduled(body, idempotencyKey) {
+    const headers = {};
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    const res = await this.request("/scheduled-posts", { method: "POST", body, headers });
+    return { json: res.json, replayed: res.headers.get("idempotency-replayed") === "true" };
+  }
+  async updateScheduled(id, body) {
+    return (await this.request(`/scheduled-posts/${encodeURIComponent(id)}`, { method: "PATCH", body })).json;
+  }
+  async deleteScheduled(id) {
+    return (await this.request(`/scheduled-posts/${encodeURIComponent(id)}`, { method: "DELETE" })).json;
+  }
+  // --- Media ---
+  async createMediaUpload(body) {
+    return (await this.request("/media", { method: "POST", body })).json;
+  }
+  // --- Tags ---
+  async listTags() {
+    return (await this.request("/tags")).json;
+  }
+  async createTag(body) {
+    return (await this.request("/tags", { method: "POST", body })).json;
+  }
+  async updateTag(id, body) {
+    return (await this.request(`/tags/${encodeURIComponent(id)}`, { method: "PATCH", body })).json;
+  }
+  async deleteTag(id) {
+    return (await this.request(`/tags/${encodeURIComponent(id)}`, { method: "DELETE" })).json;
+  }
+  // --- Articles ---
+  async listArticles(query = {}) {
+    return (await this.request("/articles", { query })).json;
+  }
+  async getArticle(id) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}`)).json;
+  }
+  async createArticle(body) {
+    return (await this.request("/articles", { method: "POST", body })).json;
+  }
+  async updateArticle(id, body) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}`, { method: "PATCH", body })).json;
+  }
+  async deleteArticle(id) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}`, { method: "DELETE" })).json;
+  }
+  async publishArticle(id) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}/publish`, { method: "POST", body: {} })).json;
+  }
+  async scheduleArticle(id, body) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}/schedule`, { method: "POST", body })).json;
+  }
+  async unscheduleArticle(id) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}/unschedule`, { method: "POST", body: {} })).json;
+  }
+  async generateArticleCover(id, body) {
+    return (await this.request(`/articles/${encodeURIComponent(id)}/cover`, { method: "POST", body })).json;
+  }
+  // --- Docs (unauthenticated markdown) ---
+  async docs() {
+    const url = this.buildUrl("/docs");
+    let response;
+    try {
+      response = await fetch(url);
+    } catch (err) {
+      throw new ApiError(0, "network_error", `Could not reach ${this.apiUrl} (${err?.message || err})`);
+    }
+    if (!response.ok) {
+      throw new ApiError(response.status, `http_${response.status}`, `Docs request failed with HTTP ${response.status}`);
+    }
+    return response.text();
+  }
+};
+function printJson(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+function note(message) {
+  process.stderr.write(message + "\n");
+}
+
+// src/commands/auth.ts
+var readline = __toESM(require("readline"));
+
+// src/config.ts
+var fs = __toESM(require("fs"));
+var os = __toESM(require("os"));
+var path = __toESM(require("path"));
+var DEFAULT_API_URL = "https://api.superx.so/v1";
+var CONFIG_DIR = path.join(os.homedir(), ".superx");
+var CREDENTIALS_PATH = path.join(CONFIG_DIR, "credentials.json");
+function loadCredentials() {
+  try {
+    const raw = fs.readFileSync(CREDENTIALS_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.apiKey === "string" && parsed.apiKey) {
+      return {
+        apiKey: parsed.apiKey,
+        apiUrl: typeof parsed.apiUrl === "string" && parsed.apiUrl ? parsed.apiUrl : DEFAULT_API_URL
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function saveCredentials(creds) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2) + "\n", { mode: 384 });
+  fs.chmodSync(CONFIG_DIR, 448);
+  fs.chmodSync(CREDENTIALS_PATH, 384);
+}
+function deleteCredentials() {
+  try {
+    fs.unlinkSync(CREDENTIALS_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveApiUrl(storedUrl) {
+  const envUrl = process.env.SUPERX_API_URL;
+  if (envUrl) return envUrl.replace(/\/+$/, "");
+  if (storedUrl) return storedUrl.replace(/\/+$/, "");
+  return DEFAULT_API_URL;
+}
+function getConfig() {
+  const creds = loadCredentials();
+  if (creds) {
+    return { apiKey: creds.apiKey, apiUrl: resolveApiUrl(creds.apiUrl), source: "credentials_file" };
+  }
+  const envKey = process.env.SUPERX_API_KEY;
+  if (envKey) {
+    return { apiKey: envKey, apiUrl: resolveApiUrl(), source: "env" };
+  }
+  process.stderr.write("Not authenticated. Either:\n");
+  process.stderr.write("  1. Run: superx login\n");
+  process.stderr.write("  2. Or set: export SUPERX_API_KEY=sxk_...\n");
+  process.stderr.write("Create an API key at https://app.superx.so/account?tab=developers\n");
+  process.exit(1);
+}
+
+// src/commands/auth.ts
+function promptForKey() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr
+      // keep the prompt off stdout
+    });
+    rl.question("Paste your API key (sxk_...): ", (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+async function login(argv) {
+  const apiUrl = resolveApiUrl(loadCredentials()?.apiUrl);
+  let key = (argv.key || "").trim();
+  if (!key) {
+    note("Create or copy an API key at:");
+    note("  https://app.superx.so/account?tab=developers");
+    note("");
+    key = await promptForKey();
+  }
+  if (!key) {
+    note("No API key provided.");
+    process.exit(1);
+  }
+  if (!key.startsWith("sxk_")) {
+    note("That does not look like a SuperX API key (expected an sxk_ prefix).");
+    process.exit(1);
+  }
+  const api = new SuperXAPI({ apiKey: key, apiUrl });
+  const me2 = await api.me();
+  saveCredentials({ apiKey: key, apiUrl });
+  note(`Logged in as ${me2?.data?.owner?.name || me2?.data?.owner?.id || "unknown"}.`);
+  note(`Credentials saved to ${CREDENTIALS_PATH}`);
+  printJson(me2);
+}
+async function logout() {
+  const removed = deleteCredentials();
+  note(removed ? `Removed ${CREDENTIALS_PATH}` : "No credentials file found; nothing to remove.");
+  printJson({ logged_out: true, credentials_removed: removed });
+}
+async function status() {
+  const config = getConfig();
+  const api = new SuperXAPI(config);
+  const me2 = await api.me();
+  printJson({
+    authenticated: true,
+    auth_source: config.source,
+    api_url: config.apiUrl,
+    owner: me2?.data?.owner ?? null,
+    plan: me2?.data?.plan ?? null,
+    key: me2?.data?.key ?? null,
+    rate_limit: api.lastRateLimit
+  });
+}
+
+// src/commands/accounts.ts
+async function me() {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.me());
+}
+async function accounts(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.accounts({ limit: argv.limit, page: argv.page }));
+}
+
+// src/commands/posts.ts
+async function postsList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listPosts({
+      account_id: argv.account,
+      type: argv.type,
+      sort: argv.sort,
+      since: argv.since,
+      until: argv.until,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function postsAnalytics(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.postsAnalytics({
+      account_id: argv.account,
+      since: argv.since,
+      until: argv.until
+    })
+  );
+}
+async function repliesList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listReplies({
+      account_id: argv.account,
+      since: argv.since,
+      until: argv.until,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function repliesReceived(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.receivedReplies({
+      account_id: argv.account,
+      sort: argv.sort,
+      since: argv.since,
+      until: argv.until,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+
+// src/commands/inspiration.ts
+async function inspirationSearch(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.searchInspiration({
+      q: argv.query,
+      sort: argv.sort,
+      min_likes: argv.minLikes,
+      min_reposts: argv.minReposts,
+      min_replies: argv.minReplies,
+      min_bookmarks: argv.minBookmarks,
+      min_impressions: argv.minImpressions,
+      min_followers: argv.minFollowers,
+      max_followers: argv.maxFollowers,
+      since: argv.since,
+      until: argv.until,
+      lang: argv.lang,
+      exclude_topics: argv.excludeTopics,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+
+// src/commands/contacts.ts
+async function contactsList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listContacts({
+      account_id: argv.account,
+      sort: argv.sort,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function contactsReplies(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.contactReplies(argv.id, {
+      account_id: argv.account,
+      sort: argv.sort,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+
+// src/commands/lists.ts
+async function listsList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.listContactLists({ account_id: argv.account }));
+}
+async function listsMembers(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listListMembers(argv.id, {
+      account_id: argv.account,
+      q: argv.q,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function listsAddMember(argv) {
+  if (argv.handle && argv.xUserId || !argv.handle && !argv.xUserId) {
+    throw new Error("Provide exactly one of --handle or --x-user-id.");
+  }
+  const api = new SuperXAPI(getConfig());
+  const body = argv.handle ? { handle: argv.handle } : { x_user_id: argv.xUserId };
+  printJson(await api.addListMember(argv.id, body));
+}
+async function listsRemoveMember(argv) {
+  const api = new SuperXAPI(getConfig());
+  await api.removeListMember(argv.id, argv.memberId);
+  printJson({ data: { id: argv.memberId, removed: true } });
+}
+
+// src/commands/signals.ts
+async function signalsAgents(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.listSignalAgents({ account_id: argv.account }));
+}
+async function signalsLeads(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listSignalLeads({
+      account_id: argv.account,
+      agent_id: argv.agent,
+      // yargs boolean: pass through only when the flag was given.
+      deposited: argv.deposited === void 0 ? void 0 : String(argv.deposited),
+      since: argv.since,
+      until: argv.until,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function signalsCreateAgent(argv) {
+  const body = {
+    name: argv.name,
+    icp_description: argv.icp
+  };
+  if (argv.precision) body.precision_mode = argv.precision;
+  if (argv["list-id"]) body.destination_list_id = argv["list-id"];
+  const keywords = (argv.keyword || []).filter((k) => typeof k === "string" && k.length > 0);
+  if (keywords.length > 0) body.keywords = keywords;
+  const api = new SuperXAPI(getConfig());
+  const { json, replayed } = await api.createSignalAgent(body, argv["idempotency-key"]);
+  if (replayed) {
+    note("Idempotency replay: this Idempotency-Key was already processed; returning the original response.");
+    printJson({ ...json, replayed: true });
+    return;
+  }
+  printJson(json);
+}
+async function signalsPauseAgent(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.setSignalAgentStatus(argv.id, "paused"));
+}
+async function signalsResumeAgent(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.setSignalAgentStatus(argv.id, "active"));
+}
+async function signalsDeleteAgent(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.deleteSignalAgent(argv.id));
+}
+
+// src/commands/scheduled.ts
+async function scheduledList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listScheduled({
+      account_id: argv.account,
+      status: argv.status,
+      tags: argv.tags,
+      from: argv.from,
+      to: argv.to,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+function mediaFromFlags(mediaFlag, altText) {
+  if (!mediaFlag) {
+    if (altText !== void 0) {
+      note("--alt-text requires --media.");
+      process.exit(1);
+    }
+    return null;
+  }
+  const keys = mediaFlag.split(",").map((k) => k.trim()).filter(Boolean);
+  if (keys.length === 0) {
+    note("--media must be a comma list of object_keys (from media:upload).");
+    process.exit(1);
+  }
+  if (altText !== void 0 && keys.length > 1) {
+    note("--alt-text works with a single --media key. For per-image alt text use --parts-json.");
+    process.exit(1);
+  }
+  return keys.map((object_key, i) => ({
+    object_key,
+    ...altText !== void 0 && i === 0 ? { alt_text: altText } : {}
+  }));
+}
+function parsePartsJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    note('--parts-json must be valid JSON, e.g. [{"text":"Hook","media":[{"object_key":"..."}]}]');
+    process.exit(1);
+    throw new Error("unreachable");
+  }
+  if (!Array.isArray(parsed) || parsed.some((p) => !p || typeof p !== "object" || typeof p.text !== "string")) {
+    note("--parts-json must be an array of { text, media? } objects.");
+    process.exit(1);
+  }
+  return parsed;
+}
+async function scheduledCreate(argv) {
+  const parts = (argv.part || []).filter((p) => typeof p === "string");
+  const sourceCount = [argv.text, parts.length > 0 ? "p" : void 0, argv["parts-json"]].filter(
+    (v) => v !== void 0
+  ).length;
+  if (sourceCount > 1) {
+    note("Use exactly one of --text (single post), --part (thread), or --parts-json.");
+    process.exit(1);
+  }
+  if (sourceCount === 0) {
+    note("Provide --text for a single post, --part flags for a thread, or --parts-json.");
+    process.exit(1);
+  }
+  if (argv.media !== void 0 && !argv.text) {
+    note("--media applies to the --text single-post form. For threads, put media in --parts-json.");
+    process.exit(1);
+  }
+  const body = {};
+  if (argv["parts-json"] !== void 0) {
+    body.parts = parsePartsJson(argv["parts-json"]);
+  } else if (argv.text) {
+    const media = mediaFromFlags(argv.media, argv["alt-text"]);
+    if (media) {
+      body.parts = [{ text: argv.text, media }];
+    } else {
+      body.text = argv.text;
+    }
+  } else {
+    body.parts = parts.map((text) => ({ text }));
+  }
+  if (argv.at) body.scheduled_for = argv.at;
+  if (argv.title !== void 0) body.title = argv.title;
+  if (argv.scratchpad !== void 0) body.scratchpad = argv.scratchpad;
+  const tags = (argv.tag || []).filter((t) => typeof t === "string" && t.length > 0);
+  if (tags.length > 0) body.tags = tags;
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  const { json, replayed } = await api.createScheduled(body, argv["idempotency-key"]);
+  if (replayed) {
+    note("Idempotency replay: this Idempotency-Key was already processed; returning the original response.");
+    printJson({ ...json, replayed: true });
+    return;
+  }
+  printJson(json);
+}
+async function scheduledUpdate(argv) {
+  const parts = (argv.part || []).filter((p) => typeof p === "string");
+  const sourceCount = [argv.text, parts.length > 0 ? "p" : void 0, argv["parts-json"]].filter(
+    (v) => v !== void 0
+  ).length;
+  if (sourceCount > 1) {
+    note("Use exactly one of --text (single post), --part (thread), or --parts-json.");
+    process.exit(1);
+  }
+  if (argv.media !== void 0 && !argv.text) {
+    note("--media applies to the --text single-post form. For threads, put media in --parts-json.");
+    process.exit(1);
+  }
+  if (argv.title !== void 0 && argv["clear-title"]) {
+    note("Use either --title or --clear-title, not both.");
+    process.exit(1);
+  }
+  if (argv.scratchpad !== void 0 && argv["clear-scratchpad"]) {
+    note("Use either --scratchpad or --clear-scratchpad, not both.");
+    process.exit(1);
+  }
+  const tags = (argv.tag || []).filter((t) => typeof t === "string" && t.length > 0);
+  if (tags.length > 0 && argv["clear-tags"]) {
+    note("Use either --tag or --clear-tags, not both.");
+    process.exit(1);
+  }
+  const body = {};
+  if (argv["parts-json"] !== void 0) {
+    body.parts = parsePartsJson(argv["parts-json"]);
+  } else if (argv.text) {
+    const media = mediaFromFlags(argv.media, argv["alt-text"]);
+    if (media) {
+      body.parts = [{ text: argv.text, media }];
+    } else {
+      body.text = argv.text;
+    }
+  } else if (parts.length > 0) {
+    body.parts = parts.map((text) => ({ text }));
+  }
+  if (argv.at) body.scheduled_for = argv.at;
+  if (argv.status) body.status = argv.status;
+  if (argv.title !== void 0) body.title = argv.title;
+  if (argv["clear-title"]) body.title = null;
+  if (argv.scratchpad !== void 0) body.scratchpad = argv.scratchpad;
+  if (argv["clear-scratchpad"]) body.scratchpad = null;
+  if (tags.length > 0) body.tags = tags;
+  if (argv["clear-tags"]) body.tags = [];
+  if (argv.account) body.account_id = argv.account;
+  if (Object.keys(body).filter((k) => k !== "account_id").length === 0) {
+    note("Provide at least one field to update. Run: superx scheduled:update --help");
+    process.exit(1);
+  }
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.updateScheduled(argv.id, body));
+}
+async function scheduledDelete(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.deleteScheduled(argv.id));
+}
+
+// src/commands/media.ts
+var import_fs = require("fs");
+var import_path = __toESM(require("path"));
+function sniffImageType(bytes) {
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) {
+    return "image/jpeg";
+  }
+  if (bytes.length >= 4 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
+    return "image/png";
+  }
+  if (bytes.length >= 4 && bytes.toString("latin1", 0, 4) === "GIF8") {
+    return "image/gif";
+  }
+  if (bytes.length >= 12 && bytes.toString("latin1", 0, 4) === "RIFF" && bytes.toString("latin1", 8, 12) === "WEBP") {
+    return "image/webp";
+  }
+  return null;
+}
+var EXT_TYPES = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif"
+};
+async function mediaUpload(argv) {
+  let buffer;
+  try {
+    buffer = (0, import_fs.readFileSync)(argv.file);
+  } catch (err) {
+    note(`Error: could not read ${argv.file} (${err?.message || err})`);
+    process.exit(1);
+    return;
+  }
+  const fileType = sniffImageType(buffer) || EXT_TYPES[import_path.default.extname(argv.file).toLowerCase()];
+  if (!fileType) {
+    note("Error: unsupported file type. Supported images: JPG, PNG, WEBP, GIF.");
+    process.exit(1);
+    return;
+  }
+  const filename = import_path.default.basename(argv.file);
+  const api = new SuperXAPI(getConfig());
+  const created = await api.createMediaUpload({
+    filename,
+    file_type: fileType,
+    size: buffer.length
+  });
+  const data = created?.data || {};
+  if (!data.upload_url || !data.object_key) {
+    note("Error: the API did not return an upload URL.");
+    process.exit(1);
+    return;
+  }
+  note(`Uploading ${filename} (${fileType}, ${buffer.length} bytes)...`);
+  let putResponse;
+  try {
+    putResponse = await fetch(data.upload_url, {
+      method: "PUT",
+      // The presigned URL signs the Content-Type; it must match file_type.
+      headers: { "Content-Type": fileType },
+      body: buffer
+    });
+  } catch (err) {
+    throw new ApiError(0, "network_error", `Upload failed (${err?.message || err})`);
+  }
+  if (!putResponse.ok) {
+    throw new ApiError(putResponse.status, "upload_failed", `The storage upload returned HTTP ${putResponse.status}.`);
+  }
+  printJson({
+    object_key: data.object_key,
+    url: data.url,
+    file_type: fileType,
+    size: buffer.length
+  });
+}
+
+// src/commands/tags.ts
+async function tagsList() {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.listTags());
+}
+async function tagsCreate(argv) {
+  const body = { name: argv.name };
+  if (argv.color) body.color = argv.color;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.createTag(body));
+}
+async function tagsUpdate(argv) {
+  if (argv.name === void 0 && argv.color === void 0) {
+    note("Provide --name and/or --color.");
+    process.exit(1);
+  }
+  const body = {};
+  if (argv.name !== void 0) body.name = argv.name;
+  if (argv.color !== void 0) body.color = argv.color;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.updateTag(argv.id, body));
+}
+async function tagsDelete(argv) {
+  const api = new SuperXAPI(getConfig());
+  await api.deleteTag(argv.id);
+  printJson({ id: argv.id, deleted: true });
+}
+
+// src/commands/articles.ts
+var import_fs2 = require("fs");
+function resolveContent(argv) {
+  if (argv.content !== void 0 && argv.file !== void 0) {
+    note("Use either --content or --file, not both.");
+    process.exit(1);
+  }
+  if (argv.content !== void 0) return argv.content;
+  if (argv.file !== void 0) {
+    try {
+      return (0, import_fs2.readFileSync)(argv.file, "utf8");
+    } catch (err) {
+      note(`Could not read ${argv.file}: ${err?.message || err}`);
+      process.exit(1);
+    }
+  }
+  if (!process.stdin.isTTY) {
+    try {
+      const piped = (0, import_fs2.readFileSync)(0, "utf8");
+      if (piped.length > 0) return piped;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function articlesList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listArticles({
+      account_id: argv.account,
+      status: argv.status,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function articlesGet(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.getArticle(argv.id));
+}
+async function articlesCreate(argv) {
+  const content = resolveContent(argv);
+  const body = { title: argv.title };
+  if (content !== void 0) body.content_markdown = content;
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.createArticle(body));
+}
+async function articlesUpdate(argv) {
+  if (argv["cover-url"] !== void 0 && argv["clear-cover"]) {
+    note("Use either --cover-url or --clear-cover, not both.");
+    process.exit(1);
+  }
+  const body = {};
+  if (argv.title !== void 0) body.title = argv.title;
+  if (argv.content !== void 0 && argv.file !== void 0) {
+    note("Use either --content or --file, not both.");
+    process.exit(1);
+  }
+  if (argv.content !== void 0) body.content_markdown = argv.content;
+  if (argv.file !== void 0) {
+    try {
+      body.content_markdown = (0, import_fs2.readFileSync)(argv.file, "utf8");
+    } catch (err) {
+      note(`Could not read ${argv.file}: ${err?.message || err}`);
+      process.exit(1);
+    }
+  }
+  if (argv["cover-url"] !== void 0) body.cover_url = argv["cover-url"];
+  if (argv["clear-cover"]) body.cover_url = null;
+  if (Object.keys(body).length === 0) {
+    note("Provide at least one of: --title, --content, --file, --cover-url, --clear-cover.");
+    process.exit(1);
+  }
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.updateArticle(argv.id, body));
+}
+async function articlesDelete(argv) {
+  const api = new SuperXAPI(getConfig());
+  await api.deleteArticle(argv.id);
+  printJson({ id: argv.id, deleted: true });
+}
+async function articlesPublish(argv) {
+  note("Publishing to X. This is live and irreversible; it can take up to 90 seconds...");
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.publishArticle(argv.id));
+}
+async function articlesSchedule(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.scheduleArticle(argv.id, { scheduled_for: argv.at }));
+}
+async function articlesUnschedule(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.unscheduleArticle(argv.id));
+}
+async function articlesCover(argv) {
+  note("Generating a cover image. This spends AI credits and can take 60-100 seconds...");
+  const body = {};
+  if (argv.style !== void 0) body.style_text = argv.style;
+  if (argv.attach === false) body.attach = false;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.generateArticleCover(argv.id, body));
+}
+
+// src/commands/docs.ts
+async function docs() {
+  const apiUrl = resolveApiUrl(loadCredentials()?.apiUrl || DEFAULT_API_URL);
+  const api = new SuperXAPI({ apiKey: "", apiUrl });
+  process.stdout.write(await api.docs());
+}
+
+// src/index.ts
+function run(handler) {
+  return async (argv) => {
+    try {
+      await handler(argv);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        const status2 = err.status ? ` (HTTP ${err.status})` : "";
+        note(`Error [${err.code}]${status2}: ${err.message}`);
+        if (err.retryAfter !== null) {
+          note(`Retry after ${err.retryAfter} seconds.`);
+        }
+      } else {
+        note(`Error: ${err?.message || err}`);
+      }
+      process.exit(1);
+    }
+  };
+}
+var paginationOptions = (y) => y.option("limit", { describe: "Items per page (max 100)", type: "number" }).option("page", { describe: "Page number (1-based)", type: "number" });
+var accountOption = (y) => y.option("account", {
+  describe: "Account id (from `superx accounts`); defaults to your main account",
+  type: "string"
+});
+(0, import_yargs.default)((0, import_helpers.hideBin)(process.argv)).scriptName("superx").usage("$0 <command> [options]").command(
+  "login",
+  "Authenticate with a SuperX API key (guided paste or --key)",
+  (y) => y.option("key", {
+    describe: "API key (sxk_...); omit to be prompted",
+    type: "string"
+  }).example('$0 login --key "sxk_..."', "Non-interactive login").example("$0 login", "Guided login: prints the key page URL and prompts for a paste"),
+  run(login)
+).command("logout", "Remove stored credentials (~/.superx/credentials.json)", {}, run(logout)).command("status", "Check authentication, plan, and current rate-limit state", {}, run(status)).command("me", "Show the key owner, plan, and API key details", {}, run(me)).command(
+  "accounts",
+  "List the X accounts this key can read (main account first)",
+  (y) => paginationOptions(y),
+  run(accounts)
+).command(
+  "posts:list",
+  "List published posts with engagement metrics",
+  (y) => paginationOptions(accountOption(y)).option("type", {
+    describe: "Filter by post kind",
+    type: "string",
+    choices: ["posts", "replies", "all"]
+  }).option("sort", {
+    describe: "Sort order",
+    type: "string",
+    choices: ["posted_at", "likes", "impressions"]
+  }).option("since", { describe: "Start of range (UTC ISO-8601, e.g. 2026-06-01T00:00:00Z)", type: "string" }).option("until", { describe: "End of range (UTC ISO-8601)", type: "string" }).example("$0 posts:list --sort likes --limit 10", "Top 10 posts by likes").example('$0 posts:list --since "2026-06-01T00:00:00Z" --type posts', "Original posts since June"),
+  run(postsList)
+).command(
+  "posts:analytics",
+  "Account analytics: totals, daily series, follower change (default: last 30 days)",
+  (y) => accountOption(y).option("since", { describe: "Start of range (UTC ISO-8601)", type: "string" }).option("until", { describe: "End of range (UTC ISO-8601)", type: "string" }).example('$0 posts:analytics --since "2026-06-01T00:00:00Z" --until "2026-07-01T00:00:00Z"', "June analytics"),
+  run(postsAnalytics)
+).command(
+  "replies:list",
+  "List replies the account has sent (newest first)",
+  (y) => paginationOptions(accountOption(y)).option("since", { describe: "Start of range (UTC ISO-8601)", type: "string" }).option("until", { describe: "End of range (UTC ISO-8601)", type: "string" }),
+  run(repliesList)
+).command(
+  "replies:received",
+  "List replies your audience has sent you across all your posts",
+  (y) => paginationOptions(accountOption(y)).option("sort", {
+    describe: "Sort order",
+    type: "string",
+    choices: ["recent", "most_liked"]
+  }).option("since", { describe: "Start of range (UTC ISO-8601)", type: "string" }).option("until", { describe: "End of range (UTC ISO-8601)", type: "string" }).example("$0 replies:received --limit 10", "Ten newest audience replies").example('$0 replies:received --sort most_liked --since "2026-06-01T00:00:00Z"', "Best-liked replies since June"),
+  run(repliesReceived)
+).command(
+  "inspiration:search <query>",
+  "Search a library of 50M+ high-performing posts for inspiration",
+  (y) => paginationOptions(y).positional("query", { describe: "Topic or theme to search for", type: "string" }).option("sort", {
+    describe: "Sort order",
+    type: "string",
+    choices: ["relevant", "recent", "likes", "reposts", "impressions", "outlier"]
+  }).option("min-likes", { describe: "Only posts with at least this many likes", type: "number" }).option("min-reposts", { describe: "Only posts with at least this many reposts", type: "number" }).option("min-replies", { describe: "Only posts with at least this many replies", type: "number" }).option("min-bookmarks", { describe: "Only posts with at least this many bookmarks", type: "number" }).option("min-impressions", { describe: "Only posts with at least this many impressions", type: "number" }).option("min-followers", { describe: "Only posts from authors with at least this many followers", type: "number" }).option("max-followers", { describe: "Only posts from authors with at most this many followers", type: "number" }).option("since", { describe: "Only posts after this time (UTC ISO-8601)", type: "string" }).option("until", { describe: "Only posts before this time (UTC ISO-8601)", type: "string" }).option("lang", { describe: "Language code (default en)", type: "string" }).option("exclude-topics", { describe: "Comma-separated topics to exclude", type: "string" }).example('$0 inspiration:search "build in public" --limit 10', "Ten posts about building in public").example('$0 inspiration:search "indie hackers" --sort outlier --min-likes 500', "Overperformers with 500+ likes"),
+  run(inspirationSearch)
+).command(
+  "contacts:list",
+  "List the people who engage with you most",
+  (y) => paginationOptions(accountOption(y)).option("sort", {
+    describe: "Sort order",
+    type: "string",
+    choices: ["engagement", "replies", "reposts"]
+  }),
+  run(contactsList)
+).command(
+  "contacts:replies <id>",
+  "List a contact's replies to you (their id from contacts:list)",
+  (y) => paginationOptions(accountOption(y)).positional("id", { describe: "Contact id", type: "string" }).option("sort", {
+    describe: "Sort order",
+    type: "string",
+    choices: ["recent", "most_liked"]
+  }),
+  run(contactsReplies)
+).command(
+  "lists:list",
+  "List your contact lists (system lists are read-only)",
+  (y) => accountOption(y),
+  run(listsList)
+).command(
+  "lists:members <id>",
+  "List the members of a contact list you created",
+  (y) => paginationOptions(accountOption(y)).positional("id", { describe: "List id (from lists:list)", type: "string" }).option("q", { describe: "Filter members by handle or name substring", type: "string" }),
+  run(listsMembers)
+).command(
+  "lists:add-member <id>",
+  "Add a person to a contact list by handle or X user id",
+  (y) => y.positional("id", { describe: "List id (from lists:list)", type: "string" }).option("handle", { describe: "X username, with or without the @", type: "string" }).option("x-user-id", { describe: "Numeric X user id", type: "string" }).example("$0 lists:add-member abc123 --handle levelsio", "Add by handle").example("$0 lists:add-member abc123 --x-user-id 44196397", "Add by X user id"),
+  run(listsAddMember)
+).command(
+  "lists:remove-member <id> <memberId>",
+  "Remove a member from a contact list (member id from lists:members)",
+  (y) => y.positional("id", { describe: "List id (from lists:list)", type: "string" }).positional("memberId", { describe: "Member id (from lists:members)", type: "string" }),
+  run(listsRemoveMember)
+).command(
+  "signals:agents",
+  "List your signal agents (automated lead finders) with their watched signals",
+  (y) => accountOption(y),
+  run(signalsAgents)
+).command(
+  "signals:leads",
+  "List the leads your signal agents have found (newest first)",
+  (y) => paginationOptions(accountOption(y)).option("agent", { describe: "Narrow to one agent by its numeric id (from signals:agents)", type: "number" }).option("deposited", {
+    describe: "true = only leads already saved to the agent's contact list, false = only new ones",
+    type: "boolean"
+  }).option("since", { describe: "Only leads discovered after this time (UTC ISO-8601)", type: "string" }).option("until", { describe: "Only leads discovered before this time (UTC ISO-8601)", type: "string" }).example("$0 signals:leads --limit 10", "Ten newest leads across all agents").example("$0 signals:leads --agent 3 --deposited false", "New leads from agent 3 not yet in its list"),
+  run(signalsLeads)
+).command(
+  "signals:create-agent",
+  "Create a signal agent (automated lead finder); leads land in Signals over the next minutes and days",
+  (y) => y.option("name", { describe: "Agent name (max 80 chars)", type: "string", demandOption: true }).option("icp", {
+    describe: "Who the ideal leads are: role, product, pains, buying intent (max 500 chars)",
+    type: "string",
+    demandOption: true
+  }).option("precision", {
+    describe: "high = fewer, stricter matches (default); discovery = broader net",
+    type: "string",
+    choices: ["high", "discovery"]
+  }).option("list-id", {
+    describe: "Contact list id (from lists:list) that receives the leads; omit to auto-create one",
+    type: "string"
+  }).option("keyword", {
+    describe: "Plain-language search description to watch (repeat the flag, 1-5); omit to auto-suggest from --icp",
+    type: "string",
+    array: true
+  }).option("idempotency-key", {
+    describe: "Idempotency-Key header (max 64 chars); retries with the same key return the original result",
+    type: "string"
+  }).example(
+    '$0 signals:create-agent --name "Build in public" --icp "Indie founders building SaaS in public" --keyword "building in public" --keyword "just shipped my MVP"',
+    "Create an agent with explicit keywords"
+  ).example(
+    '$0 signals:create-agent --name "Agency leads" --icp "Marketing agency owners struggling with reporting"',
+    "Create an agent with auto-suggested keywords and an auto-created list"
+  ),
+  run(signalsCreateAgent)
+).command(
+  "signals:pause-agent <id>",
+  "Pause a signal agent (it stops finding leads until resumed)",
+  (y) => y.positional("id", { describe: "Agent id (from signals:agents)", type: "number" }),
+  run(signalsPauseAgent)
+).command(
+  "signals:resume-agent <id>",
+  "Resume a paused signal agent",
+  (y) => y.positional("id", { describe: "Agent id (from signals:agents)", type: "number" }),
+  run(signalsResumeAgent)
+).command(
+  "signals:delete-agent <id>",
+  "Delete a signal agent (its saved leads and contact list stay untouched)",
+  (y) => y.positional("id", { describe: "Agent id (from signals:agents)", type: "number" }),
+  run(signalsDeleteAgent)
+).command(
+  "scheduled:list",
+  "List drafts and the scheduled queue",
+  (y) => paginationOptions(accountOption(y)).option("status", {
+    describe: "Comma list of: draft, scheduled, sent, error",
+    type: "string"
+  }).option("tags", {
+    describe: "Comma list of tag ids (from tags:list); posts matching ANY of them",
+    type: "string"
+  }).option("from", { describe: "Scheduled-time lower bound (UTC ISO-8601)", type: "string" }).option("to", { describe: "Scheduled-time upper bound (UTC ISO-8601)", type: "string" }),
+  run(scheduledList)
+).command(
+  "media:upload <file>",
+  "Upload a local image (JPG, PNG, WEBP, GIF) and print its object_key for --media",
+  (y) => y.positional("file", { describe: "Path to the image file (max 5MB; GIF 15MB)", type: "string" }).example("$0 media:upload ./chart.png", "Upload an image").example('KEY=$($0 media:upload ./chart.png | jq -r .object_key); $0 scheduled:create --text "Post" --media "$KEY"', "Upload, then attach"),
+  run(mediaUpload)
+).command(
+  "scheduled:create",
+  "Create a draft (no --at) or scheduled post; repeat --part for a thread",
+  (y) => accountOption(y).option("text", { describe: "Text for a single post", type: "string" }).option("part", {
+    describe: "Thread part text (repeat the flag, 1-25 parts, in order)",
+    type: "string",
+    array: true
+  }).option("media", {
+    describe: "Comma list of image object_keys (from media:upload) to attach; single-post form only (max 4 images or 1 GIF)",
+    type: "string"
+  }).option("alt-text", {
+    describe: "Accessibility description for the attached image (single --media key only, max 1000 chars)",
+    type: "string"
+  }).option("parts-json", {
+    describe: 'Full parts array as JSON for threads with media: [{"text":"...","media":[{"object_key":"...","alt_text":"..."}]}]',
+    type: "string"
+  }).option("at", {
+    describe: "Schedule time: UTC ISO-8601 with explicit Z or offset, at least 60s in the future. Omit to create a draft.",
+    type: "string"
+  }).option("title", { describe: "Draft title (max 300 chars, shown in the SuperX app, never posted)", type: "string" }).option("scratchpad", { describe: "Private working notes (max 30000 chars, never posted)", type: "string" }).option("tag", {
+    describe: "Tag id to assign (repeat the flag, max 20; ids from tags:list)",
+    type: "string",
+    array: true
+  }).option("idempotency-key", {
+    describe: "Idempotency-Key header (max 64 chars); retries with the same key return the original result",
+    type: "string"
+  }).example('$0 scheduled:create --text "Hello"', "Create a draft").example('$0 scheduled:create --text "Hello" --at "2026-08-01T15:00:00Z"', "Schedule a post").example('$0 scheduled:create --part "1/ Hook" --part "2/ Detail" --part "3/ CTA"', "Draft a 3-part thread").example('$0 scheduled:create --text "Hello" --title "Launch teaser" --tag abc123', "Draft with a title and a tag").example('$0 scheduled:create --text "Chart of the week" --media "<object_key>" --alt-text "Revenue chart"', "Draft with an image"),
+  run(scheduledCreate)
+).command(
+  "scheduled:update <id>",
+  "Edit a draft or scheduled post; only the flags you pass change",
+  (y) => accountOption(y).positional("id", { describe: "Post id (from scheduled:list or scheduled:create)", type: "string" }).option("text", { describe: "Replacement text for a single post", type: "string" }).option("part", {
+    describe: "Replacement thread part text (repeat the flag, 1-25 parts, in order)",
+    type: "string",
+    array: true
+  }).option("media", {
+    describe: "Comma list of image object_keys to attach with --text (full replace: re-list existing keys to keep them; --text without --media removes the post's media)",
+    type: "string"
+  }).option("alt-text", {
+    describe: "Accessibility description for the attached image (single --media key only, max 1000 chars)",
+    type: "string"
+  }).option("parts-json", {
+    describe: 'Full replacement parts array as JSON: [{"text":"...","media":[{"object_key":"..."}]}]',
+    type: "string"
+  }).option("at", {
+    describe: "New schedule time (UTC ISO-8601 with explicit Z or offset). On its own it never schedules a draft; add --status scheduled.",
+    type: "string"
+  }).option("status", {
+    describe: "Explicit transition; scheduled needs a future time (via --at or already set)",
+    type: "string",
+    choices: ["draft", "scheduled"]
+  }).option("title", { describe: "New draft title (max 300 chars)", type: "string" }).option("clear-title", { describe: "Remove the title", type: "boolean" }).option("scratchpad", { describe: "New private notes (max 30000 chars)", type: "string" }).option("clear-scratchpad", { describe: "Remove the notes", type: "boolean" }).option("tag", {
+    describe: "Replacement tag id set (repeat the flag, max 20; replaces ALL current tags)",
+    type: "string",
+    array: true
+  }).option("clear-tags", { describe: "Remove all tags", type: "boolean" }).example('$0 scheduled:update abc123 --title "Better hook"', "Retitle a draft, everything else untouched").example('$0 scheduled:update abc123 --at "2026-08-01T15:00:00Z" --status scheduled', "Promote a draft to the queue").example("$0 scheduled:update abc123 --status draft", "Pull a post back to drafts (quota refunds)"),
+  run(scheduledUpdate)
+).command(
+  "scheduled:delete <id>",
+  "Delete a draft or scheduled post by id",
+  (y) => y.positional("id", { describe: "Post id (from scheduled:list or scheduled:create)", type: "string" }),
+  run(scheduledDelete)
+).command("tags:list", "List your tags (id, name, color)", {}, run(tagsList)).command(
+  "tags:create <name>",
+  "Create a tag",
+  (y) => y.positional("name", { describe: "Tag name (1-40 chars, unique)", type: "string" }).option("color", {
+    describe: "Palette color name (default blue): rose, amber, lime, emerald, teal, cyan, blue, indigo, violet, fuchsia, slate, stone",
+    type: "string"
+  }).example('$0 tags:create "Launch week" --color amber', "Create an amber tag"),
+  run(tagsCreate)
+).command(
+  "tags:update <id>",
+  "Rename and/or recolor a tag",
+  (y) => y.positional("id", { describe: "Tag id (from tags:list)", type: "string" }).option("name", { describe: "New name (1-40 chars, unique)", type: "string" }).option("color", { describe: "New palette color name", type: "string" }),
+  run(tagsUpdate)
+).command(
+  "tags:delete <id>",
+  "Delete a tag (it is removed from every post that carries it)",
+  (y) => y.positional("id", { describe: "Tag id (from tags:list)", type: "string" }),
+  run(tagsDelete)
+).command(
+  "articles:list",
+  "List X Articles (long-form posts)",
+  (y) => paginationOptions(accountOption(y)).option("status", {
+    describe: "Comma list of: draft, scheduled, publishing, published, failed",
+    type: "string"
+  }),
+  run(articlesList)
+).command(
+  "articles:get <id>",
+  "Get one article with its body as markdown",
+  (y) => y.positional("id", { describe: "Article id (from articles:list)", type: "string" }),
+  run(articlesGet)
+).command(
+  "articles:create",
+  "Create an article draft; body via --content, --file, or piped stdin (markdown)",
+  (y) => accountOption(y).option("title", { describe: "Article title (1-300 chars)", type: "string", demandOption: true }).option("content", { describe: "Body as inline markdown", type: "string" }).option("file", { describe: "Path to a markdown file with the body", type: "string" }).example('$0 articles:create --title "My article" --file draft.md', "Draft from a markdown file").example('cat draft.md | $0 articles:create --title "My article"', "Draft from piped stdin"),
+  run(articlesCreate)
+).command(
+  "articles:update <id>",
+  "Edit an article; only the flags you pass change",
+  (y) => y.positional("id", { describe: "Article id (from articles:list)", type: "string" }).option("title", { describe: "New title (1-300 chars)", type: "string" }).option("content", { describe: "Replacement body as inline markdown", type: "string" }).option("file", { describe: "Path to a markdown file with the replacement body", type: "string" }).option("cover-url", { describe: "http(s) image URL to set as the cover", type: "string" }).option("clear-cover", { describe: "Remove the cover image", type: "boolean" }),
+  run(articlesUpdate)
+).command(
+  "articles:delete <id>",
+  "Delete an article (scheduled articles refund their quota)",
+  (y) => y.positional("id", { describe: "Article id", type: "string" }),
+  run(articlesDelete)
+).command(
+  "articles:publish <id>",
+  "Publish an article to X NOW (irreversible, spends quota, needs X Premium)",
+  (y) => y.positional("id", { describe: "Article id", type: "string" }),
+  run(articlesPublish)
+).command(
+  "articles:schedule <id>",
+  "Schedule (or reschedule) an article",
+  (y) => y.positional("id", { describe: "Article id", type: "string" }).option("at", {
+    describe: "UTC ISO-8601 with explicit Z or offset, more than 2 minutes in the future",
+    type: "string",
+    demandOption: true
+  }).example('$0 articles:schedule abc123 --at "2026-08-01T15:00:00Z"', "Queue an article"),
+  run(articlesSchedule)
+).command(
+  "articles:unschedule <id>",
+  "Pull a scheduled article back to draft (quota refunds)",
+  (y) => y.positional("id", { describe: "Article id", type: "string" }),
+  run(articlesUnschedule)
+).command(
+  "articles:cover <id>",
+  "Generate an AI cover for an article (60-100s, spends AI credits)",
+  (y) => y.positional("id", { describe: "Article id (needs a title)", type: "string" }).option("style", { describe: "Style description steering the artwork (max 8000 chars)", type: "string" }).option("attach", {
+    describe: "Attach the result as the article's cover (use --no-attach to skip)",
+    type: "boolean",
+    default: true
+  }),
+  run(articlesCover)
+).command("docs", "Print the SuperX API quickstart (markdown, no auth needed)", {}, run(docs)).demandCommand(1, "Specify a command. Run: superx --help").strict().help().alias("h", "help").version().wrap(Math.min(100, process.stdout.columns || 100)).fail((msg, err) => {
+  if (err) throw err;
+  note(msg || "Invalid usage. Run: superx --help");
+  process.exit(1);
+}).parse();