@spectratools/xapi-cli 0.6.1 → 0.6.2

package/dist/index.js

@@ -0,0 +1,2058 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync2, realpathSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { Cli as Cli7 } from "incur";
+
+// src/auth.ts
+import { HttpError } from "@spectratools/cli-shared";
+import { z } from "incur";
+var bearerTokenSchema = z.string().describe("X app-only bearer token (read-only endpoints)");
+var accessTokenSchema = z.string().describe("X OAuth 2.0 user access token (required for write endpoints)");
+var xApiReadEnv = z.object({
+  X_BEARER_TOKEN: bearerTokenSchema.optional(),
+  X_ACCESS_TOKEN: accessTokenSchema.optional()
+}).refine((env) => Boolean(env.X_ACCESS_TOKEN || env.X_BEARER_TOKEN), {
+  message: "Set X_ACCESS_TOKEN or X_BEARER_TOKEN to authenticate X API requests."
+});
+var xApiWriteEnv = z.object({
+  X_ACCESS_TOKEN: accessTokenSchema,
+  X_BEARER_TOKEN: bearerTokenSchema.optional()
+});
+function readAuthToken(env) {
+  if (env.X_ACCESS_TOKEN) {
+    return env.X_ACCESS_TOKEN;
+  }
+  return env.X_BEARER_TOKEN;
+}
+function writeAuthToken(env) {
+  return env.X_ACCESS_TOKEN;
+}
+function parseXApiErrorDetail(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed !== "object" || parsed === null) {
+      return void 0;
+    }
+    const candidate = parsed;
+    if (typeof candidate.detail === "string" && candidate.detail.trim()) return candidate.detail;
+    if (typeof candidate.title === "string" && candidate.title.trim()) return candidate.title;
+    const firstError = candidate.errors?.[0];
+    if (typeof firstError?.message === "string" && firstError.message.trim())
+      return firstError.message;
+    if (typeof firstError?.detail === "string" && firstError.detail.trim())
+      return firstError.detail;
+  } catch {
+  }
+  return void 0;
+}
+function readEndpointNeedsUserToken(detail) {
+  if (!detail) return false;
+  const normalized = detail.toLowerCase();
+  return normalized.includes("application-only is forbidden") || normalized.includes("oauth 2.0 application-only") || normalized.includes("app-only") || normalized.includes("user context");
+}
+function toReadAuthError(operation, error) {
+  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+    const detail = parseXApiErrorDetail(error.body);
+    const requiresUserToken = readEndpointNeedsUserToken(detail);
+    return {
+      code: "INSUFFICIENT_READ_AUTH",
+      message: [
+        "Insufficient auth for read endpoint:",
+        `- operation: ${operation}`,
+        `- status: ${error.status} ${error.statusText}`,
+        requiresUserToken ? "- required auth: X_ACCESS_TOKEN (OAuth 2.0 user token required for this endpoint)" : "- required auth: X_ACCESS_TOKEN or X_BEARER_TOKEN (with required read scopes)",
+        ...detail ? [`- x_api_detail: ${detail}`] : []
+      ].join("\n")
+    };
+  }
+  return void 0;
+}
+function toWriteAuthError(operation, error) {
+  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+    const detail = parseXApiErrorDetail(error.body);
+    return {
+      code: "INSUFFICIENT_WRITE_AUTH",
+      message: [
+        "Insufficient auth for write endpoint:",
+        `- operation: ${operation}`,
+        `- status: ${error.status} ${error.statusText}`,
+        "- required auth: X_ACCESS_TOKEN (OAuth 2.0 user token with write scopes)",
+        "- note: app-only X_BEARER_TOKEN cannot perform write actions",
+        ...detail ? [`- x_api_detail: ${detail}`] : []
+      ].join("\n")
+    };
+  }
+  return void 0;
+}
+function toXApiHttpError(operation, error) {
+  if (!(error instanceof HttpError)) {
+    return void 0;
+  }
+  const detail = parseXApiErrorDetail(error.body);
+  return {
+    code: "X_API_REQUEST_FAILED",
+    message: [
+      "X API request failed:",
+      `- operation: ${operation}`,
+      `- status: ${error.status} ${error.statusText}`,
+      ...detail ? [`- x_api_detail: ${detail}`] : []
+    ].join("\n")
+  };
+}
+function toXApiCommandError(operation, error, authScope = "read") {
+  const authError = authScope === "write" ? toWriteAuthError(operation, error) : toReadAuthError(operation, error);
+  if (authError) {
+    return authError;
+  }
+  return toXApiHttpError(operation, error);
+}
+
+// src/commands/dm.ts
+import { Cli, z as z2 } from "incur";
+
+// src/api.ts
+import { createHttpClient, withRetry } from "@spectratools/cli-shared";
+var BASE_URL_V2 = "https://api.x.com/2";
+var BASE_URL_V1_1 = "https://api.x.com/1.1";
+var RETRY_OPTIONS = { maxRetries: 3, baseMs: 500, maxMs: 1e4 };
+function createXApiClient(bearerToken) {
+  const defaultHeaders = {
+    Authorization: `Bearer ${bearerToken}`
+  };
+  const httpV2 = createHttpClient({
+    baseUrl: BASE_URL_V2,
+    defaultHeaders
+  });
+  const httpV1_1 = createHttpClient({
+    baseUrl: BASE_URL_V1_1,
+    defaultHeaders
+  });
+  function get(path, query) {
+    return withRetry(
+      () => httpV2.request(path, query !== void 0 ? { query } : {}),
+      RETRY_OPTIONS
+    );
+  }
+  function getV1_1(path, query) {
+    return withRetry(
+      () => httpV1_1.request(path, query !== void 0 ? { query } : {}),
+      RETRY_OPTIONS
+    );
+  }
+  function post(path, body) {
+    return withRetry(() => httpV2.request(path, { method: "POST", body }), RETRY_OPTIONS);
+  }
+  function del(path) {
+    return withRetry(() => httpV2.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 } : {}
+    });
+  }
+  function likePost(userId, tweetId) {
+    return post(`/users/${userId}/likes`, { tweet_id: tweetId });
+  }
+  function unlikePost(userId, tweetId) {
+    return del(`/users/${userId}/likes/${tweetId}`);
+  }
+  function bookmarkPost(userId, tweetId) {
+    return post(`/users/${userId}/bookmarks`, { tweet_id: tweetId });
+  }
+  function unbookmarkPost(userId, tweetId) {
+    return del(`/users/${userId}/bookmarks/${tweetId}`);
+  }
+  function retweetPost(userId, tweetId) {
+    return post(`/users/${userId}/retweets`, { tweet_id: tweetId });
+  }
+  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 followUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/following`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unfollowUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/following/${targetUserId}`);
+  }
+  function blockUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/blocking`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unblockUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/blocking/${targetUserId}`);
+  }
+  function muteUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/muting`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unmuteUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/muting/${targetUserId}`);
+  }
+  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, sinceId) {
+    return get(`/users/${userId}/timelines/reverse_chronological`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {},
+      ...sinceId ? { since_id: sinceId } : {}
+    });
+  }
+  function getMentionsTimeline(userId, maxResults, nextToken, sinceId) {
+    return get(`/users/${userId}/mentions`, {
+      max_results: maxResults,
+      "tweet.fields": POST_FIELDS,
+      ...nextToken ? { pagination_token: nextToken } : {},
+      ...sinceId ? { since_id: sinceId } : {}
+    });
+  }
+  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 createList(name, description, isPrivate) {
+    return post("/lists", {
+      name,
+      ...description ? { description } : {},
+      ...isPrivate !== void 0 ? { private: isPrivate } : {}
+    });
+  }
+  function deleteList(id) {
+    return del(`/lists/${id}`);
+  }
+  function addListMember(id, userId) {
+    return post(`/lists/${id}/members`, {
+      user_id: userId
+    });
+  }
+  function removeListMember(id, userId) {
+    return del(`/lists/${id}/members/${userId}`);
+  }
+  function getTrendingPlaces() {
+    return getV1_1(
+      "/trends/available.json"
+    ).then((places) => ({ data: places }));
+  }
+  function getTrendsByLocation(woeid) {
+    return getV1_1("/trends/place.json", { id: woeid }).then((locations) => {
+      const trends2 = (locations[0]?.trends ?? []).map((trend) => ({
+        name: trend.name,
+        query: trend.query,
+        tweet_volume: trend.tweet_volume ?? void 0
+      }));
+      return { data: trends2 };
+    });
+  }
+  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,
+    likePost,
+    unlikePost,
+    bookmarkPost,
+    unbookmarkPost,
+    retweetPost,
+    getUserByUsername,
+    getUserById,
+    getUserFollowers,
+    getUserFollowing,
+    followUser,
+    unfollowUser,
+    blockUser,
+    unblockUser,
+    muteUser,
+    unmuteUser,
+    getUserPosts,
+    getUserMentions,
+    searchUsers,
+    getHomeTimeline,
+    getMentionsTimeline,
+    getList,
+    getListMembers,
+    getListPosts,
+    createList,
+    deleteList,
+    addListMember,
+    removeListMember,
+    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: z2.object({
+    maxResults: z2.number().default(20).describe("Maximum conversations to return")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z2.object({
+    conversations: z2.array(
+      z2.object({
+        dm_conversation_id: z2.string(),
+        participant_ids: z2.array(z2.string())
+      })
+    ),
+    count: z2.number()
+  }),
+  examples: [{ description: "List your DM conversations" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z2.object({
+    participantId: z2.string().describe("User ID to send message to")
+  }),
+  options: z2.object({
+    text: z2.string().describe("Message text")
+  }),
+  env: xApiWriteEnv,
+  output: z2.object({
+    dm_conversation_id: z2.string(),
+    dm_event_id: z2.string()
+  }),
+  examples: [
+    {
+      args: { participantId: "12345" },
+      options: { text: "Hey there!" },
+      description: "Send a DM to a user"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.sendDm(c.args.participantId, c.options.text);
+      return c.ok(res.data);
+    } catch (error) {
+      const authError = toWriteAuthError("dm send", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+
+// src/commands/lists.ts
+import { Cli as Cli2, z as z3 } from "incur";
+var lists = Cli2.create("lists", {
+  description: "Manage and browse X lists."
+});
+var listIdSchema = z3.string().min(1).describe("List ID");
+var memberSchema = z3.string().trim().min(1).describe("Member to target (username with or without @, or user ID)");
+var createListOptionsSchema = z3.object({
+  name: z3.string().trim().min(1).max(25).describe("List name (1-25 characters)"),
+  description: z3.string().trim().min(1).max(100).optional().describe("Optional list description (1-100 characters)"),
+  private: z3.boolean().default(false).describe("Create as a private list")
+});
+async function resolveMemberTarget(client, usernameOrId) {
+  const normalized = usernameOrId.replace(/^@/, "");
+  if (/^\d+$/.test(normalized)) {
+    return { id: normalized };
+  }
+  const user = await client.getUserByUsername(normalized);
+  return {
+    id: user.data.id,
+    username: user.data.username
+  };
+}
+lists.command("get", {
+  description: "Get a list by ID.",
+  args: z3.object({
+    id: listIdSchema
+  }),
+  env: xApiReadEnv,
+  output: z3.object({
+    id: z3.string(),
+    name: z3.string(),
+    description: z3.string().optional(),
+    owner_id: z3.string().optional(),
+    member_count: z3.number().optional()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get list details" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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("create", {
+  description: "Create a new list.",
+  options: createListOptionsSchema,
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    name: z3.string()
+  }),
+  examples: [
+    {
+      options: { name: "Core devs", description: "Builders only", private: true },
+      description: "Create a private list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.createList(c.options.name, c.options.description, c.options.private);
+      return c.ok(
+        res.data,
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Next steps:",
+            commands: [
+              {
+                command: "lists get",
+                args: { id: res.data.id },
+                description: "View the list details"
+              },
+              {
+                command: "lists add-member",
+                args: { id: res.data.id, member: "username-or-id" },
+                description: "Add members to the new list"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists create", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("delete", {
+  description: "Delete a list by ID.",
+  args: z3.object({
+    id: listIdSchema.describe("List ID to delete")
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    deleted: z3.boolean(),
+    id: z3.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Delete a list" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.deleteList(c.args.id);
+      return c.ok({ deleted: res.data.deleted, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("lists delete", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("add-member", {
+  description: "Add a member to an X list.",
+  args: z3.object({
+    id: listIdSchema,
+    member: memberSchema
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    member_id: z3.string(),
+    member_username: z3.string().optional(),
+    is_member: z3.boolean()
+  }),
+  examples: [
+    {
+      args: { id: "1234567890", member: "jack" },
+      description: "Add @jack to a list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const member = await resolveMemberTarget(client, c.args.member);
+      const res = await client.addListMember(c.args.id, member.id);
+      return c.ok(
+        {
+          id: c.args.id,
+          member_id: member.id,
+          member_username: member.username,
+          is_member: res.data.is_member
+        },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Verify list membership:",
+            commands: [
+              {
+                command: "lists members",
+                args: { id: c.args.id },
+                description: "View current list members"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists add-member", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("remove-member", {
+  description: "Remove a member from an X list.",
+  args: z3.object({
+    id: listIdSchema,
+    member: memberSchema
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    member_id: z3.string(),
+    member_username: z3.string().optional(),
+    is_member: z3.boolean()
+  }),
+  examples: [
+    {
+      args: { id: "1234567890", member: "jack" },
+      description: "Remove @jack from a list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const member = await resolveMemberTarget(client, c.args.member);
+      const res = await client.removeListMember(c.args.id, member.id);
+      return c.ok(
+        {
+          id: c.args.id,
+          member_id: member.id,
+          member_username: member.username,
+          is_member: res.data.is_member
+        },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Next steps:",
+            commands: [
+              {
+                command: "lists members",
+                args: { id: c.args.id },
+                description: "Confirm updated membership"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists remove-member", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("members", {
+  description: "List members of an X list.",
+  args: z3.object({
+    id: listIdSchema
+  }),
+  options: z3.object({
+    maxResults: z3.number().default(100).describe("Maximum members to return")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  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: "List all members" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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: z3.object({
+    id: listIdSchema
+  }),
+  options: z3.object({
+    maxResults: z3.number().default(25).describe("Maximum posts to return"),
+    verbose: z3.boolean().optional().describe("Show full text")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z3.object({
+    posts: z3.array(
+      z3.object({
+        id: z3.string(),
+        text: z3.string(),
+        author_id: z3.string().optional(),
+        created_at: z3.string().optional(),
+        likes: z3.number().optional()
+      })
+    ),
+    count: z3.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get posts from a list" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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 { Cli as Cli3, z as z4 } from "incur";
+var posts = Cli3.create("posts", {
+  description: "Manage and search X posts."
+});
+posts.command("get", {
+  description: "Get a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID")
+  }),
+  options: z4.object({
+    verbose: z4.boolean().optional().describe("Show full text without truncation")
+  }),
+  env: xApiReadEnv,
+  output: 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(),
+    replies: z4.number().optional()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Get a post by ID" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z4.object({
+    query: z4.string().describe("Search query")
+  }),
+  options: z4.object({
+    maxResults: z4.number().int().min(10).max(100).default(10).describe("Maximum results to return (10\u2013100)"),
+    sort: z4.enum(["recency", "relevancy"]).default("recency").describe("Sort order"),
+    verbose: z4.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z4.object({
+    posts: z4.array(
+      z4.object({
+        id: z4.string(),
+        text: z4.string(),
+        created_at: z4.string().optional(),
+        likes: z4.number().optional(),
+        retweets: z4.number().optional()
+      })
+    ),
+    count: z4.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 client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z4.object({
+    text: z4.string().describe("Post text"),
+    replyTo: z4.string().optional().describe("Reply to post ID"),
+    quote: z4.string().optional().describe("Quote post ID")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    id: z4.string(),
+    text: z4.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) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.createPost(c.options.text, c.options.replyTo, c.options.quote);
+      return c.ok(
+        res.data,
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "View your post:",
+            commands: [
+              {
+                command: "posts get",
+                args: { id: res.data.id },
+                description: "See the created post"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("posts create", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("delete", {
+  description: "Delete a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to delete")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    deleted: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Delete a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.deletePost(c.args.id);
+      return c.ok({ deleted: res.data.deleted, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts delete", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("like", {
+  description: "Like a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to like")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    liked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Like a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.likePost(me.data.id, c.args.id);
+      return c.ok({ liked: res.data.liked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts like", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("unlike", {
+  description: "Unlike a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to unlike")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    liked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Unlike a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.unlikePost(me.data.id, c.args.id);
+      return c.ok({ liked: res.data.liked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts unlike", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("bookmark", {
+  description: "Bookmark a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to bookmark")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    bookmarked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Bookmark a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.bookmarkPost(me.data.id, c.args.id);
+      return c.ok({ bookmarked: res.data.bookmarked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts bookmark", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("unbookmark", {
+  description: "Remove bookmark from a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to unbookmark")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    bookmarked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Remove a bookmark from a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.unbookmarkPost(me.data.id, c.args.id);
+      return c.ok({ bookmarked: res.data.bookmarked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts unbookmark", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("retweet", {
+  description: "Retweet a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to retweet")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    retweeted: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Retweet a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.retweetPost(me.data.id, c.args.id);
+      return c.ok({ retweeted: res.data.retweeted, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts retweet", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("likes", {
+  description: "List users who liked a post.",
+  args: z4.object({
+    id: z4.string().describe("Post ID")
+  }),
+  options: z4.object({
+    maxResults: z4.number().default(100).describe("Maximum users to return")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z4.object({
+    users: z4.array(
+      z4.object({
+        id: z4.string(),
+        name: z4.string(),
+        username: z4.string(),
+        followers: z4.number().optional()
+      })
+    ),
+    count: z4.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "See who liked a post" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z4.object({
+    id: z4.string().describe("Post ID")
+  }),
+  options: z4.object({
+    maxResults: z4.number().default(100).describe("Maximum users to return")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z4.object({
+    users: z4.array(
+      z4.object({
+        id: z4.string(),
+        name: z4.string(),
+        username: z4.string(),
+        followers: z4.number().optional()
+      })
+    ),
+    count: z4.number()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "See who retweeted a post" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 { Cli as Cli4, z as z5 } from "incur";
+var timeline = Cli4.create("timeline", {
+  description: "View your X timeline."
+});
+timeline.command("home", {
+  description: "View your home timeline.",
+  options: z5.object({
+    maxResults: z5.number().default(25).describe("Maximum posts to return (5\u2013100)"),
+    sinceId: z5.string().optional().describe("Only return posts newer than this post ID"),
+    verbose: z5.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z5.object({
+    posts: z5.array(
+      z5.object({
+        id: z5.string(),
+        text: z5.string(),
+        author_id: z5.string().optional(),
+        created_at: z5.string().optional(),
+        likes: z5.number().optional(),
+        retweets: z5.number().optional()
+      })
+    ),
+    count: z5.number()
+  }),
+  examples: [
+    { description: "View your home timeline" },
+    { options: { maxResults: 50 }, description: "View 50 posts" },
+    {
+      options: { sinceId: "1900123456789012345" },
+      description: "Resume from last-seen post ID"
+    }
+  ],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    const meRes = await client.getMe();
+    const userId = meRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getHomeTimeline(userId, limit, cursor, c.options.sinceId),
+      (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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z5.object({
+    maxResults: z5.number().default(25).describe("Maximum mentions to return"),
+    sinceId: z5.string().optional().describe("Only return mentions newer than this post ID"),
+    verbose: z5.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z5.object({
+    posts: z5.array(
+      z5.object({
+        id: z5.string(),
+        text: z5.string(),
+        author_id: z5.string().optional(),
+        created_at: z5.string().optional()
+      })
+    ),
+    count: z5.number()
+  }),
+  examples: [
+    { description: "View your recent mentions" },
+    {
+      options: { sinceId: "1900123456789012345" },
+      description: "Resume mentions from last-seen post ID"
+    }
+  ],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    const meRes = await client.getMe();
+    const userId = meRes.data.id;
+    const allPosts = await collectPaged(
+      (limit, cursor) => client.getMentionsTimeline(userId, limit, cursor, c.options.sinceId),
+      (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 { Cli as Cli5, z as z6 } from "incur";
+var trends = Cli5.create("trends", {
+  description: "Explore trending topics on X."
+});
+trends.command("places", {
+  description: "List places where trending topics are available.",
+  env: xApiReadEnv,
+  output: z6.object({
+    places: z6.array(
+      z6.object({
+        woeid: z6.number(),
+        name: z6.string(),
+        country: z6.string()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [{ description: "List all trending places" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    const res = await client.getTrendingPlaces();
+    const places = res.data ?? [];
+    const first = places[0];
+    return c.ok(
+      { places, count: places.length },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z6.object({
+    woeid: z6.string().describe("Where On Earth ID (from trends places)")
+  }),
+  env: xApiReadEnv,
+  output: z6.object({
+    trends: z6.array(
+      z6.object({
+        name: z6.string(),
+        query: z6.string(),
+        tweet_volume: z6.number().optional()
+      })
+    ),
+    count: z6.number()
+  }),
+  examples: [
+    { args: { woeid: "1" }, description: "Get worldwide trends" },
+    { args: { woeid: "2459115" }, description: "Get trends for New York" }
+  ],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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 { readFileSync } from "fs";
+import { Cli as Cli6, z as z7 } 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(/^@/, ""));
+}
+function formatUserProfile(user, verbose) {
+  return {
+    id: user.id,
+    name: user.name,
+    username: user.username,
+    description: user.description ? 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
+  };
+}
+function readSeenIds(filePath) {
+  const fileContents = readFileSync(filePath, "utf8");
+  return new Set(
+    fileContents.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+  );
+}
+var followersOptionsSchema = z7.object({
+  maxResults: z7.number().default(100).describe("Maximum followers to return"),
+  seenIdsFile: z7.string().optional().describe(
+    "Path to newline-delimited follower IDs used as a baseline for client-side diffing"
+  ),
+  newOnly: z7.boolean().default(false).describe(
+    "Return only followers not found in --seen-ids-file (client-side baseline diff; not API-native since_id)"
+  )
+}).refine((options) => !options.newOnly || Boolean(options.seenIdsFile), {
+  path: ["seenIdsFile"],
+  message: "--seen-ids-file is required when --new-only is set"
+});
+users.command("me", {
+  description: "Get the authenticated user profile and metrics.",
+  options: z7.object({
+    verbose: z7.boolean().optional().describe("Show full bio without truncation")
+  }),
+  env: xApiReadEnv,
+  output: z7.object({
+    id: z7.string(),
+    name: z7.string(),
+    username: z7.string(),
+    description: z7.string().optional(),
+    followers: z7.number().optional(),
+    following: z7.number().optional(),
+    tweets: z7.number().optional(),
+    joined: z7.string().optional()
+  }),
+  examples: [{ description: "Get your authenticated profile", options: {} }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    const res = await client.getMe();
+    const user = res.data;
+    return c.ok(
+      formatUserProfile(user, c.options.verbose),
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore your account:",
+          commands: [
+            {
+              command: "users followers",
+              args: { username: user.username },
+              description: "View your followers"
+            },
+            {
+              command: "users posts",
+              args: { username: user.username },
+              description: "View your recent posts"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+users.command("get", {
+  description: "Get a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  options: z7.object({
+    verbose: z7.boolean().optional().describe("Show full bio without truncation")
+  }),
+  env: xApiReadEnv,
+  output: z7.object({
+    id: z7.string(),
+    name: z7.string(),
+    username: z7.string(),
+    description: z7.string().optional(),
+    followers: z7.number().optional(),
+    following: z7.number().optional(),
+    tweets: z7.number().optional(),
+    joined: z7.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 client = createXApiClient(readAuthToken(c.env));
+    const res = await resolveUser(client, c.args.username);
+    const user = res.data;
+    return c.ok(
+      formatUserProfile(user, c.options.verbose),
+      c.format === "json" || c.format === "jsonl" ? 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("follow", {
+  description: "Follow a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    following: z7.boolean(),
+    pending_follow: z7.boolean().optional()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Follow @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.followUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        following: res.data.following,
+        pending_follow: res.data.pending_follow
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users follow", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unfollow", {
+  description: "Unfollow a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    following: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unfollow @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.unfollowUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        following: res.data.following
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unfollow", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("block", {
+  description: "Block a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    blocking: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Block @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.blockUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        blocking: res.data.blocking
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users block", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unblock", {
+  description: "Unblock a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    blocking: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unblock @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.unblockUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        blocking: res.data.blocking
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unblock", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("mute", {
+  description: "Mute a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    muting: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Mute @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.muteUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        muting: res.data.muting
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users mute", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unmute", {
+  description: "Unmute a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    muting: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unmute @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.unmuteUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        muting: res.data.muting
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unmute", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("followers", {
+  description: "List followers of a user. Supports optional client-side baseline diffing for new follower detection.",
+  args: z7.object({
+    username: z7.string().describe("Username or user ID")
+  }),
+  options: followersOptionsSchema,
+  alias: { maxResults: "n", seenIdsFile: "s" },
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
+      })
+    ),
+    count: z7.number()
+  }),
+  examples: [
+    { args: { username: "jack" }, description: "List followers of jack" },
+    {
+      args: { username: "jack" },
+      options: { seenIdsFile: "./seen-followers.txt", newOnly: true },
+      description: "Show only followers not in your baseline file (client-side diffing; the X API does not support since_id here)"
+    }
+  ],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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
+    );
+    if (!c.options.newOnly) {
+      return c.ok({ users: allUsers, count: allUsers.length });
+    }
+    if (!c.options.seenIdsFile) {
+      throw new Error("--seen-ids-file is required when --new-only is set");
+    }
+    const seenIds = readSeenIds(c.options.seenIdsFile);
+    const newUsers = allUsers.filter((user) => !seenIds.has(user.id));
+    return c.ok({ users: newUsers, count: newUsers.length });
+  }
+});
+users.command("following", {
+  description: "List accounts a user is following.",
+  args: z7.object({
+    username: z7.string().describe("Username or user ID")
+  }),
+  options: z7.object({
+    maxResults: z7.number().default(100).describe("Maximum accounts to return")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
+      })
+    ),
+    count: z7.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "List accounts jack follows" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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: z7.object({
+    username: z7.string().describe("Username or user ID")
+  }),
+  options: z7.object({
+    maxResults: z7.number().default(10).describe("Maximum posts to return"),
+    verbose: z7.boolean().optional().describe("Show full text without truncation")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z7.object({
+    posts: z7.array(
+      z7.object({
+        id: z7.string(),
+        text: z7.string(),
+        created_at: z7.string().optional(),
+        likes: z7.number().optional(),
+        retweets: z7.number().optional()
+      })
+    ),
+    count: z7.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Get jack's recent posts" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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: z7.object({
+    username: z7.string().describe("Username or user ID")
+  }),
+  options: z7.object({
+    maxResults: z7.number().default(10).describe("Maximum mentions to return"),
+    verbose: z7.boolean().optional().describe("Show full text")
+  }),
+  alias: { maxResults: "n" },
+  env: xApiReadEnv,
+  output: z7.object({
+    posts: z7.array(
+      z7.object({
+        id: z7.string(),
+        text: z7.string(),
+        created_at: z7.string().optional()
+      })
+    ),
+    count: z7.number()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Get mentions of jack" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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: z7.object({
+    query: z7.string().describe("Search query")
+  }),
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
+      })
+    ),
+    count: z7.number()
+  }),
+  examples: [{ args: { query: "TypeScript" }, description: "Search for users about TypeScript" }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    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 },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        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 __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync2(resolve(__dirname, "../package.json"), "utf8"));
+var cli = Cli7.create("xapi", {
+  version: pkg.version,
+  description: "X (Twitter) API CLI for spectra-the-bot."
+});
+var WRITE_OPERATIONS = /* @__PURE__ */ new Set([
+  "posts create",
+  "posts delete",
+  "posts like",
+  "posts unlike",
+  "posts bookmark",
+  "posts unbookmark",
+  "posts retweet",
+  "users follow",
+  "users unfollow",
+  "users block",
+  "users unblock",
+  "users mute",
+  "users unmute",
+  "lists create",
+  "lists delete",
+  "lists add-member",
+  "lists remove-member",
+  "dm send"
+]);
+cli.use(async ({ command, error }, next) => {
+  try {
+    return await next();
+  } catch (cause) {
+    const authScope = WRITE_OPERATIONS.has(command) ? "write" : "read";
+    const mapped = toXApiCommandError(command, cause, authScope);
+    if (mapped) {
+      return error(mapped);
+    }
+    throw cause;
+  }
+});
+cli.command(posts);
+cli.command(users);
+cli.command(timeline);
+cli.command(lists);
+cli.command(trends);
+cli.command(dm);
+var isMain = (() => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+  try {
+    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  cli.serve();
+}
+export {
+  cli
+};