@spectratools/xapi-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spectra-the-bot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @spectra-the-bot/xapi-cli
+
+X (Twitter) API v2 CLI for spectra-the-bot, built with [incur](https://github.com/wevm/incur).
+
+## Setup
+
+```bash
+export X_BEARER_TOKEN=your_bearer_token_here
+npx @spectra-the-bot/xapi-cli --help
+```
+
+## Commands
+
+### Posts
+
+```bash
+xapi posts get <id>
+xapi posts search <query> [-n 10] [--sort recency|relevancy]
+xapi posts create --text "Hello world!" [--reply-to <id>] [--quote <id>]
+xapi posts delete <id>
+xapi posts likes <id>
+xapi posts retweets <id>
+```
+
+### Users
+
+```bash
+xapi users get <username|id>
+xapi users followers <username> [-n 100]
+xapi users following <username>
+xapi users posts <username> [-n 10]
+xapi users mentions <username>
+xapi users search <query>
+```
+
+### Timeline
+
+```bash
+xapi timeline home [-n 25]
+xapi timeline mentions [-n 25]
+```
+
+### Lists
+
+```bash
+xapi lists get <id>
+xapi lists members <id>
+xapi lists posts <id> [-n 25]
+```
+
+### Trends
+
+```bash
+xapi trends places
+xapi trends location <woeid>
+```
+
+### DMs
+
+```bash
+xapi dm conversations [-n 20]
+xapi dm send <participant-id> --text "Hello!"
+```
+
+## Common Options
+
+- `--verbose` — Show full text without truncation
+- `-n, --max-results` — Control result count
+- `--format json` — JSON output
+- `--help` — Show help
+
+## Auth
+
+All read endpoints use `X_BEARER_TOKEN`. Write endpoints (create post, delete, DMs) require OAuth 2.0 user context. Requests are automatically retried on 429 rate limit responses.

package/dist/cli.js

@@ -0,0 +1,1202 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { fileURLToPath } from "url";
+import { Cli as Cli7 } from "incur";
+
+// src/commands/dm.ts
+import { apiKeyAuth } from "@spectratools/cli-shared";
+import { Cli, z } from "incur";
+
+// src/api.ts
+import { createHttpClient, withRetry } from "@spectratools/cli-shared";
+var BASE_URL = "https://api.x.com/2";
+var RETRY_OPTIONS = { maxRetries: 3, baseMs: 500, maxMs: 1e4 };
+function createXApiClient(bearerToken) {
+  const http = createHttpClient({
+    baseUrl: BASE_URL,
+    defaultHeaders: {
+      Authorization: `Bearer ${bearerToken}`
+    }
+  });
+  function get(path, query) {
+    return withRetry(
+      () => http.request(path, query !== void 0 ? { query } : {}),
+      RETRY_OPTIONS
+    );
+  }
+  function post(path, body) {
+    return withRetry(() => http.request(path, { method: "POST", body }), RETRY_OPTIONS);
+  }
+  function del(path) {
+    return withRetry(() => http.request(path, { method: "DELETE" }), RETRY_OPTIONS);
+  }
+  const POST_FIELDS = "id,text,author_id,created_at,public_metrics";
+  function getPost(id) {
+    return get(`/tweets/${id}`, {
+      "tweet.fields": POST_FIELDS
+    });
+  }
+  function searchPosts(query, maxResults, sort, nextToken) {
+    return get("/tweets/search/recent", {
+      query,
+      max_results: maxResults,
+      sort_order: sort,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { next_token: nextToken } : {}
+    });
+  }
+  function createPost(text, replyTo, quote) {
+    const body = { text };
+    if (replyTo) body.reply = { in_reply_to_tweet_id: replyTo };
+    if (quote) body.quote_tweet_id = quote;
+    return post("/tweets", body);
+  }
+  function deletePost(id) {
+    return del(`/tweets/${id}`);
+  }
+  function getPostLikes(id, maxResults, nextToken) {
+    return get(`/tweets/${id}/liking_users`, {
+      max_results: maxResults,
+      "user.fields": "id,name,username,public_metrics",
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getPostRetweets(id, maxResults, nextToken) {
+    return get(`/tweets/${id}/retweeted_by`, {
+      max_results: maxResults,
+      "user.fields": "id,name,username,public_metrics",
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  const USER_FIELDS = "id,name,username,description,public_metrics,created_at";
+  function getUserByUsername(username) {
+    return get(`/users/by/username/${username}`, {
+      "user.fields": USER_FIELDS
+    });
+  }
+  function getUserById(id) {
+    return get(`/users/${id}`, {
+      "user.fields": USER_FIELDS
+    });
+  }
+  function getUserFollowers(id, maxResults, nextToken) {
+    return get(`/users/${id}/followers`, {
+      max_results: maxResults,
+      "user.fields": USER_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getUserFollowing(id, maxResults, nextToken) {
+    return get(`/users/${id}/following`, {
+      max_results: maxResults,
+      "user.fields": USER_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getUserPosts(id, maxResults, nextToken) {
+    return get(`/users/${id}/tweets`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getUserMentions(id, maxResults, nextToken) {
+    return get(`/users/${id}/mentions`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function searchUsers(query) {
+    return get("/users/search", {
+      query,
+      "user.fields": USER_FIELDS
+    });
+  }
+  function getHomeTimeline(userId, maxResults, nextToken) {
+    return get(`/users/${userId}/timelines/reverse_chronological`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getMentionsTimeline(userId, maxResults, nextToken) {
+    return get(`/users/${userId}/mentions`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getList(id) {
+    return get(`/lists/${id}`, {
+      "list.fields": "id,name,description,owner_id,member_count"
+    });
+  }
+  function getListMembers(id, maxResults, nextToken) {
+    return get(`/lists/${id}/members`, {
+      max_results: maxResults,
+      "user.fields": USER_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getListPosts(id, maxResults, nextToken) {
+    return get(`/lists/${id}/tweets`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function getTrendingPlaces() {
+    return get(
+      "/trends/available"
+    );
+  }
+  function getTrendsByLocation(woeid) {
+    return get(
+      `/trends/place/${woeid}`
+    );
+  }
+  function getDmConversations(userId, maxResults, nextToken) {
+    return get(`/users/${userId}/dm_conversations`, {
+      max_results: maxResults,
+      ...nextToken ? { pagination_token: nextToken } : {}
+    });
+  }
+  function sendDm(participantId, text) {
+    return post(
+      `/dm_conversations/with/${participantId}/messages`,
+      { text }
+    );
+  }
+  function getMe() {
+    return get("/users/me", { "user.fields": USER_FIELDS });
+  }
+  return {
+    getPost,
+    searchPosts,
+    createPost,
+    deletePost,
+    getPostLikes,
+    getPostRetweets,
+    getUserByUsername,
+    getUserById,
+    getUserFollowers,
+    getUserFollowing,
+    getUserPosts,
+    getUserMentions,
+    searchUsers,
+    getHomeTimeline,
+    getMentionsTimeline,
+    getList,
+    getListMembers,
+    getListPosts,
+    getTrendingPlaces,
+    getTrendsByLocation,
+    getDmConversations,
+    sendDm,
+    getMe
+  };
+}
+function relativeTime(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  const s = Math.floor(ms / 1e3);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+function truncateText(text, max = 100) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 3)}...`;
+}
+
+// src/collect-paged.ts
+import { paginateCursor } from "@spectratools/cli-shared";
+async function collectPaged(fetchFn, mapFn, maxResults, pageSize = 100) {
+  const results = [];
+  for await (const item of paginateCursor({
+    fetchPage: async (cursor) => {
+      const res = await fetchFn(
+        Math.min(maxResults - results.length, pageSize),
+        cursor ?? void 0
+      );
+      return {
+        items: res.data ?? [],
+        nextCursor: res.meta?.next_token ?? null
+      };
+    }
+  })) {
+    results.push(mapFn(item));
+    if (results.length >= maxResults) break;
+  }
+  return results;
+}
+
+// src/commands/dm.ts
+var dm = Cli.create("dm", {
+  description: "Manage X direct messages."
+});
+dm.command("conversations", {
+  description: "List your DM conversations.",
+  options: z.object({
+    maxResults: z.number().default(20).describe("Maximum conversations to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z.object({
+    conversations: z.array(
+      z.object({
+        dm_conversation_id: z.string(),
+        participant_ids: z.array(z.string())
+      })
+    ),
+    count: z.number()
+  }),
+  examples: [{ description: "List your DM conversations" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const meRes = await client.getMe();
+    const userId = meRes.data.id;
+    const allConvos = await collectPaged(
+      (limit, cursor) => client.getDmConversations(userId, limit, cursor),
+      (convo) => ({
+        dm_conversation_id: convo.dm_conversation_id,
+        participant_ids: convo.participant_ids
+      }),
+      c.options.maxResults
+    );
+    const firstParticipant = allConvos[0]?.participant_ids[0];
+    return c.ok(
+      { conversations: allConvos, count: allConvos.length },
+      {
+        cta: firstParticipant ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "dm send",
+              args: { participantId: firstParticipant },
+              options: { text: "Hello!" },
+              description: "Send a message to the first conversation"
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+dm.command("send", {
+  description: "Send a direct message to a user.",
+  args: z.object({
+    participantId: z.string().describe("User ID to send message to")
+  }),
+  options: z.object({
+    text: z.string().describe("Message text")
+  }),
+  output: z.object({
+    dm_conversation_id: z.string(),
+    dm_event_id: z.string()
+  }),
+  examples: [
+    {
+      args: { participantId: "12345" },
+      options: { text: "Hey there!" },
+      description: "Send a DM to a user"
+    }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.sendDm(c.args.participantId, c.options.text);
+    return c.ok(res.data);
+  }
+});
+
+// src/commands/lists.ts
+import { apiKeyAuth as apiKeyAuth2 } from "@spectratools/cli-shared";
+import { Cli as Cli2, z as z2 } from "incur";
+var lists = Cli2.create("lists", {
+  description: "Manage and browse X lists."
+});
+lists.command("get", {
+  description: "Get a list by ID.",
+  args: z2.object({
+    id: z2.string().describe("List ID")
+  }),
+  output: z2.object({
+    id: z2.string(),
+    name: z2.string(),
+    description: z2.string().optional(),
+    owner_id: z2.string().optional(),
+    member_count: z2.number().optional()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get list details" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.getList(c.args.id);
+    const list = res.data;
+    return c.ok(
+      {
+        id: list.id,
+        name: list.name,
+        description: list.description,
+        owner_id: list.owner_id,
+        member_count: list.member_count
+      },
+      {
+        cta: {
+          description: "Explore this list:",
+          commands: [
+            { command: "lists members", args: { id: c.args.id }, description: "See list members" },
+            { command: "lists posts", args: { id: c.args.id }, description: "See list posts" }
+          ]
+        }
+      }
+    );
+  }
+});
+lists.command("members", {
+  description: "List members of an X list.",
+  args: z2.object({
+    id: z2.string().describe("List ID")
+  }),
+  options: z2.object({
+    maxResults: z2.number().default(100).describe("Maximum members to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z2.object({
+    users: z2.array(
+      z2.object({
+        id: z2.string(),
+        name: z2.string(),
+        username: z2.string(),
+        followers: z2.number().optional()
+      })
+    ),
+    count: z2.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "List all members" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const allUsers = await collectPaged(
+      (limit, cursor) => client.getListMembers(c.args.id, limit, cursor),
+      (user) => ({
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        followers: user.public_metrics?.followers_count
+      }),
+      c.options.maxResults
+    );
+    return c.ok({ users: allUsers, count: allUsers.length });
+  }
+});
+lists.command("posts", {
+  description: "Get posts from an X list.",
+  args: z2.object({
+    id: z2.string().describe("List ID")
+  }),
+  options: z2.object({
+    maxResults: z2.number().default(25).describe("Maximum posts to return"),
+    verbose: z2.boolean().optional().describe("Show full text")
+  }),
+  alias: { maxResults: "n" },
+  output: z2.object({
+    posts: z2.array(
+      z2.object({
+        id: z2.string(),
+        text: z2.string(),
+        author_id: z2.string().optional(),
+        created_at: z2.string().optional(),
+        likes: z2.number().optional()
+      })
+    ),
+    count: z2.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get posts from a list" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getListPosts(c.args.id, limit, cursor),
+      (post) => ({
+        id: post.id,
+        text: c.options.verbose ? post.text : truncateText(post.text),
+        author_id: post.author_id,
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0,
+        likes: post.public_metrics?.like_count
+      }),
+      c.options.maxResults
+    );
+    const firstId = allPosts[0]?.id;
+    return c.ok(
+      { posts: allPosts, count: allPosts.length },
+      {
+        cta: firstId ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "posts get",
+              args: { id: firstId },
+              description: "View top post in detail"
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+
+// src/commands/posts.ts
+import { apiKeyAuth as apiKeyAuth3 } from "@spectratools/cli-shared";
+import { Cli as Cli3, z as z3 } from "incur";
+var posts = Cli3.create("posts", {
+  description: "Manage and search X posts."
+});
+posts.command("get", {
+  description: "Get a post by ID.",
+  args: z3.object({
+    id: z3.string().describe("Post ID")
+  }),
+  options: z3.object({
+    verbose: z3.boolean().optional().describe("Show full text without truncation")
+  }),
+  output: z3.object({
+    id: z3.string(),
+    text: z3.string(),
+    author_id: z3.string().optional(),
+    created_at: z3.string().optional(),
+    likes: z3.number().optional(),
+    retweets: z3.number().optional(),
+    replies: z3.number().optional()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get a post by ID" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.getPost(c.args.id);
+    const post = res.data;
+    const text = c.options.verbose ? post.text : truncateText(post.text);
+    return c.ok(
+      {
+        id: post.id,
+        text,
+        author_id: post.author_id,
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0,
+        likes: post.public_metrics?.like_count,
+        retweets: post.public_metrics?.retweet_count,
+        replies: post.public_metrics?.reply_count
+      },
+      {
+        cta: {
+          description: "Explore this post:",
+          commands: [
+            {
+              command: "posts likes",
+              args: { id: c.args.id },
+              description: "See who liked this post"
+            },
+            {
+              command: "posts retweets",
+              args: { id: c.args.id },
+              description: "See who retweeted this post"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+posts.command("search", {
+  description: "Search recent posts.",
+  args: z3.object({
+    query: z3.string().describe("Search query")
+  }),
+  options: z3.object({
+    maxResults: z3.number().default(10).describe("Maximum results to return (10\u2013100)"),
+    sort: z3.enum(["recency", "relevancy"]).default("recency").describe("Sort order"),
+    verbose: z3.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  output: z3.object({
+    posts: z3.array(
+      z3.object({
+        id: z3.string(),
+        text: z3.string(),
+        created_at: z3.string().optional(),
+        likes: z3.number().optional(),
+        retweets: z3.number().optional()
+      })
+    ),
+    count: z3.number()
+  }),
+  examples: [
+    { args: { query: "TypeScript" }, description: "Search for TypeScript posts" },
+    {
+      args: { query: "AI" },
+      options: { sort: "relevancy", maxResults: 20 },
+      description: "Search by relevance"
+    }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.searchPosts(c.args.query, c.options.maxResults, c.options.sort);
+    const items = (res.data ?? []).map((p) => ({
+      id: p.id,
+      text: c.options.verbose ? p.text : truncateText(p.text),
+      created_at: p.created_at ? relativeTime(p.created_at) : void 0,
+      likes: p.public_metrics?.like_count,
+      retweets: p.public_metrics?.retweet_count
+    }));
+    const firstId = items[0]?.id;
+    return c.ok(
+      { posts: items, count: items.length },
+      {
+        cta: firstId ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "posts get",
+              args: { id: firstId },
+              description: "View top result in detail"
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+posts.command("create", {
+  description: "Create a new post.",
+  options: z3.object({
+    text: z3.string().describe("Post text"),
+    replyTo: z3.string().optional().describe("Reply to post ID"),
+    quote: z3.string().optional().describe("Quote post ID")
+  }),
+  output: z3.object({
+    id: z3.string(),
+    text: z3.string()
+  }),
+  examples: [
+    { options: { text: "Hello world!" }, description: "Post a simple message" },
+    { options: { text: "Great point!", replyTo: "1234567890" }, description: "Reply to a post" }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.createPost(c.options.text, c.options.replyTo, c.options.quote);
+    return c.ok(res.data, {
+      cta: {
+        description: "View your post:",
+        commands: [
+          { command: "posts get", args: { id: res.data.id }, description: "See the created post" }
+        ]
+      }
+    });
+  }
+});
+posts.command("delete", {
+  description: "Delete a post by ID.",
+  args: z3.object({
+    id: z3.string().describe("Post ID to delete")
+  }),
+  output: z3.object({
+    deleted: z3.boolean(),
+    id: z3.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Delete a post" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.deletePost(c.args.id);
+    return c.ok({ deleted: res.data.deleted, id: c.args.id });
+  }
+});
+posts.command("likes", {
+  description: "List users who liked a post.",
+  args: z3.object({
+    id: z3.string().describe("Post ID")
+  }),
+  options: z3.object({
+    maxResults: z3.number().default(100).describe("Maximum users to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z3.object({
+    users: z3.array(
+      z3.object({
+        id: z3.string(),
+        name: z3.string(),
+        username: z3.string(),
+        followers: z3.number().optional()
+      })
+    ),
+    count: z3.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "See who liked a post" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const allUsers = await collectPaged(
+      (limit, cursor) => client.getPostLikes(c.args.id, limit, cursor),
+      (user) => ({
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        followers: user.public_metrics?.followers_count
+      }),
+      c.options.maxResults
+    );
+    return c.ok(
+      { users: allUsers, count: allUsers.length },
+      {
+        cta: {
+          description: "Next steps:",
+          commands: allUsers.slice(0, 1).map((u) => ({
+            command: "users get",
+            args: { username: u.username },
+            description: `View profile of @${u.username}`
+          }))
+        }
+      }
+    );
+  }
+});
+posts.command("retweets", {
+  description: "List users who retweeted a post.",
+  args: z3.object({
+    id: z3.string().describe("Post ID")
+  }),
+  options: z3.object({
+    maxResults: z3.number().default(100).describe("Maximum users to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z3.object({
+    users: z3.array(
+      z3.object({
+        id: z3.string(),
+        name: z3.string(),
+        username: z3.string(),
+        followers: z3.number().optional()
+      })
+    ),
+    count: z3.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "See who retweeted a post" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const allUsers = await collectPaged(
+      (limit, cursor) => client.getPostRetweets(c.args.id, limit, cursor),
+      (user) => ({
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        followers: user.public_metrics?.followers_count
+      }),
+      c.options.maxResults
+    );
+    return c.ok({ users: allUsers, count: allUsers.length });
+  }
+});
+
+// src/commands/timeline.ts
+import { apiKeyAuth as apiKeyAuth4 } from "@spectratools/cli-shared";
+import { Cli as Cli4, z as z4 } from "incur";
+var timeline = Cli4.create("timeline", {
+  description: "View your X timeline."
+});
+timeline.command("home", {
+  description: "View your home timeline.",
+  options: z4.object({
+    maxResults: z4.number().default(25).describe("Maximum posts to return (5\u2013100)"),
+    verbose: z4.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  output: z4.object({
+    posts: z4.array(
+      z4.object({
+        id: z4.string(),
+        text: z4.string(),
+        author_id: z4.string().optional(),
+        created_at: z4.string().optional(),
+        likes: z4.number().optional(),
+        retweets: z4.number().optional()
+      })
+    ),
+    count: z4.number()
+  }),
+  examples: [
+    { description: "View your home timeline" },
+    { options: { maxResults: 50 }, description: "View 50 posts" }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth4("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const meRes = await client.getMe();
+    const userId = meRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getHomeTimeline(userId, limit, cursor),
+      (post) => ({
+        id: post.id,
+        text: c.options.verbose ? post.text : truncateText(post.text),
+        author_id: post.author_id,
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0,
+        likes: post.public_metrics?.like_count,
+        retweets: post.public_metrics?.retweet_count
+      }),
+      c.options.maxResults
+    );
+    const firstId = allPosts[0]?.id;
+    return c.ok(
+      { posts: allPosts, count: allPosts.length },
+      {
+        cta: firstId ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "posts get",
+              args: { id: firstId },
+              description: "View top post in detail"
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+timeline.command("mentions", {
+  description: "View your recent mentions.",
+  options: z4.object({
+    maxResults: z4.number().default(25).describe("Maximum mentions to return"),
+    verbose: z4.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  output: z4.object({
+    posts: z4.array(
+      z4.object({
+        id: z4.string(),
+        text: z4.string(),
+        author_id: z4.string().optional(),
+        created_at: z4.string().optional()
+      })
+    ),
+    count: z4.number()
+  }),
+  examples: [{ description: "View your recent mentions" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth4("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const meRes = await client.getMe();
+    const userId = meRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getMentionsTimeline(userId, limit, cursor),
+      (post) => ({
+        id: post.id,
+        text: c.options.verbose ? post.text : truncateText(post.text),
+        author_id: post.author_id,
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0
+      }),
+      c.options.maxResults
+    );
+    return c.ok({ posts: allPosts, count: allPosts.length });
+  }
+});
+
+// src/commands/trends.ts
+import { apiKeyAuth as apiKeyAuth5 } from "@spectratools/cli-shared";
+import { Cli as Cli5, z as z5 } from "incur";
+var trends = Cli5.create("trends", {
+  description: "Explore trending topics on X."
+});
+trends.command("places", {
+  description: "List places where trending topics are available.",
+  output: z5.object({
+    places: z5.array(
+      z5.object({
+        woeid: z5.number(),
+        name: z5.string(),
+        country: z5.string()
+      })
+    ),
+    count: z5.number()
+  }),
+  examples: [{ description: "List all trending places" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth5("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.getTrendingPlaces();
+    const places = res.data ?? [];
+    const first = places[0];
+    return c.ok(
+      { places, count: places.length },
+      {
+        cta: first ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "trends location",
+              args: { woeid: first.woeid },
+              description: `View trends for ${first.name}`
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+trends.command("location", {
+  description: "Get trending topics for a specific location (WOEID).",
+  args: z5.object({
+    woeid: z5.string().describe("Where On Earth ID (from trends places)")
+  }),
+  output: z5.object({
+    trends: z5.array(
+      z5.object({
+        name: z5.string(),
+        query: z5.string(),
+        tweet_volume: z5.number().optional()
+      })
+    ),
+    count: z5.number()
+  }),
+  examples: [
+    { args: { woeid: "1" }, description: "Get worldwide trends" },
+    { args: { woeid: "2459115" }, description: "Get trends for New York" }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth5("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.getTrendsByLocation(Number(c.args.woeid));
+    const trendItems = res.data ?? [];
+    const firstTrend = trendItems[0];
+    return c.ok(
+      { trends: trendItems, count: trendItems.length },
+      {
+        cta: firstTrend ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "posts search",
+              args: { query: firstTrend.query },
+              description: `Search posts about "${firstTrend.name}"`
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+
+// src/commands/users.ts
+import { apiKeyAuth as apiKeyAuth6 } from "@spectratools/cli-shared";
+import { Cli as Cli6, z as z6 } from "incur";
+var users = Cli6.create("users", {
+  description: "Look up X users."
+});
+async function resolveUser(client, usernameOrId) {
+  if (/^\d+$/.test(usernameOrId)) {
+    return client.getUserById(usernameOrId);
+  }
+  return client.getUserByUsername(usernameOrId.replace(/^@/, ""));
+}
+users.command("get", {
+  description: "Get a user by username or ID.",
+  args: z6.object({
+    username: z6.string().describe("Username (with or without @) or user ID")
+  }),
+  options: z6.object({
+    verbose: z6.boolean().optional().describe("Show full bio without truncation")
+  }),
+  output: z6.object({
+    id: z6.string(),
+    name: z6.string(),
+    username: z6.string(),
+    description: z6.string().optional(),
+    followers: z6.number().optional(),
+    following: z6.number().optional(),
+    tweets: z6.number().optional(),
+    joined: z6.string().optional()
+  }),
+  examples: [
+    { args: { username: "jack" }, description: "Get a user by username" },
+    { args: { username: "12345" }, description: "Get a user by ID" }
+  ],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await resolveUser(client, c.args.username);
+    const user = res.data;
+    return c.ok(
+      {
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        description: user.description ? c.options.verbose ? user.description : truncateText(user.description) : void 0,
+        followers: user.public_metrics?.followers_count,
+        following: user.public_metrics?.following_count,
+        tweets: user.public_metrics?.tweet_count,
+        joined: user.created_at ? relativeTime(user.created_at) : void 0
+      },
+      {
+        cta: {
+          description: "Explore this user:",
+          commands: [
+            {
+              command: "users posts",
+              args: { username: user.username },
+              description: "View their posts"
+            },
+            {
+              command: "users followers",
+              args: { username: user.username },
+              description: "View their followers"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+users.command("followers", {
+  description: "List followers of a user.",
+  args: z6.object({
+    username: z6.string().describe("Username or user ID")
+  }),
+  options: z6.object({
+    maxResults: z6.number().default(100).describe("Maximum followers to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z6.object({
+    users: z6.array(
+      z6.object({
+        id: z6.string(),
+        name: z6.string(),
+        username: z6.string(),
+        followers: z6.number().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "List followers of jack" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const userRes = await resolveUser(client, c.args.username);
+    const userId = userRes.data.id;
+    const allUsers = await collectPaged(
+      (limit, cursor) => client.getUserFollowers(userId, limit, cursor),
+      (user) => ({
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        followers: user.public_metrics?.followers_count
+      }),
+      c.options.maxResults,
+      1e3
+    );
+    return c.ok({ users: allUsers, count: allUsers.length });
+  }
+});
+users.command("following", {
+  description: "List accounts a user is following.",
+  args: z6.object({
+    username: z6.string().describe("Username or user ID")
+  }),
+  options: z6.object({
+    maxResults: z6.number().default(100).describe("Maximum accounts to return")
+  }),
+  alias: { maxResults: "n" },
+  output: z6.object({
+    users: z6.array(
+      z6.object({
+        id: z6.string(),
+        name: z6.string(),
+        username: z6.string(),
+        followers: z6.number().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "List accounts jack follows" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const userRes = await resolveUser(client, c.args.username);
+    const userId = userRes.data.id;
+    const allUsers = await collectPaged(
+      (limit, cursor) => client.getUserFollowing(userId, limit, cursor),
+      (user) => ({
+        id: user.id,
+        name: user.name,
+        username: user.username,
+        followers: user.public_metrics?.followers_count
+      }),
+      c.options.maxResults,
+      1e3
+    );
+    return c.ok({ users: allUsers, count: allUsers.length });
+  }
+});
+users.command("posts", {
+  description: "List a user's posts.",
+  args: z6.object({
+    username: z6.string().describe("Username or user ID")
+  }),
+  options: z6.object({
+    maxResults: z6.number().default(10).describe("Maximum posts to return"),
+    verbose: z6.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  output: z6.object({
+    posts: z6.array(
+      z6.object({
+        id: z6.string(),
+        text: z6.string(),
+        created_at: z6.string().optional(),
+        likes: z6.number().optional(),
+        retweets: z6.number().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Get jack's recent posts" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const userRes = await resolveUser(client, c.args.username);
+    const userId = userRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getUserPosts(userId, limit, cursor),
+      (post) => ({
+        id: post.id,
+        text: c.options.verbose ? post.text : truncateText(post.text),
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0,
+        likes: post.public_metrics?.like_count,
+        retweets: post.public_metrics?.retweet_count
+      }),
+      c.options.maxResults
+    );
+    const firstId = allPosts[0]?.id;
+    return c.ok(
+      { posts: allPosts, count: allPosts.length },
+      {
+        cta: firstId ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "posts get",
+              args: { id: firstId },
+              description: "View top post in detail"
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+users.command("mentions", {
+  description: "List recent mentions of a user.",
+  args: z6.object({
+    username: z6.string().describe("Username or user ID")
+  }),
+  options: z6.object({
+    maxResults: z6.number().default(10).describe("Maximum mentions to return"),
+    verbose: z6.boolean().optional().describe("Show full text")
+  }),
+  alias: { maxResults: "n" },
+  output: z6.object({
+    posts: z6.array(
+      z6.object({
+        id: z6.string(),
+        text: z6.string(),
+        created_at: z6.string().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Get mentions of jack" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const userRes = await resolveUser(client, c.args.username);
+    const userId = userRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getUserMentions(userId, limit, cursor),
+      (post) => ({
+        id: post.id,
+        text: c.options.verbose ? post.text : truncateText(post.text),
+        created_at: post.created_at ? relativeTime(post.created_at) : void 0
+      }),
+      c.options.maxResults
+    );
+    return c.ok({ posts: allPosts, count: allPosts.length });
+  }
+});
+users.command("search", {
+  description: "Search for users by keyword.",
+  args: z6.object({
+    query: z6.string().describe("Search query")
+  }),
+  output: z6.object({
+    users: z6.array(
+      z6.object({
+        id: z6.string(),
+        name: z6.string(),
+        username: z6.string(),
+        followers: z6.number().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ args: { query: "TypeScript" }, description: "Search for users about TypeScript" }],
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
+    const client = createXApiClient(apiKey);
+    const res = await client.searchUsers(c.args.query);
+    const items = (res.data ?? []).map((u) => ({
+      id: u.id,
+      name: u.name,
+      username: u.username,
+      followers: u.public_metrics?.followers_count
+    }));
+    const first = items[0];
+    return c.ok(
+      { users: items, count: items.length },
+      {
+        cta: first ? {
+          description: "Next steps:",
+          commands: [
+            {
+              command: "users get",
+              args: { username: first.username },
+              description: `View @${first.username}'s profile`
+            }
+          ]
+        } : void 0
+      }
+    );
+  }
+});
+
+// src/cli.ts
+var cli = Cli7.create("xapi", {
+  description: "X (Twitter) API CLI for spectra-the-bot."
+});
+cli.command(posts);
+cli.command(users);
+cli.command(timeline);
+cli.command(lists);
+cli.command(trends);
+cli.command(dm);
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  cli.serve();
+}
+export {
+  cli
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@spectratools/xapi-cli",
+  "version": "0.1.0",
+  "description": "X (Twitter) API CLI for spectra-the-bot",
+  "type": "module",
+  "license": "MIT",
+  "author": "spectra-the-bot",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "xapi-cli": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "incur": "^0.2.2",
+    "@spectratools/cli-shared": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3",
+    "vitest": "2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/cli.js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}