slack-term 1.14.0 → 1.16.0

package/ts/cli.ts

@@ -8,17 +8,20 @@ import { join } from "node:path";
 
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
-import { listProfiles, removeProfile, resolveCookie, resolveToken, useProfile } from "./profiles.ts";
-import { cmdAuthLogin } from "./auth.ts";
+import { listProfiles, removeProfile, resolveBotToken, resolveCookie, resolveToken, useProfile } from "./profiles.ts";
+import { diagnoseBotMessaging, formatDiagnosis } from "./botdoctor.ts";
+import { cmdAuthLogin, cmdAuthChrome, cmdAuthFirefox, cmdAuthToken, cmdAuthApp } from "./auth.ts";
 import { cmdTail } from "./tail.ts";
 
 import {
+  authTest,
   authTestSession,
   conversationInfoSession,
   createDraft,
   deleteDraft,
   updateDraft,
   editMessage,
+  deleteMessage,
   history,
   listConversations,
   listDrafts,
@@ -29,9 +32,11 @@ import {
   parseSlackPermalink,
   replies,
   resolveChannel,
+  resolveUserId,
   search,
   searchAll,
   send as slackSend,
+  getPermalink,
   scheduleMessage,
   listScheduledMessages,
   deleteScheduledMessage,
@@ -170,34 +175,65 @@ async function formatMsgLine(
   const lines = resolved.split("\n");
   const body = lines[0] + (lines.length > 1 ? "\n" + lines.slice(1).map(l => `  ${l}`).join("\n") : "");
   const who = chLabel ? `${chLabel}  @${handle}` : `@${handle}`;
-  return `${stamp}  ${who}:  ${body}`;
+  const reactions = asArray(m.reactions)
+    .map(asRecord)
+    .map((r) => {
+      const name = typeof r.name === "string" ? r.name : "";
+      const count = Number(r.count ?? asArray(r.users).length ?? 0);
+      return name ? `:${name}:×${count}` : "";
+    })
+    .filter(Boolean)
+    .join(" ");
+  const tail = reactions ? `\n   ${reactions}` : "";
+  return `${stamp}  ${who}:  ${body}${tail}`;
+}
+
+// Slim a raw message down to the fields a script actually needs. Keeps the
+// author's user ID (incl. external / Slack-Connect guests that never appear in
+// users.list) so callers can resolve mentions without scraping history by hand.
+function slimMsg(m: Record<string, Json>): Record<string, Json> {
+  return {
+    ts: m.ts ?? null,
+    user: m.user ?? null,
+    username: m.username ?? null,
+    bot_id: m.bot_id ?? null,
+    thread_ts: m.thread_ts ?? null,
+    text: typeof m.text === "string" ? m.text : "",
+  };
 }
 
 // --- msgs <target> — channel/DM history with timestamps ---
-async function cmdMsgsTarget(token: string, target: string, limit: number): Promise<void> {
+async function cmdMsgsTarget(token: string, target: string, limit: number, format: "text" | "jsonl" = "text"): Promise<void> {
   const parsed = parseSlackPermalink(target);
   const channelId = await resolveChannel(token, target);
   const cache = new Map<string, string>();
-  if (parsed?.threadTs) {
-    const resp = (await replies(token, channelId, parsed.threadTs, limit)) as Record<string, Json>;
-    const msgs = asArray(resp.messages).map(asRecord);
-    for (const m of msgs) {
-      console.log(await formatMsgLine(token, m, cache));
+  const fetchMsgs = async (): Promise<Record<string, Json>[]> => {
+    if (parsed?.threadTs) {
+      const resp = (await replies(token, channelId, parsed.threadTs, limit)) as Record<string, Json>;
+      return asArray(resp.messages).map(asRecord);
     }
-  } else {
     const hist = (await history(token, channelId, limit)) as Record<string, Json>;
-    const msgs = asArray(hist.messages).map(asRecord);
-    for (const m of msgs.reverse()) {
-      console.log(await formatMsgLine(token, m, cache));
-    }
+    return asArray(hist.messages).map(asRecord).reverse();
+  };
+  const msgs = await fetchMsgs();
+  if (format === "jsonl") {
+    for (const m of msgs) console.log(JSON.stringify(slimMsg(m)));
+    return;
+  }
+  for (const m of msgs) {
+    console.log(await formatMsgLine(token, m, cache));
   }
 }
 
 // --- thread ---
-async function cmdThread(token: string, target: string, ts: string, limit: number): Promise<void> {
+async function cmdThread(token: string, target: string, ts: string, limit: number, format: "text" | "jsonl" = "text"): Promise<void> {
   const channelId = await resolveChannel(token, target);
   const resp = (await replies(token, channelId, parseInputTs(ts), limit)) as Record<string, Json>;
   const msgs = asArray(resp.messages).map(asRecord);
+  if (format === "jsonl") {
+    for (const m of msgs) console.log(JSON.stringify(slimMsg(m)));
+    return;
+  }
   const cache = new Map<string, string>();
   for (const m of msgs) {
     console.log(await formatMsgLine(token, m, cache));
@@ -548,6 +584,69 @@ function splitRefTs(s: string): { ref: string; ts?: string } {
   return { ref: s };
 }
 
+/** Parse a send/upload target that may embed a thread_ts after `:`.
+ *  Accepts: `#chan:1700000000.000100`, `@user:ts`, `RAWID:ts`, Slack permalink, or plain ref.
+ *  A message permalink targets that message's thread — `?thread_ts=` (the parent) wins when
+ *  present, otherwise the message's own ts. A channel-only permalink stays top-level. */
+function parseTargetThread(s: string): { ref: string; threadTs?: string } {
+  const url = parseSlackPermalink(s);
+  if (url) {
+    const threadTs = url.threadTs ?? url.ts;
+    return threadTs ? { ref: url.channel, threadTs } : { ref: url.channel };
+  }
+  const colon = s.indexOf(":");
+  if (colon > 0) {
+    const maybeTs = s.slice(colon + 1);
+    if (/^\d{10}\.\d{6}$/.test(maybeTs)) return { ref: s.slice(0, colon), threadTs: maybeTs };
+    if (/^\d{4}-\d{2}-\d{2}T/.test(maybeTs)) return { ref: s.slice(0, colon), threadTs: isoToSlackTs(maybeTs) };
+  }
+  return { ref: s };
+}
+
+/** Human-readable destination label for confirm gates, e.g. "#symval (C0B0L6SSAMD)".
+ *  When ref is already a #channel/@user label, keep it; otherwise resolve the channel
+ *  name via conversations.info (fail-soft: a raw ID is still unambiguous). */
+async function destLabel(token: string, channelId: string, ref: string): Promise<string> {
+  let name = ref;
+  if (!ref.startsWith("#") && !ref.startsWith("@")) {
+    try {
+      const info = asRecord((await conversationInfo(token, channelId)) as Json);
+      const ch = asRecord(info.channel);
+      if (ch.is_im === true) {
+        const uid = typeof ch.user === "string" ? ch.user : "";
+        name = uid ? `@${await userName(token, uid)}` : channelId;
+      } else {
+        name = typeof ch.name === "string" ? `#${ch.name}` : channelId;
+      }
+    } catch {
+      name = channelId;
+    }
+  }
+  return name === channelId ? channelId : `${name} (${channelId})`;
+}
+
+/** One-line thread-parent description for confirm gates: "2026-06-11 08:05 @handle: head…".
+ *  Fail-soft: returns the raw ts if the parent cannot be fetched. */
+async function threadParentLine(token: string, channelId: string, threadTs: string): Promise<string> {
+  try {
+    const resp = (await replies(token, channelId, threadTs, 1)) as Record<string, Json>;
+    const msgs = asArray(resp.messages).map(asRecord);
+    const parent = msgs.find((m) => String(m.ts) === threadTs) ?? msgs[0];
+    if (!parent) return threadTs;
+    const author = typeof parent.user === "string"
+      ? await userName(token, parent.user)
+      : typeof parent.username === "string"
+      ? parent.username
+      : "?";
+    const head = (typeof parent.text === "string" ? parent.text : "").split("\n")[0] ?? "";
+    const headShort = head.length > 40 ? `${head.slice(0, 40)}…` : head;
+    const stamp = slackTsToIso(threadTs).slice(0, 16).replace("T", " ");
+    return `${stamp} @${author}${headShort ? `: ${headShort}` : ""}`;
+  } catch {
+    return threadTs;
+  }
+}
+
 // --- edit ---
 interface EditArgs {
   target: string;
@@ -591,48 +690,172 @@ async function cmdEdit(token: string, args: EditArgs): Promise<void> {
   console.log(`✓ Edited (ts: ${newTs})`);
 }
 
+// --- delete ---
+interface DeleteArgs {
+  target: string;
+  code?: string;
+  channelId?: string;
+}
+async function cmdDelete(token: string, args: DeleteArgs): Promise<void> {
+  const { ref, ts } = splitRefTs(args.target);
+  if (!ts) {
+    console.error("Error: target must embed a message ts (e.g. #chan:2026-05-11T06:01:04.000100 or a Slack permalink URL)");
+    process.exit(2);
+  }
+
+  let channelId: string;
+  if (args.channelId) channelId = args.channelId;
+  else channelId = await resolveChannel(token, ref);
+
+  // Fetch the message to display what is being deleted and compute the safety hash.
+  const resp = (await replies(token, channelId, ts, 1)) as Record<string, Json>;
+  const msgs = asArray(resp.messages).map(asRecord);
+  const original = msgs.find((m) => String(m.ts) === ts);
+  if (!original) {
+    console.error(`Message not found at ts=${ts} in channel ${channelId}`);
+    process.exit(1);
+  }
+  const originalText = typeof original.text === "string" ? original.text : "";
+
+  const code = safetyCode(channelId, ts, originalText);
+  if (args.code !== code) {
+    const dest = await destLabel(token, channelId, ref);
+    requireCode(args.code, code, [
+      `--- Deleting message -------------------------`,
+      `  → ${dest} at ${slackTsToIso(ts)}`,
+      ...originalText.split("\n").map((l) => `  ${l}`),
+      `---------------------------------------------`,
+    ]);
+  }
+
+  await deleteMessage(token, channelId, ts);
+  console.log(`✓ Deleted (ts: ${ts})`);
+}
+
 // --- send ---
 interface SendArgs {
   target: string;
   message: string;
-  thread?: string;
   code?: string;
   channelId?: string;
   userId?: string;
+  asBot?: boolean;
+  broadcast?: boolean;
+}
+
+// Detect the silent-failure footgun: DMing yourself with your own user token.
+// Slack does not notify you about messages you sent to yourself, so an
+// escalation DM via `send @me` (or @your-own-handle) is delivered but never
+// surfaces. Returns true when ref names the token's own user.
+async function isSelfDm(token: string, ref: string): Promise<boolean> {
+  if (!ref.startsWith("@")) return false;
+  const name = ref.slice(1).toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (name === "me" || name === "you") return true;
+  try {
+    const self = await authTest(token);
+    const selfName = (self.user ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+    return selfName !== "" && selfName === name;
+  } catch {
+    return false;
+  }
 }
+
 async function cmdSend(token: string, args: SendArgs): Promise<void> {
+  const { ref, threadTs } = parseTargetThread(args.target);
+
+  // Guard the self-DM footgun before doing anything else, unless sending as the
+  // bot (which delivers a notifiable DM from a different identity).
+  if (!args.asBot && !args.channelId && !args.userId && await isSelfDm(token, ref)) {
+    console.error(
+      `Warning: "${ref}" is a DM to yourself — Slack will NOT notify you of your own message.\n` +
+      `  To reach yourself with a notification, send as the bot:  slack send '${ref}' '...' --as-bot`,
+    );
+  }
+
   let channelId: string;
   if (args.channelId) channelId = args.channelId;
   else if (args.userId) channelId = await openDm(token, args.userId);
-  else if (args.target.startsWith("#") || args.target.startsWith("@")) {
-    channelId = await resolveChannel(token, args.target);
-  } else {
-    console.error(`Error: target must be #channel-name or @username (got: ${args.target})`);
-    console.error("Use --channel-id=<ID> or --user-id=<ID> to send by raw ID.");
-    process.exit(1);
-  }
+  else channelId = await resolveChannel(token, ref);
 
-  // Fetch last 1 message for context hash
-  const ctx = (await history(token, channelId, 1)) as Record<string, Json>;
-  const lastMsg = asArray(ctx.messages).map(asRecord)
-    .filter((m) => m.subtype === undefined || m.subtype === null)[0];
-  const lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
-  const lastUser = typeof lastMsg?.user === "string" ? lastMsg.user : "?";
+  // Fetch last 1 message for context hash. Fail-soft: a bot token without
+  // im:history (or channels:history) can still send — only the preview of the
+  // prior message is lost, so default to empty rather than blocking the send.
+  let lastText = "";
+  let lastUser = "?";
+  try {
+    const ctx = (await history(token, channelId, 1)) as Record<string, Json>;
+    const lastMsg = asArray(ctx.messages).map(asRecord)
+      .filter((m) => m.subtype === undefined || m.subtype === null)[0];
+    lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
+    // Resolve the author's user ID to a display name for the preview; fall back
+    // to the bot username, then the raw ID. userName() is fail-soft.
+    lastUser = typeof lastMsg?.user === "string"
+      ? await userName(token, lastMsg.user)
+      : typeof lastMsg?.username === "string"
+      ? lastMsg.username
+      : "?";
+  } catch {
+    // best-effort preview only
+  }
 
-  const code = safetyCode(lastText, args.message);
+  // Hash covers the destination too — a code minted for one channel/thread
+  // cannot confirm a send to another.
+  const code = safetyCode(channelId, threadTs ?? "", lastText, args.message);
 
   if (args.code !== code) {
+    const dest = await destLabel(token, channelId, ref);
+    const destLine = threadTs
+      ? `  → ${dest} thread of ${await threadParentLine(token, channelId, threadTs)} — THREAD REPLY`
+      : `  → ${dest} — NEW top-level message`;
     requireCode(args.code, code, [
       `--- Last message in channel ------------------`,
       `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
       `--- Sending ----------------------------------`,
-      `  To:      ${args.target}${args.thread ? ` (thread ${args.thread})` : ""}`,
+      destLine,
       `  Message: ${args.message}`,
       `--------------------------------────────────`,
     ]);
   }
-  const ts = await slackSend(token, channelId, args.message, args.thread);
-  console.log(`✓ Sent (ts: ${ts})`);
+  const ts = await slackSend(token, channelId, args.message, threadTs, args.broadcast);
+  let permalink = "";
+  try {
+    permalink = await getPermalink(token, channelId, ts);
+  } catch {
+    // fail-soft: getPermalink failure (rate limit, network, etc.) should not
+    // mask send success — fall back to ts-only output below.
+  }
+  if (permalink) {
+    console.log(`✓ Sent: ${permalink}`);
+  } else {
+    console.log(`✓ Sent (ts: ${ts})`);
+  }
+
+  // After a bot DM, check the app can actually carry a two-way conversation —
+  // an escalation the user can't reply to (Messages Tab off / missing scopes)
+  // is worse than useless. Non-fatal: the send already succeeded.
+  if (args.asBot && channelId.startsWith("D")) {
+    try {
+      const diag = await diagnoseBotMessaging(token);
+      if (!diag.ok) {
+        for (const line of formatDiagnosis(diag, true)) console.error(line);
+      } else {
+        // Scopes are fine, but the Messages Tab toggle isn't API-detectable.
+        const appUrl = diag.appId ? `https://api.slack.com/apps/${diag.appId}` : "https://api.slack.com/apps";
+        console.error(
+          `Note: if ${args.target} can't reply (app messaging may be off), ` +
+          `enable Messages Tab: ${appUrl} → App Home.`,
+        );
+      }
+    } catch {
+      // diagnosis is best-effort; never turn a successful send into a failure.
+    }
+  }
+}
+
+async function cmdDoctor(token: string): Promise<void> {
+  const diag = await diagnoseBotMessaging(token);
+  for (const line of formatDiagnosis(diag, false)) console.log(line);
+  if (!diag.ok) process.exit(1);
 }
 
 // --- schedule ---
@@ -647,21 +870,17 @@ interface ScheduleSendArgs {
   target: string;
   message: string;
   at: string;
-  thread?: string;
   code?: string;
   channelId?: string;
   userId?: string;
 }
 async function cmdScheduleSend(token: string, args: ScheduleSendArgs): Promise<void> {
+  const { ref, threadTs } = parseTargetThread(args.target);
+
   let channelId: string;
   if (args.channelId) channelId = args.channelId;
   else if (args.userId) channelId = await openDm(token, args.userId);
-  else if (args.target.startsWith("#") || args.target.startsWith("@")) {
-    channelId = await resolveChannel(token, args.target);
-  } else {
-    console.error(`Error: target must be #channel-name or @username (got: ${args.target})`);
-    process.exit(1);
-  }
+  else channelId = await resolveChannel(token, ref);
 
   const postAt = parsePostAt(args.at);
   const postAtDate = new Date(postAt * 1000).toISOString();
@@ -670,13 +889,13 @@ async function cmdScheduleSend(token: string, args: ScheduleSendArgs): Promise<v
   if (args.code !== code) {
     requireCode(args.code, code, [
       `--- Scheduling message -----------------------`,
-      `  To:      ${args.target}${args.thread ? ` (thread ${args.thread})` : ""}`,
+      `  To:      ${ref}${threadTs ? ` (thread ${threadTs})` : ""}`,
       `  At:      ${postAtDate} (Unix: ${postAt})`,
       `  Message: ${args.message}`,
       `---------------------------------------------`,
     ]);
   }
-  const id = await scheduleMessage(token, channelId, args.message, postAt, args.thread);
+  const id = await scheduleMessage(token, channelId, args.message, postAt, threadTs);
   console.log(`✓ Scheduled (id: ${id}, at: ${postAtDate})`);
 }
 
@@ -727,7 +946,6 @@ interface UploadArgs {
   target: string;
   filePaths: string[];
   title?: string;
-  thread?: string;
   comment?: string;
   code?: string;
   channelId?: string;
@@ -744,15 +962,12 @@ async function cmdUpload(token: string, args: UploadArgs): Promise<void> {
     }
   }
 
+  const { ref, threadTs } = parseTargetThread(args.target);
+
   let channelId: string;
   if (args.channelId) channelId = args.channelId;
   else if (args.userId) channelId = await openDm(token, args.userId);
-  else if (args.target.startsWith("#") || args.target.startsWith("@")) {
-    channelId = await resolveChannel(token, args.target);
-  } else {
-    console.error(`Error: target must be #channel-name or @username (got: ${args.target})`);
-    process.exit(1);
-  }
+  else channelId = await resolveChannel(token, ref);
 
   function fmtSize(n: number): string {
     return n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1048576).toFixed(1)} MB`;
@@ -768,7 +983,7 @@ async function cmdUpload(token: string, args: UploadArgs): Promise<void> {
   // Safety code covers the full batch — single-file code is identical to the old formula.
   const code = safetyCode(channelId, ...files.flatMap((f) => [f.fp, f.title]));
   if (args.code !== code) {
-    const destLine = `  To:    ${args.target}${args.thread ? ` (thread ${args.thread})` : ""}`;
+    const destLine = `  To:    ${ref}${threadTs ? ` (thread ${threadTs})` : ""}`;
     const lines = isBatch
       ? [
           `--- Uploading ${files.length} files ------------------------`,
@@ -791,7 +1006,7 @@ async function cmdUpload(token: string, args: UploadArgs): Promise<void> {
   for (let i = 0; i < total; i++) {
     const f = files[i]!;
     const uploadOpts: { title?: string; threadTs?: string; initialComment?: string } = { title: f.title };
-    if (args.thread !== undefined) uploadOpts.threadTs = args.thread;
+    if (threadTs !== undefined) uploadOpts.threadTs = threadTs;
     if (args.comment !== undefined && i === 0) uploadOpts.initialComment = args.comment;
     const { fileId, permalink } = await uploadFile(token, channelId, f.fp, uploadOpts);
     const prefix = total > 1 ? `[${i + 1}/${total}] ` : "";
@@ -831,10 +1046,13 @@ async function main(): Promise<void> {
       "Browse messages",
       (y) => y
         .positional("target", { type: "string", describe: "#channel, @user, or URL" })
-        .option("limit", { alias: "n", type: "number", default: 20, describe: "Number of messages" }),
+        .option("limit", { alias: "n", type: "number", default: 20, describe: "Number of messages" })
+        .option("format", { type: "string", choices: ["text", "jsonl"] as const, default: "text", describe: "jsonl exposes raw ts/user/text (incl. external-guest user IDs)" })
+        .option("json", { type: "boolean", default: false, describe: "Alias for --format=jsonl" }),
       async (argv) => {
         const token = tok(argv as W);
-        if (argv.target) await cmdMsgsTarget(token, argv.target, argv.limit);
+        const format = argv.json ? "jsonl" : (argv.format as "text" | "jsonl");
+        if (argv.target) await cmdMsgsTarget(token, argv.target, argv.limit, format);
         else await cmdMsgs(token);
       },
     )
@@ -844,9 +1062,12 @@ async function main(): Promise<void> {
       (y) => y
         .positional("target", { type: "string", demandOption: true })
         .positional("ts", { type: "string", demandOption: true })
-        .option("limit", { alias: "n", type: "number", default: 100 }),
+        .option("limit", { alias: "n", type: "number", default: 100 })
+        .option("format", { type: "string", choices: ["text", "jsonl"] as const, default: "text", describe: "jsonl exposes raw ts/user/text (incl. external-guest user IDs)" })
+        .option("json", { type: "boolean", default: false, describe: "Alias for --format=jsonl" }),
       async (argv) => {
-        await cmdThread(tok(argv as W), argv.target!, argv.ts!, argv.limit);
+        const format = argv.json ? "jsonl" : (argv.format as "text" | "jsonl");
+        await cmdThread(tok(argv as W), argv.target!, argv.ts!, argv.limit, format);
       },
     )
     .command(
@@ -1019,19 +1240,75 @@ async function main(): Promise<void> {
       "send <target> <message>",
       "Send a message (confirm-hash safety gate)",
       (y) => y
-        .positional("target", { type: "string", demandOption: true })
+        .positional("target", { type: "string", demandOption: true, describe: "#chan, @user, #chan:thread_ts, or permalink (a message permalink replies in its thread)" })
         .positional("message", { type: "string", demandOption: true })
-        .option("thread", { type: "string", describe: "Thread timestamp" })
         .option("code", { type: "string", describe: "Safety hash to confirm send" })
         .option("channel-id", { type: "string", describe: "Raw channel ID" })
-        .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" }),
+        .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" })
+        .option("as-bot", { type: "boolean", default: false, describe: "Send via the bot token (xoxb / SLACK_BOT_TOKEN) so a DM notifies the recipient and can be two-way" })
+        .option("broadcast", { type: "boolean", default: false, describe: "Also send to channel: broadcast a threaded reply back to the channel (Slack's \"Also send to #channel\" checkbox). Only effective with a thread target." }),
       async (argv) => {
         const args: SendArgs = { target: argv.target!, message: argv.message! };
-        if (argv.thread) args.thread = argv.thread;
         if (argv.code) args.code = argv.code;
         if (argv["channel-id"]) args.channelId = argv["channel-id"];
         if (argv["user-id"]) args.userId = argv["user-id"];
-        await cmdSend(tok(argv as W), args);
+        if (argv.broadcast) args.broadcast = true;
+        let sendToken: string;
+        if (argv["as-bot"]) {
+          const botToken = resolveBotToken();
+          if (!botToken) {
+            console.error(
+              "Error: --as-bot needs a bot token, but no xoxb- token was found.\n" +
+              "  Set SLACK_BOT_TOKEN=xoxb-... in ~/.config/slack-cli/.env (or your shell).",
+            );
+            process.exit(1);
+          }
+          // Resolve @user → user_id with the *user* token (has users:read), then
+          // let cmdSend open the DM with the bot token (im:write). This avoids
+          // requiring users:read on the bot and guarantees the DM is bot↔user
+          // (not the user's own self-DM).
+          if (!args.channelId && !args.userId && args.target.startsWith("@")) {
+            try {
+              args.userId = await resolveUserId(tok(argv as W), args.target);
+            } catch (e: unknown) {
+              console.error(
+                `Error: could not resolve ${args.target} to a user for the bot DM.\n` +
+                `  ${e instanceof Error ? e.message : String(e)}\n` +
+                `  Tip: pass --user-id <Uxxxx> to skip the lookup.`,
+              );
+              process.exit(1);
+            }
+          }
+          sendToken = botToken;
+          args.asBot = true;
+        } else {
+          sendToken = tok(argv as W);
+        }
+        // Print a clean error instead of yargs' usage dump when a send fails at
+        // runtime (e.g. missing scope, channel not found). The confirm gate
+        // exits via process.exit, so it is unaffected.
+        try {
+          await cmdSend(sendToken, args);
+        } catch (e: unknown) {
+          console.error(e instanceof Error ? e.message : String(e));
+          process.exit(1);
+        }
+      },
+    )
+    .command(
+      "doctor",
+      "Check the bot token (xoxb) can carry a two-way DM (scopes + Messages Tab)",
+      (y) => y,
+      async () => {
+        const botToken = resolveBotToken();
+        if (!botToken) {
+          console.error(
+            "Error: slack doctor checks the bot token, but no xoxb- token was found.\n" +
+            "  Set SLACK_BOT_TOKEN=xoxb-... in ~/.config/slack-cli/.env (or your shell).",
+          );
+          process.exit(1);
+        }
+        await cmdDoctor(botToken);
       },
     )
     .command(
@@ -1042,16 +1319,14 @@ async function main(): Promise<void> {
           "send <target> <message>",
           "Schedule a message for later delivery",
           (y2) => y2
-            .positional("target", { type: "string", demandOption: true })
+            .positional("target", { type: "string", demandOption: true, describe: "#chan, @user, #chan:thread_ts, or permalink (a message permalink replies in its thread)" })
             .positional("message", { type: "string", demandOption: true })
             .option("at", { type: "string", demandOption: true, describe: "Delivery time (ISO datetime or Unix ts)" })
-            .option("thread", { type: "string", describe: "Thread timestamp" })
             .option("code", { type: "string", describe: "Safety hash to confirm" })
             .option("channel-id", { type: "string", describe: "Raw channel ID" })
             .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" }),
           async (argv) => {
             const args: ScheduleSendArgs = { target: argv.target!, message: argv.message!, at: argv.at! };
-            if (argv.thread) args.thread = argv.thread;
             if (argv.code) args.code = argv.code;
             if (argv["channel-id"]) args.channelId = argv["channel-id"];
             if (argv["user-id"]) args.userId = argv["user-id"];
@@ -1102,14 +1377,27 @@ async function main(): Promise<void> {
         await cmdEdit(tok(argv as W), args);
       },
     )
+    .command(
+      "delete <target>",
+      "Delete a sent message (confirm-hash safety gate)",
+      (y) => y
+        .positional("target", { type: "string", demandOption: true, describe: "#chan:ts, @user:ts, or permalink" })
+        .option("code", { type: "string", describe: "Safety hash to confirm delete" })
+        .option("channel-id", { type: "string", describe: "Raw channel ID" }),
+      async (argv) => {
+        const args: DeleteArgs = { target: argv.target! };
+        if (argv.code) args.code = argv.code;
+        if (argv["channel-id"]) args.channelId = argv["channel-id"];
+        await cmdDelete(tok(argv as W), args);
+      },
+    )
     .command(
       "upload <target> <file..>",
       "Upload one or more files to a channel or DM",
       (y) => y
-        .positional("target", { type: "string", demandOption: true })
+        .positional("target", { type: "string", demandOption: true, describe: "#chan, @user, #chan:thread_ts, or permalink (a message permalink replies in its thread)" })
         .positional("file", { type: "string", array: true, demandOption: true, describe: "Path(s) to file(s)" })
         .option("title", { type: "string", describe: "Title (single file only)" })
-        .option("thread", { type: "string", describe: "Thread timestamp" })
         .option("comment", { type: "string", describe: "Initial comment (first file)" })
         .option("code", { type: "string", describe: "4-hex safety code to confirm upload" })
         .option("channel-id", { type: "string" })
@@ -1117,7 +1405,6 @@ async function main(): Promise<void> {
       async (argv) => {
         const args: UploadArgs = { target: argv.target!, filePaths: argv.file as string[] };
         if (argv.title) args.title = argv.title;
-        if (argv.thread) args.thread = argv.thread;
         if (argv.comment) args.comment = argv.comment;
         if (argv.code) args.code = argv.code;
         if (argv["channel-id"]) args.channelId = argv["channel-id"];
@@ -1226,9 +1513,30 @@ async function main(): Promise<void> {
       "auth",
       "Authentication and workspace management",
       (y) => y
+        .command(
+          "token",
+          "Add a workspace — paste an existing xoxp-/xoxb- token",
+          (y2) => y2
+            .option("token", { type: "string", describe: "Token to save directly (non-interactive)" })
+            .option("name", { type: "string", describe: "Workspace name (used with --token)" }),
+          async (argv) => {
+            await cmdAuthToken({
+              ...(argv.token !== undefined ? { token: argv.token } : {}),
+              ...(argv.name !== undefined ? { name: argv.name } : {}),
+            });
+          },
+        )
+        .command(
+          "app",
+          "Create a new Slack app and obtain a token (guided wizard)",
+          (y2) => y2.option("bot", { type: "boolean", describe: "Create a bot token (xoxb-) instead of user (xoxp-)" }),
+          async (argv) => {
+            await cmdAuthApp({ ...(argv.bot !== undefined ? { bot: argv.bot } : {}) });
+          },
+        )
         .command(
           "login",
-          "Add a workspace (interactive or --token for non-interactive)",
+          "Interactive auth wizard (all auth methods: desktop app, token, new app)",
           (y2) => y2
             .option("token", { type: "string", describe: "Token to save directly (non-interactive)" })
             .option("name", { type: "string", describe: "Workspace name (used with --token)" }),
@@ -1258,7 +1566,7 @@ async function main(): Promise<void> {
           },
         )
         .command(
-          ["rm <name>", "remove <name>"],
+          ["logout <name>", "rm <name>", "remove <name>"],
           "Remove a workspace",
           (y2) => y2.positional("name", { type: "string", demandOption: true }),
           (argv) => {
@@ -1266,6 +1574,24 @@ async function main(): Promise<void> {
             console.log(`Removed workspace "${argv.name}"`);
           },
         )
+        .command(
+          ["chrome", "cookie"],
+          "Attach Chrome browser xoxd cookie to a workspace (macOS, interactive)",
+          (y2) => y2
+            .option("workspace", { type: "string", alias: "w", describe: "Workspace name to update (default: active)" }),
+          async (argv) => {
+            await cmdAuthChrome({ ...(argv.workspace !== undefined ? { workspace: argv.workspace } : {}) });
+          },
+        )
+        .command(
+          "firefox",
+          "Attach Firefox browser xoxd cookie to a workspace (all platforms)",
+          (y2) => y2
+            .option("workspace", { type: "string", alias: "w", describe: "Workspace name to update (default: active)" }),
+          async (argv) => {
+            await cmdAuthFirefox({ ...(argv.workspace !== undefined ? { workspace: argv.workspace } : {}) });
+          },
+        )
         .command("$0", false as unknown as string, () => {}, () => { y.showHelp(); process.exit(0); }),
     )
     .command(
@@ -1275,8 +1601,11 @@ async function main(): Promise<void> {
         .positional("target", { type: "string", describe: "#channel or @user to follow" })
         .option("since", { type: "string", describe: "Backfill from N ago (e.g. 10m, 2h, 1d)" })
         .option("thread", { type: "string", describe: "Follow a single thread by timestamp" })
+        .option("watch-thread", { type: "string", describe: "Watch the channel's top-level timeline AND one thread's replies together (ts or permalink)" })
         .option("me", { type: "boolean", default: false, describe: "Filter to messages that mention you" })
         .option("interval", { type: "number", default: 60000, describe: "Poll interval in ms (default 60s; use --interval=3000 for near-real-time)" })
+        .option("timeout", { type: "string", describe: "Auto-stop after this long (e.g. 30m, 2h). Exit code 0 even if nothing arrived." })
+        .option("exit-on-message", { type: "boolean", default: false, describe: "Stop as soon as the first new message from someone else arrives (wait-for-reply)" })
         .option("rtm", { type: "boolean", default: true, describe: "Use RTM WebSocket when available (xoxc + cookie); pass --no-rtm to force polling" }),
       async (argv) => {
         const token = tok(argv as W);
@@ -1286,8 +1615,11 @@ async function main(): Promise<void> {
         await cmdTail(token, argv.target, {
           ...(argv.since !== undefined ? { since: argv.since } : {}),
           ...(argv.thread !== undefined ? { thread: argv.thread } : {}),
+          ...(argv["watch-thread"] !== undefined ? { watchThread: argv["watch-thread"] as string } : {}),
           me: argv.me,
           interval: argv.interval,
+          ...(argv.timeout !== undefined ? { timeout: argv.timeout } : {}),
+          ...(argv["exit-on-message"] === true ? { exitOnMessage: true } : {}),
           ...(cookie !== undefined ? { cookie } : {}),
           ...(argv.rtm === false ? { noRtm: true } : {}),
         }, signal.signal);