@spectratools/xapi-cli 0.1.1 → 0.1.2

package/README.md

@@ -1,74 +1,79 @@
-# @spectra-the-bot/xapi-cli
+# @spectratools/xapi-cli
 
-X (Twitter) API v2 CLI for spectra-the-bot, built with [incur](https://github.com/wevm/incur).
+X (Twitter) API v2 CLI for post, user, list, trend, timeline, and DM workflows.
 
-## Setup
+## Install
 
 ```bash
-export X_BEARER_TOKEN=your_bearer_token_here
-npx @spectra-the-bot/xapi-cli --help
+pnpm add -g @spectratools/xapi-cli
 ```
 
-## Commands
-
-### Posts
+## LLM / Agent Discovery
 
 ```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>
-```
+# Emit machine-readable command metadata
+xapi-cli --llms
 
-### Users
+# Register as a reusable local skill for agent runtimes
+xapi-cli skills add
 
-```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>
+# Register as an MCP server entry
+xapi-cli mcp add
 ```
 
-### Timeline
+## Configuration
 
 ```bash
-xapi timeline home [-n 25]
-xapi timeline mentions [-n 25]
-```
-
-### Lists
+# Read-only endpoints (search, profiles, trends, list reads)
+export X_BEARER_TOKEN=your_app_bearer_token
 
-```bash
-xapi lists get <id>
-xapi lists members <id>
-xapi lists posts <id> [-n 25]
+# Write endpoints (create/delete post, send DM)
+# OAuth 2.0 user context token with the required write scopes
+export X_ACCESS_TOKEN=your_oauth2_user_access_token
 ```
 
-### Trends
+Auth behavior:
+- Reads use `X_ACCESS_TOKEN` when present, otherwise fall back to `X_BEARER_TOKEN`.
+- Writes require `X_ACCESS_TOKEN` and will return a structured auth error if missing/insufficient.
 
-```bash
-xapi trends places
-xapi trends location <woeid>
-```
+## Command Group Intent Summary
+
+- `posts` — Read/search/create/delete posts and inspect social engagement
+- `users` — Profile lookup, social graph traversal, and user timelines
+- `timeline` — Home timeline and mention stream monitoring
+- `lists` — List discovery, member inspection, and list feed reads
+- `trends` — Trend place discovery and per-location trend fetch
+- `dm` — Conversation listing and outbound direct messages
 
-### DMs
+## Agent-Oriented Examples
 
 ```bash
-xapi dm conversations [-n 20]
-xapi dm send <participant-id> --text "Hello!"
+# 1) Trend-to-content pipeline
+xapi-cli trends places --format json
+xapi-cli trends location 1 --format json
+xapi-cli posts search "AI agents" --sort relevancy --max-results 20 --format json
+
+# 2) User intelligence pass
+xapi-cli users get jack --format json
+xapi-cli users posts jack --max-results 20 --format json
+xapi-cli users followers jack --max-results 100 --format json
+
+# 3) Moderation helper flow
+xapi-cli posts get 1234567890 --format json
+xapi-cli posts likes 1234567890 --max-results 100 --format json
+xapi-cli posts retweets 1234567890 --max-results 100 --format json
+
+# 4) Timeline monitor
+xapi-cli timeline home --max-results 50 --format json
+xapi-cli timeline mentions --max-results 50 --format json
+
+# 5) DM assistant loop
+xapi-cli dm conversations --max-results 20 --format json
+xapi-cli dm send 12345 --text "hello from agent" --format json
 ```
 
-## Common Options
-
-- `--verbose` — Show full text without truncation
-- `-n, --max-results` — Control result count
-- `--format json` — JSON output
-- `--help` — Show help
-
-## Auth
+## Notes
 
-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.
+- All commands support JSON output with `--format json`.
+- `X_BEARER_TOKEN` is for read-only app auth.
+- `X_ACCESS_TOKEN` is required for write actions (`posts create`, `posts delete`, `dm send`).

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { realpathSync } from "fs";
 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";
+import { Cli, z as z2 } from "incur";
 
 // src/api.ts
 import { createHttpClient, withRetry } from "@spectratools/cli-shared";
@@ -214,6 +214,66 @@ function truncateText(text, max = 100) {
   return `${text.slice(0, max - 3)}...`;
 }
 
+// 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 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;
+}
+
 // src/collect-paged.ts
 import { paginateCursor } from "@spectratools/cli-shared";
 async function collectPaged(fetchFn, mapFn, maxResults, pageSize = 100) {
@@ -242,23 +302,23 @@ var dm = Cli.create("dm", {
 });
 dm.command("conversations", {
   description: "List your DM conversations.",
-  options: z.object({
-    maxResults: z.number().default(20).describe("Maximum conversations to return")
+  options: z2.object({
+    maxResults: z2.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())
+  env: xApiReadEnv,
+  output: z2.object({
+    conversations: z2.array(
+      z2.object({
+        dm_conversation_id: z2.string(),
+        participant_ids: z2.array(z2.string())
       })
     ),
-    count: z.number()
+    count: z2.number()
   }),
   examples: [{ description: "List your DM conversations" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const meRes = await client.getMe();
     const userId = meRes.data.id;
     const allConvos = await collectPaged(
@@ -290,15 +350,16 @@ dm.command("conversations", {
 });
 dm.command("send", {
   description: "Send a direct message to a user.",
-  args: z.object({
-    participantId: z.string().describe("User ID to send message to")
+  args: z2.object({
+    participantId: z2.string().describe("User ID to send message to")
   }),
-  options: z.object({
-    text: z.string().describe("Message text")
+  options: z2.object({
+    text: z2.string().describe("Message text")
   }),
-  output: z.object({
-    dm_conversation_id: z.string(),
-    dm_event_id: z.string()
+  env: xApiWriteEnv,
+  output: z2.object({
+    dm_conversation_id: z2.string(),
+    dm_event_id: z2.string()
   }),
   examples: [
     {
@@ -308,35 +369,39 @@ dm.command("send", {
     }
   ],
   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);
+    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 { apiKeyAuth as apiKeyAuth2 } from "@spectratools/cli-shared";
-import { Cli as Cli2, z as z2 } from "incur";
+import { Cli as Cli2, z as z3 } 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")
+  args: z3.object({
+    id: z3.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()
+  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 { apiKey } = apiKeyAuth2("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const res = await client.getList(c.args.id);
     const list = res.data;
     return c.ok(
@@ -361,28 +426,28 @@ lists.command("get", {
 });
 lists.command("members", {
   description: "List members of an X list.",
-  args: z2.object({
-    id: z2.string().describe("List ID")
+  args: z3.object({
+    id: z3.string().describe("List ID")
   }),
-  options: z2.object({
-    maxResults: z2.number().default(100).describe("Maximum members to return")
+  options: z3.object({
+    maxResults: z3.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()
+  env: xApiReadEnv,
+  output: z3.object({
+    users: z3.array(
+      z3.object({
+        id: z3.string(),
+        name: z3.string(),
+        username: z3.string(),
+        followers: z3.number().optional()
       })
     ),
-    count: z2.number()
+    count: z3.number()
   }),
   examples: [{ args: { id: "1234567890" }, description: "List all members" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth2("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const allUsers = await collectPaged(
       (limit, cursor) => client.getListMembers(c.args.id, limit, cursor),
       (user) => ({
@@ -398,30 +463,30 @@ lists.command("members", {
 });
 lists.command("posts", {
   description: "Get posts from an X list.",
-  args: z2.object({
-    id: z2.string().describe("List ID")
+  args: z3.object({
+    id: z3.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")
+  options: z3.object({
+    maxResults: z3.number().default(25).describe("Maximum posts to return"),
+    verbose: z3.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()
+  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: z2.number()
+    count: z3.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 client = createXApiClient(readAuthToken(c.env));
     const allPosts = await collectPaged(
       (limit, cursor) => client.getListPosts(c.args.id, limit, cursor),
       (post) => ({
@@ -453,32 +518,31 @@ lists.command("posts", {
 });
 
 // src/commands/posts.ts
-import { apiKeyAuth as apiKeyAuth3 } from "@spectratools/cli-shared";
-import { Cli as Cli3, z as z3 } from "incur";
+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: z3.object({
-    id: z3.string().describe("Post ID")
+  args: z4.object({
+    id: z4.string().describe("Post ID")
   }),
-  options: z3.object({
-    verbose: z3.boolean().optional().describe("Show full text without truncation")
+  options: z4.object({
+    verbose: z4.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()
+  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 { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    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);
@@ -514,26 +578,27 @@ posts.command("get", {
 });
 posts.command("search", {
   description: "Search recent posts.",
-  args: z3.object({
-    query: z3.string().describe("Search query")
+  args: z4.object({
+    query: z4.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")
+  options: z4.object({
+    maxResults: z4.number().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" },
-  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()
+  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: z3.number()
+    count: z4.number()
   }),
   examples: [
     { args: { query: "TypeScript" }, description: "Search for TypeScript posts" },
@@ -544,8 +609,7 @@ posts.command("search", {
     }
   ],
   async run(c) {
-    const { apiKey } = apiKeyAuth3("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    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,
@@ -574,74 +638,90 @@ posts.command("search", {
 });
 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")
+  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")
   }),
-  output: z3.object({
-    id: z3.string(),
-    text: z3.string()
+  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) {
-    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" }
-        ]
-      }
-    });
+    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, {
+        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: z3.object({
-    id: z3.string().describe("Post ID to delete")
+  args: z4.object({
+    id: z4.string().describe("Post ID to delete")
   }),
-  output: z3.object({
-    deleted: z3.boolean(),
-    id: z3.string()
+  env: xApiWriteEnv,
+  output: z4.object({
+    deleted: z4.boolean(),
+    id: z4.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 });
+    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("likes", {
   description: "List users who liked a post.",
-  args: z3.object({
-    id: z3.string().describe("Post ID")
+  args: z4.object({
+    id: z4.string().describe("Post ID")
   }),
-  options: z3.object({
-    maxResults: z3.number().default(100).describe("Maximum users to return")
+  options: z4.object({
+    maxResults: z4.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()
+  env: xApiReadEnv,
+  output: z4.object({
+    users: z4.array(
+      z4.object({
+        id: z4.string(),
+        name: z4.string(),
+        username: z4.string(),
+        followers: z4.number().optional()
       })
     ),
-    count: z3.number()
+    count: z4.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 client = createXApiClient(readAuthToken(c.env));
     const allUsers = await collectPaged(
       (limit, cursor) => client.getPostLikes(c.args.id, limit, cursor),
       (user) => ({
@@ -669,28 +749,28 @@ posts.command("likes", {
 });
 posts.command("retweets", {
   description: "List users who retweeted a post.",
-  args: z3.object({
-    id: z3.string().describe("Post ID")
+  args: z4.object({
+    id: z4.string().describe("Post ID")
   }),
-  options: z3.object({
-    maxResults: z3.number().default(100).describe("Maximum users to return")
+  options: z4.object({
+    maxResults: z4.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()
+  env: xApiReadEnv,
+  output: z4.object({
+    users: z4.array(
+      z4.object({
+        id: z4.string(),
+        name: z4.string(),
+        username: z4.string(),
+        followers: z4.number().optional()
       })
     ),
-    count: z3.number()
+    count: z4.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 client = createXApiClient(readAuthToken(c.env));
     const allUsers = await collectPaged(
       (limit, cursor) => client.getPostRetweets(c.args.id, limit, cursor),
       (user) => ({
@@ -706,38 +786,37 @@ posts.command("retweets", {
 });
 
 // src/commands/timeline.ts
-import { apiKeyAuth as apiKeyAuth4 } from "@spectratools/cli-shared";
-import { Cli as Cli4, z as z4 } from "incur";
+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: z4.object({
-    maxResults: z4.number().default(25).describe("Maximum posts to return (5\u2013100)"),
-    verbose: z4.boolean().optional().describe("Show full text without truncation")
+  options: z5.object({
+    maxResults: z5.number().default(25).describe("Maximum posts to return (5\u2013100)"),
+    verbose: z5.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()
+  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: z4.number()
+    count: z5.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 client = createXApiClient(readAuthToken(c.env));
     const meRes = await client.getMe();
     const userId = meRes.data.id;
     const allPosts = await collectPaged(
@@ -772,26 +851,26 @@ timeline.command("home", {
 });
 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")
+  options: z5.object({
+    maxResults: z5.number().default(25).describe("Maximum mentions to return"),
+    verbose: z5.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()
+  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: z4.number()
+    count: z5.number()
   }),
   examples: [{ description: "View your recent mentions" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth4("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const meRes = await client.getMe();
     const userId = meRes.data.id;
     const allPosts = await collectPaged(
@@ -809,27 +888,26 @@ timeline.command("mentions", {
 });
 
 // src/commands/trends.ts
-import { apiKeyAuth as apiKeyAuth5 } from "@spectratools/cli-shared";
-import { Cli as Cli5, z as z5 } from "incur";
+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.",
-  output: z5.object({
-    places: z5.array(
-      z5.object({
-        woeid: z5.number(),
-        name: z5.string(),
-        country: z5.string()
+  env: xApiReadEnv,
+  output: z6.object({
+    places: z6.array(
+      z6.object({
+        woeid: z6.number(),
+        name: z6.string(),
+        country: z6.string()
       })
     ),
-    count: z5.number()
+    count: z6.number()
   }),
   examples: [{ description: "List all trending places" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth5("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const res = await client.getTrendingPlaces();
     const places = res.data ?? [];
     const first = places[0];
@@ -852,26 +930,26 @@ trends.command("places", {
 });
 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)")
+  args: z6.object({
+    woeid: z6.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()
+  env: xApiReadEnv,
+  output: z6.object({
+    trends: z6.array(
+      z6.object({
+        name: z6.string(),
+        query: z6.string(),
+        tweet_volume: z6.number().optional()
       })
     ),
-    count: z5.number()
+    count: z6.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 client = createXApiClient(readAuthToken(c.env));
     const res = await client.getTrendsByLocation(Number(c.args.woeid));
     const trendItems = res.data ?? [];
     const firstTrend = trendItems[0];
@@ -894,8 +972,7 @@ trends.command("location", {
 });
 
 // src/commands/users.ts
-import { apiKeyAuth as apiKeyAuth6 } from "@spectratools/cli-shared";
-import { Cli as Cli6, z as z6 } from "incur";
+import { Cli as Cli6, z as z7 } from "incur";
 var users = Cli6.create("users", {
   description: "Look up X users."
 });
@@ -907,29 +984,29 @@ async function resolveUser(client, usernameOrId) {
 }
 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")
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
   }),
-  options: z6.object({
-    verbose: z6.boolean().optional().describe("Show full bio without truncation")
+  options: z7.object({
+    verbose: z7.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()
+  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 { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const res = await resolveUser(client, c.args.username);
     const user = res.data;
     return c.ok(
@@ -965,28 +1042,28 @@ users.command("get", {
 });
 users.command("followers", {
   description: "List followers of a user.",
-  args: z6.object({
-    username: z6.string().describe("Username or user ID")
+  args: z7.object({
+    username: z7.string().describe("Username or user ID")
   }),
-  options: z6.object({
-    maxResults: z6.number().default(100).describe("Maximum followers to return")
+  options: z7.object({
+    maxResults: z7.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()
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
       })
     ),
-    count: z6.number()
+    count: z7.number()
   }),
   examples: [{ args: { username: "jack" }, description: "List followers of jack" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const userRes = await resolveUser(client, c.args.username);
     const userId = userRes.data.id;
     const allUsers = await collectPaged(
@@ -1005,28 +1082,28 @@ users.command("followers", {
 });
 users.command("following", {
   description: "List accounts a user is following.",
-  args: z6.object({
-    username: z6.string().describe("Username or user ID")
+  args: z7.object({
+    username: z7.string().describe("Username or user ID")
   }),
-  options: z6.object({
-    maxResults: z6.number().default(100).describe("Maximum accounts to return")
+  options: z7.object({
+    maxResults: z7.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()
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
       })
     ),
-    count: z6.number()
+    count: z7.number()
   }),
   examples: [{ args: { username: "jack" }, description: "List accounts jack follows" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const userRes = await resolveUser(client, c.args.username);
     const userId = userRes.data.id;
     const allUsers = await collectPaged(
@@ -1045,30 +1122,30 @@ users.command("following", {
 });
 users.command("posts", {
   description: "List a user's posts.",
-  args: z6.object({
-    username: z6.string().describe("Username or user ID")
+  args: z7.object({
+    username: z7.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")
+  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" },
-  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()
+  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: z6.number()
+    count: z7.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 client = createXApiClient(readAuthToken(c.env));
     const userRes = await resolveUser(client, c.args.username);
     const userId = userRes.data.id;
     const allPosts = await collectPaged(
@@ -1102,28 +1179,28 @@ users.command("posts", {
 });
 users.command("mentions", {
   description: "List recent mentions of a user.",
-  args: z6.object({
-    username: z6.string().describe("Username or user ID")
+  args: z7.object({
+    username: z7.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")
+  options: z7.object({
+    maxResults: z7.number().default(10).describe("Maximum mentions to return"),
+    verbose: z7.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()
+  env: xApiReadEnv,
+  output: z7.object({
+    posts: z7.array(
+      z7.object({
+        id: z7.string(),
+        text: z7.string(),
+        created_at: z7.string().optional()
       })
     ),
-    count: z6.number()
+    count: z7.number()
   }),
   examples: [{ args: { username: "jack" }, description: "Get mentions of jack" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("X_BEARER_TOKEN");
-    const client = createXApiClient(apiKey);
+    const client = createXApiClient(readAuthToken(c.env));
     const userRes = await resolveUser(client, c.args.username);
     const userId = userRes.data.id;
     const allPosts = await collectPaged(
@@ -1140,24 +1217,24 @@ users.command("mentions", {
 });
 users.command("search", {
   description: "Search for users by keyword.",
-  args: z6.object({
-    query: z6.string().describe("Search query")
+  args: z7.object({
+    query: z7.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()
+  env: xApiReadEnv,
+  output: z7.object({
+    users: z7.array(
+      z7.object({
+        id: z7.string(),
+        name: z7.string(),
+        username: z7.string(),
+        followers: z7.number().optional()
       })
     ),
-    count: z6.number()
+    count: z7.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 client = createXApiClient(readAuthToken(c.env));
     const res = await client.searchUsers(c.args.query);
     const items = (res.data ?? []).map((u) => ({
       id: u.id,
@@ -1194,7 +1271,18 @@ cli.command(timeline);
 cli.command(lists);
 cli.command(trends);
 cli.command(dm);
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/xapi-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "X (Twitter) API CLI for spectra-the-bot",
   "type": "module",
   "license": "MIT",