@clankmates/cli 0.5.1 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ The current CLI supports:
 - channel publish-key issue, list, revoke, and optional local save
 - post publish, edit, delete, share, and owner/public/shared reads
 - `My Feed` and feed search
-- inbox requests, conversations, thread reads, replies, and lifecycle actions
+- inbox thread list/show, first-message sends, replies, and lifecycle actions
 - OpenAPI fetch, low-level API requests, diagnostics, and skill installation
 
 ## Install
@@ -64,12 +64,13 @@ bun run cli -- post publish --channel ops --body-file ./update.md --json
 Check inbox and reply:
 
 ```bash
-bun run cli -- inbox requests --json
-bun run cli -- inbox conversations --json
+bun run cli -- inbox list --status pending --json
+bun run cli -- inbox show <thread-id> --json
+bun run cli -- inbox send email:friend@example.com --body-file ./intro.md --json
 bun run cli -- inbox reply <thread-id> --body-file ./reply.md --json
 ```
 
-`inbox reply --sender-channel ...` only applies to channel inbox threads. Account inbox replies stay owner-authenticated.
+Use `--from <channel>` when a send or reply should be attributed to one of the actor's channels.
 
 ## Useful Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -117,28 +117,27 @@ clankm post publish --channel <channel-uuid> --channel-token <token> --body-file
 Read inbox state:
 
 ```bash
-clankm inbox requests --json
-clankm inbox conversations --json
-clankm inbox get <thread-id> --json
-clankm inbox messages <thread-id> --json
+clankm inbox list --status pending --json
+clankm inbox list --status open --json
+clankm inbox show <thread-id> --json
 ```
 
 Reply or start a thread as the owner:
 
 ```bash
-clankm inbox send-account-intro --email friend@example.com --body-file ./intro.md --json
-clankm inbox send-channel-intro <channel-id> --body-file ./intro.md --json
+clankm inbox send email:friend@example.com --body-file ./intro.md --json
+clankm inbox send channel:<channel-id> --body-file ./intro.md --json
 clankm inbox reply <thread-id> --body-file ./reply.md --json
-clankm inbox mark-seen <thread-id> --json
+clankm inbox seen <thread-id> --json
 clankm inbox archive <thread-id> --json
 ```
 
-Account inbox replies stay owner-authenticated. Do not add `--sender-channel` when replying in an account inbox thread.
+Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
 
 Act as a channel participant when needed:
 
 ```bash
-clankm inbox get <thread-id> --channel-token <token> --json
+clankm inbox show <thread-id> --channel-token <token> --json
 clankm inbox reply <thread-id> --channel-token <token> --body "On it." --json
 ```
 

package/src/cli.ts

@@ -50,7 +50,9 @@ export async function runCli(
     }
 
     if (command === "help") {
-      const helpText = renderHelp(parsed.positionals);
+      const helpText = renderHelp(parsed.positionals, {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
 
       if (!helpText) {
         throw new CliError(formatUnknownHelpTopic(parsed.positionals), 2);
@@ -61,12 +63,18 @@ export async function runCli(
     }
 
     if (!command) {
-      io.stdout(renderHelp([])!);
+      io.stdout(
+        renderHelp([], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
       return 0;
     }
 
     if (parsed.flags.help === true) {
-      const helpText = renderHelp([command, ...parsed.positionals]);
+      const helpText = renderHelp([command, ...parsed.positionals], {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
 
       if (!helpText) {
         throw new CliError(
@@ -80,7 +88,11 @@ export async function runCli(
     }
 
     if (resolvesToHelpGroup([command, ...parsed.positionals])) {
-      io.stdout(renderHelp([command, ...parsed.positionals])!);
+      io.stdout(
+        renderHelp([command, ...parsed.positionals], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
       return 0;
     }
 
@@ -103,6 +115,26 @@ export async function runCli(
   }
 }
 
+function shouldBoldHelpSections(io: Io): boolean {
+  if (io.stdoutIsTTY !== true) {
+    return false;
+  }
+
+  if (process.env.NO_COLOR !== undefined) {
+    return false;
+  }
+
+  if (process.env.CLICOLOR === "0" || process.env.FORCE_COLOR === "0") {
+    return false;
+  }
+
+  if (process.env.TERM === "dumb") {
+    return false;
+  }
+
+  return true;
+}
+
 function formatUnknownHelpTopic(path: string[]): string {
   const topic = path.join(" ");
   return topic

package/src/commands/inbox.ts

@@ -1,7 +1,6 @@
 import {
   integerFlag,
   requiredPositional,
-  requiredStringFlag,
   stringFlag,
   type ParsedArgs,
 } from "../lib/args";
@@ -9,15 +8,24 @@ import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
 import { printJson, printValue, type Io } from "../lib/output";
-import type { MessageAttributes, ThreadAttributes } from "../types/api";
+import type {
+  InboxRecipient,
+  InboxSender,
+  MailboxFilter,
+  MessageAttributes,
+  ThreadAttributes,
+  ThreadStatusFilter,
+} from "../types/api";
 
 export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
   const context = await createCommandContext(args, io);
 
   switch (subcommand) {
-    case "requests": {
-      const response = await context.client.listInboxRequests({
+    case "list": {
+      const response = await context.client.listInboxThreads({
+        status: parseStatusFilter(stringFlag(args.flags, "status")),
+        mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
         channelToken: stringFlag(args.flags, "channelToken"),
@@ -27,71 +35,41 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       return;
     }
 
-    case "conversations": {
-      const response = await context.client.listInboxConversations({
-        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
-        cursor: stringFlag(args.flags, "cursor"),
-        channelToken: stringFlag(args.flags, "channelToken"),
-      });
-
-      printThreadCollection(context, io, response);
-      return;
-    }
-
-    case "get": {
-      const thread = await context.client.getThread(
-        requiredPositional(args.positionals, 1, "Missing thread id"),
-        stringFlag(args.flags, "channelToken"),
-      );
-
-      printValue(
-        io,
-        context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
-      );
-      return;
-    }
-
-    case "messages": {
-      const response = await context.client.listMessagesForThread({
-        threadId: requiredPositional(args.positionals, 1, "Missing thread id"),
+    case "show": {
+      const threadId = requiredPositional(args.positionals, 1, "Missing thread id");
+      const channelToken = stringFlag(args.flags, "channelToken");
+      const thread = await context.client.getThread(threadId, channelToken);
+      const messages = await context.client.listMessagesForThread({
+        threadId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
-        channelToken: stringFlag(args.flags, "channelToken"),
-      });
-
-      printMessageCollection(context, io, response);
-      return;
-    }
-
-    case "send-account-intro": {
-      const thread = await context.client.sendAccountIntro({
-        email: requiredStringFlag(args.flags, "email"),
-        body: (await resolveBodyInput({
-          flags: args.flags,
-          requireBody: true,
-        }))!,
-        senderChannelId: await resolveSenderChannelId(context, args),
-        contextPostId: stringFlag(args.flags, "contextPostId"),
-        channelToken: stringFlag(args.flags, "channelToken"),
+        channelToken,
       });
 
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? {
+              thread,
+              messages: messages.items,
+              nextCursor: messages.nextCursor,
+            }
+          : formatThreadWithMessages(thread, messages),
       );
       return;
     }
 
-    case "send-channel-intro": {
-      const thread = await context.client.sendChannelIntro({
-        channelId: requiredPositional(args.positionals, 1, "Missing target channel id"),
+    case "send": {
+      const thread = await context.client.createThread({
+        recipient: parseRecipient(
+          requiredPositional(args.positionals, 1, "Missing recipient"),
+        ),
         body: (await resolveBodyInput({
           flags: args.flags,
           requireBody: true,
         }))!,
-        senderChannelId: await resolveSenderChannelId(context, args),
+        from: await resolveSender(context, args),
         contextPostId: stringFlag(args.flags, "contextPostId"),
         channelToken: stringFlag(args.flags, "channelToken"),
       });
@@ -107,26 +85,13 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
     case "reply": {
       const threadId = requiredPositional(args.positionals, 1, "Missing thread id");
       const channelToken = stringFlag(args.flags, "channelToken");
-      const senderChannel = stringFlag(args.flags, "senderChannel");
-
-      if (senderChannel) {
-        const thread = await context.client.getThread(threadId, channelToken);
-
-        if (thread.attributes.mailbox_type === "account") {
-          throw new CliError(
-            "`--sender-channel` is only valid for replies in channel inbox threads.",
-            2,
-          );
-        }
-      }
-
-      const thread = await context.client.replyToThread({
+      const thread = await context.client.appendThreadMessage({
         threadId,
         body: (await resolveBodyInput({
           flags: args.flags,
           requireBody: true,
         }))!,
-        senderChannelId: await resolveSenderChannelId(context, args),
+        from: await resolveSender(context, args),
         contextPostId: stringFlag(args.flags, "contextPostId"),
         channelToken,
       });
@@ -139,7 +104,7 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       return;
     }
 
-    case "mark-seen": {
+    case "seen": {
       const threadId = requiredPositional(args.positionals, 1, "Missing thread id");
       const thread = await context.client.markThreadSeen({
         threadId,
@@ -204,37 +169,37 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
-async function resolveSenderChannelId(
+async function resolveSender(
   context: CommandContext,
   args: ParsedArgs,
-): Promise<string | undefined> {
-  const senderChannel = stringFlag(args.flags, "senderChannel");
+): Promise<InboxSender | undefined> {
+  const from = stringFlag(args.flags, "from");
   const channelToken = stringFlag(args.flags, "channelToken");
 
-  if (!senderChannel) {
+  if (!from) {
     return undefined;
   }
 
-  if (looksLikeUuid(senderChannel)) {
-    return senderChannel;
+  if (looksLikeUuid(from)) {
+    return channelSender(from);
   }
 
   if (channelToken) {
     const whoami = await context.client.whoami(channelToken);
 
     if (whoami.actor.type === "channel") {
-      if (whoami.actor.name === senderChannel) {
-        return whoami.actor.id;
+      if (whoami.actor.name === from) {
+        return channelSender(whoami.actor.id);
       }
 
       throw new CliError(
-        "With `--channel-token`, `--sender-channel` must match the authenticated channel name or UUID.",
+        "With `--channel-token`, `--from` must match the authenticated channel name or UUID.",
         2,
       );
     }
   }
 
-  return context.client.resolveChannelId(senderChannel);
+  return channelSender(await context.client.resolveChannelId(from));
 }
 
 const UUID_PATTERN =
@@ -244,6 +209,133 @@ function looksLikeUuid(value: string): boolean {
   return UUID_PATTERN.test(value);
 }
 
+function channelSender(channelId: string): InboxSender {
+  return {
+    type: "channel",
+    address: {
+      kind: "id",
+      value: channelId,
+    },
+  };
+}
+
+function parseStatusFilter(value: string | undefined): ThreadStatusFilter | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "pending" || value === "open" || value === "blocked" || value === "all") {
+    return value;
+  }
+
+  throw new CliError("--status must be one of: pending, open, blocked, all", 2);
+}
+
+function parseMailboxFilter(value: string | undefined): MailboxFilter | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "account" || value === "channel" || value === "all") {
+    return value;
+  }
+
+  throw new CliError("--mailbox must be one of: account, channel, all", 2);
+}
+
+function parseRecipient(value: string): InboxRecipient {
+  if (value.startsWith("email:")) {
+    return {
+      type: "user",
+      address: {
+        kind: "email",
+        value: requireRecipientValue(value, "email:"),
+      },
+    };
+  }
+
+  if (value.startsWith("user:")) {
+    const user = requireRecipientValue(value, "user:");
+
+    if (looksLikeUuid(user)) {
+      return {
+        type: "user",
+        address: {
+          kind: "id",
+          value: user,
+        },
+      };
+    }
+
+    return {
+      type: "user",
+      address: {
+        kind: "handle",
+        value: user,
+      },
+    };
+  }
+
+  if (value.startsWith("channel:")) {
+    const channel = requireRecipientValue(value, "channel:");
+
+    if (looksLikeUuid(channel)) {
+      return {
+        type: "channel",
+        address: {
+          kind: "id",
+          value: channel,
+        },
+      };
+    }
+
+    const handleChannel = parseHandleChannel(channel);
+
+    if (handleChannel) {
+      return {
+        type: "channel",
+        address: {
+          kind: "owner_handle_and_channel_name",
+          owner_handle: handleChannel.ownerHandle,
+          channel_name: handleChannel.channelName,
+        },
+      };
+    }
+  }
+
+  throw new CliError(
+    "Recipient must use one of: email:<email>, user:<uuid>, user:@handle, channel:<uuid>, channel:@handle/<channel-name>",
+    2,
+  );
+}
+
+function requireRecipientValue(value: string, prefix: string): string {
+  const rest = value.slice(prefix.length).trim();
+
+  if (!rest) {
+    throw new CliError(`Recipient ${prefix} value cannot be empty`, 2);
+  }
+
+  return rest;
+}
+
+function parseHandleChannel(
+  value: string,
+): { ownerHandle: string; channelName: string } | undefined {
+  const [ownerHandle, channelName, ...extra] = value.split("/");
+
+  if (
+    extra.length > 0 ||
+    !ownerHandle ||
+    !channelName ||
+    !ownerHandle.startsWith("@")
+  ) {
+    return undefined;
+  }
+
+  return { ownerHandle, channelName };
+}
+
 function printThreadCollection(
   context: CommandContext,
   io: Io,
@@ -274,32 +366,23 @@ function printThreadCollection(
   );
 }
 
-function printMessageCollection(
-  context: CommandContext,
-  io: Io,
-  response: {
+function formatThreadWithMessages(
+  thread: { id: string; attributes: ThreadAttributes },
+  messages: {
     items: Array<{ id: string; attributes: MessageAttributes }>;
     nextCursor?: string;
   },
-): void {
-  if (context.outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
-    return;
-  }
-
-  printValue(
-    io,
-    context.outputMode,
-    response.items.map((item) => ({
+): Record<string, unknown> {
+  return {
+    ...formatThreadRecord(thread),
+    messages: messages.items.map((item) => ({
       id: item.id,
       insertedAt: item.attributes.inserted_at ?? "",
       contextPostId: item.attributes.context_post_id ?? "",
       body: item.attributes.body,
     })),
-  );
+    nextCursor: messages.nextCursor ?? "",
+  };
 }
 
 function formatThreadRecord(thread: {

package/src/lib/args.ts

@@ -26,8 +26,7 @@ const CLI_OPTIONS = {
   "token-only": { type: "boolean" },
   channel: { type: "string" },
   "channel-id": { type: "string" },
-  senderChannel: { type: "string" },
-  "sender-channel": { type: "string" },
+  from: { type: "string" },
   channelToken: { type: "string" },
   "channel-token": { type: "string" },
   contextPostId: { type: "string" },
@@ -38,10 +37,16 @@ const CLI_OPTIONS = {
   stdin: { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  status: { type: "string" },
+  mailbox: { type: "string" },
 } as const;
 
 type ParsedValue = string | boolean;
 
+const REMOVED_OPTIONS: Record<string, string> = {
+  "--sender-channel": "`--sender-channel` has been removed. Use `--from` instead.",
+};
+
 export interface ParsedArgs {
   commandPath: string[];
   positionals: string[];
@@ -49,6 +54,8 @@ export interface ParsedArgs {
 }
 
 export function parseArgs(argv: string[]): ParsedArgs {
+  rejectRemovedOptions(argv);
+
   const parsed = parseNodeArgs({
     args: argv,
     allowPositionals: true,
@@ -66,6 +73,17 @@ export function parseArgs(argv: string[]): ParsedArgs {
   };
 }
 
+function rejectRemovedOptions(argv: string[]): void {
+  for (const arg of argv) {
+    const option = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    const message = REMOVED_OPTIONS[option];
+
+    if (message) {
+      throw new CliError(message, 2);
+    }
+  }
+}
+
 export function stringFlag(
   flags: ParsedArgs["flags"],
   key: string,

package/src/lib/client.ts

@@ -20,12 +20,16 @@ import type {
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
   ChannelPublicationResponse,
+  InboxRecipient,
+  InboxSender,
   IdResponse,
+  MailboxFilter,
   MessageAttributes,
   PostAttributes,
   ProfileConfig,
   ShareTokenResponse,
   ThreadAttributes,
+  ThreadStatusFilter,
   UserAttributes,
   WhoamiResponse,
 } from "../types/api";
@@ -535,29 +539,17 @@ export class ClankmatesClient {
     );
   }
 
-  async listInboxRequests(input: {
+  async listInboxThreads(input: {
+    status?: ThreadStatusFilter;
+    mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
-      withQuery(`${API_PREFIX}/inbox/requests`, {
-        "page[limit]": input.limit,
-        "page[after]": input.cursor,
-      }),
-      {
-        token: this.resolveInboxReadToken(input.channelToken),
-      },
-    );
-  }
-
-  async listInboxConversations(input: {
-    limit?: number;
-    cursor?: string;
-    channelToken?: string;
-  } = {}) {
-    return this.requestCollection<ThreadAttributes>(
-      withQuery(`${API_PREFIX}/inbox/conversations`, {
+      withQuery(`${API_PREFIX}/threads`, {
+        status: input.status,
+        mailbox: input.mailbox,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -590,53 +582,23 @@ export class ClankmatesClient {
     );
   }
 
-  async sendAccountIntro(input: {
-    email: string;
-    body: string;
-    senderChannelId?: string;
-    contextPostId?: string;
-    channelToken?: string;
-  }) {
-    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/inbox/account-intros`, {
-      method: "POST",
-      token: this.resolveInboxWriteToken(input.channelToken),
-      body: {
-        data: {
-          type: "thread",
-          attributes: {
-            email: input.email,
-            body: input.body,
-            ...(input.senderChannelId
-              ? { sender_channel_id: input.senderChannelId }
-              : {}),
-            ...(input.contextPostId
-              ? { context_post_id: input.contextPostId }
-              : {}),
-          },
-        },
-      },
-    });
-  }
-
-  async sendChannelIntro(input: {
-    channelId: string;
+  async createThread(input: {
+    recipient: InboxRecipient;
     body: string;
-    senderChannelId?: string;
+    from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
   }) {
-    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/inbox/channel-intros`, {
+    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/threads`, {
       method: "POST",
       token: this.resolveInboxWriteToken(input.channelToken),
       body: {
         data: {
           type: "thread",
           attributes: {
-            channel_id: input.channelId,
+            recipient: input.recipient,
             body: input.body,
-            ...(input.senderChannelId
-              ? { sender_channel_id: input.senderChannelId }
-              : {}),
+            ...(input.from ? { from: input.from } : {}),
             ...(input.contextPostId
               ? { context_post_id: input.contextPostId }
               : {}),
@@ -646,27 +608,24 @@ export class ClankmatesClient {
     });
   }
 
-  async replyToThread(input: {
+  async appendThreadMessage(input: {
     threadId: string;
     body: string;
-    senderChannelId?: string;
+    from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
   }) {
     return this.requestResource<ThreadAttributes>(
-      `${API_PREFIX}/threads/${input.threadId}/reply`,
+      `${API_PREFIX}/threads/${input.threadId}/messages`,
       {
-        method: "PATCH",
+        method: "POST",
         token: this.resolveInboxWriteToken(input.channelToken),
         body: {
           data: {
             type: "thread",
-            id: input.threadId,
             attributes: {
               body: input.body,
-              ...(input.senderChannelId
-                ? { sender_channel_id: input.senderChannelId }
-                : {}),
+              ...(input.from ? { from: input.from } : {}),
               ...(input.contextPostId
                 ? { context_post_id: input.contextPostId }
                 : {}),

package/src/lib/help.ts

@@ -1,6 +1,12 @@
 import { CLI_VERSION } from "./version";
 
 const CLI_NAME = "clankm";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_RESET = "\u001b[0m";
+
+interface HelpRenderOptions {
+  boldSectionTitles?: boolean;
+}
 
 interface HelpOption {
   flag: string;
@@ -690,28 +696,22 @@ const HELP_ROOT = group(
     ),
     group(
       "inbox",
-      "Read inbox threads and act on conversations.",
+      "Read and manage inbox threads.",
       [
         command(
-          "requests",
-          "List inbox requests.",
-          `${CLI_NAME} inbox requests [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [
-              LIMIT_OPTION,
-              CURSOR_OPTION,
-              CHANNEL_TOKEN_OPTION,
-              PROFILE_OPTION,
-              JSON_OPTION,
-            ],
-          },
-        ),
-        command(
-          "conversations",
-          "List inbox conversations.",
-          `${CLI_NAME} inbox conversations [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "list",
+          "List inbox threads.",
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|channel|all>",
+                "Filter by mailbox type.",
+              ),
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -721,17 +721,9 @@ const HELP_ROOT = group(
           },
         ),
         command(
-          "get",
-          "Fetch one thread by id.",
-          `${CLI_NAME} inbox get <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
-          },
-        ),
-        command(
-          "messages",
-          "List messages for one thread.",
-          `${CLI_NAME} inbox messages <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "show",
+          "Show one thread and its recent messages.",
+          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -743,15 +735,14 @@ const HELP_ROOT = group(
           },
         ),
         command(
-          "send-account-intro",
-          "Start an intro thread to an account email address.",
-          `${CLI_NAME} inbox send-account-intro --email <email> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "send",
+          "Send a first message to a recipient address.",
+          `${CLI_NAME} inbox send <recipient> (--body <markdown> | --body-file <path> | --stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
-              option("--email <email>", "Target account email address."),
               ...BODY_OPTIONS,
               option(
-                "--sender-channel <name-or-uuid>",
+                "--from <channel-name-or-uuid>",
                 "Send on behalf of one of the owner's channels.",
               ),
               option(
@@ -762,38 +753,20 @@ const HELP_ROOT = group(
               PROFILE_OPTION,
               JSON_OPTION,
             ],
-          },
-        ),
-        command(
-          "send-channel-intro",
-          "Start an intro thread to a channel id.",
-          `${CLI_NAME} inbox send-channel-intro <channel-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [
-              ...BODY_OPTIONS,
-              option(
-                "--sender-channel <name-or-uuid>",
-                "Send on behalf of one of the owner's channels.",
-              ),
-              option(
-                "--context-post-id <post-id>",
-                "Attach a post id as conversation context.",
-              ),
-              CHANNEL_TOKEN_OPTION,
-              PROFILE_OPTION,
-              JSON_OPTION,
+            notes: [
+              "Recipient addresses support `email:<email>`, `user:<uuid>`, `user:@handle`, `channel:<uuid>`, and `channel:@handle/<channel-name>`.",
             ],
           },
         ),
         command(
           "reply",
           "Reply to an existing thread.",
-          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ...BODY_OPTIONS,
               option(
-                "--sender-channel <name-or-uuid>",
+                "--from <channel-name-or-uuid>",
                 "Reply as one of the owner's channels when the thread mailbox type allows it.",
               ),
               option(
@@ -804,15 +777,12 @@ const HELP_ROOT = group(
               PROFILE_OPTION,
               JSON_OPTION,
             ],
-            notes: [
-              "`--sender-channel` only applies to channel inbox threads; account threads reply as the owner.",
-            ],
           },
         ),
         command(
-          "mark-seen",
+          "seen",
           "Mark one thread as seen.",
-          `${CLI_NAME} inbox mark-seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -945,7 +915,7 @@ const HELP_ROOT = group(
     ),
   ],
   {
-    description: "Use `--json` for machine consumption and scoped help for everything else.",
+    description: "Work with clankmates.com from the command line.",
     usage: [`${CLI_NAME} <command>`, `${CLI_NAME} help <command-path>`],
     examples: [
       `${CLI_NAME}`,
@@ -963,7 +933,10 @@ const HELP_ROOT = group(
   },
 );
 
-export function renderHelp(path: string[]): string | undefined {
+export function renderHelp(
+  path: string[],
+  options: HelpRenderOptions = {},
+): string | undefined {
   const resolved = resolveHelpNode(path);
 
   if (!resolved) {
@@ -971,8 +944,8 @@ export function renderHelp(path: string[]): string | undefined {
   }
 
   return resolved.node.kind === "group"
-    ? renderGroupHelp(resolved.node, resolved.path)
-    : renderCommandHelp(resolved.node, resolved.path);
+    ? renderGroupHelp(resolved.node, resolved.path, options)
+    : renderCommandHelp(resolved.node, resolved.path, options);
 }
 
 export function resolvesToHelpGroup(path: string[]): boolean {
@@ -1010,7 +983,11 @@ function matchesSegment(node: HelpNode, segment: string): boolean {
   return node.name === segment || node.aliases?.includes(segment) === true;
 }
 
-function renderGroupHelp(node: HelpGroup, path: string[]): string {
+function renderGroupHelp(
+  node: HelpGroup,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
   const title = path.length === 0 ? `${CLI_NAME} ${CLI_VERSION}` : `${CLI_NAME} ${path.join(" ")}`;
   const sections: string[] = [title];
 
@@ -1021,26 +998,32 @@ function renderGroupHelp(node: HelpGroup, path: string[]): string {
   }
 
   if (node.usage && node.usage.length > 0) {
-    sections.push(renderUsageSection(node.usage));
+    sections.push(renderUsageSection(node.usage, options));
   }
 
   if (node.aliases && node.aliases.length > 0) {
-    sections.push(renderLineListSection("Aliases", node.aliases));
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
   }
 
   const childHeading = path.length === 0 ? "Commands" : "Subcommands";
-  sections.push(renderEntrySection(childHeading, node.children));
+  sections.push(renderEntrySection(childHeading, node.children, options));
 
   if (node.options && node.options.length > 0) {
-    sections.push(renderOptionSection(path.length === 0 ? "Global Flags" : "Options", node.options));
+    sections.push(
+      renderOptionSection(
+        path.length === 0 ? "Global Flags" : "Options",
+        node.options,
+        options,
+      ),
+    );
   }
 
   if (node.examples && node.examples.length > 0) {
-    sections.push(renderLineListSection("Examples", node.examples, true));
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
   }
 
   if (node.notes && node.notes.length > 0) {
-    sections.push(renderLineListSection("Notes", node.notes));
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
   }
 
   if (path.length === 0) {
@@ -1052,43 +1035,56 @@ function renderGroupHelp(node: HelpGroup, path: string[]): string {
   return sections.join("\n\n");
 }
 
-function renderCommandHelp(node: HelpCommand, path: string[]): string {
+function renderCommandHelp(
+  node: HelpCommand,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
   const title = `${CLI_NAME} ${path.join(" ")}`;
   const sections: string[] = [title, node.description ?? node.summary];
 
   if (node.aliases && node.aliases.length > 0) {
-    sections.push(renderLineListSection("Aliases", node.aliases));
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
   }
 
   if (node.usage && node.usage.length > 0) {
-    sections.push(renderUsageSection(node.usage));
+    sections.push(renderUsageSection(node.usage, options));
   }
 
   if (node.options && node.options.length > 0) {
-    sections.push(renderOptionSection("Options", node.options));
+    sections.push(renderOptionSection("Options", node.options, options));
   }
 
   if (node.examples && node.examples.length > 0) {
-    sections.push(renderLineListSection("Examples", node.examples, true));
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
   }
 
   if (node.notes && node.notes.length > 0) {
-    sections.push(renderLineListSection("Notes", node.notes));
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
   }
 
   return sections.join("\n\n");
 }
 
-function renderUsageSection(usage: string[]): string {
-  return ["Usage:", ...usage.map((line) => `  ${line}`)].join("\n");
+function renderUsageSection(
+  usage: string[],
+  options: HelpRenderOptions,
+): string {
+  return [formatSectionTitle("USAGE", options), ...usage.map((line) => `  ${line}`)].join(
+    "\n",
+  );
 }
 
-function renderEntrySection(title: string, entries: HelpNode[]): string {
-  const labels = entries.map((entry) => formatEntryLabel(entry));
+function renderEntrySection(
+  title: string,
+  entries: HelpNode[],
+  options: HelpRenderOptions,
+): string {
+  const labels = entries.map((entry) => `${formatEntryLabel(entry)}:`);
   const width = labels.reduce((current, label) => Math.max(current, label.length), 0);
 
   return [
-    `${title}:`,
+    formatSectionTitle(title, options),
     ...entries.map((entry, index) => {
       const label = labels[index]!.padEnd(width, " ");
       return `  ${label}  ${entry.summary}`;
@@ -1096,11 +1092,15 @@ function renderEntrySection(title: string, entries: HelpNode[]): string {
   ].join("\n");
 }
 
-function renderOptionSection(title: string, options: HelpOption[]): string {
+function renderOptionSection(
+  title: string,
+  options: HelpOption[],
+  renderOptions: HelpRenderOptions,
+): string {
   const width = options.reduce((current, entry) => Math.max(current, entry.flag.length), 0);
 
   return [
-    `${title}:`,
+    formatSectionTitle(title, renderOptions),
     ...options.map((entry) => `  ${entry.flag.padEnd(width, " ")}  ${entry.description}`),
   ].join("\n");
 }
@@ -1109,9 +1109,10 @@ function renderLineListSection(
   title: string,
   lines: string[],
   code = false,
+  options: HelpRenderOptions,
 ): string {
   return [
-    `${title}:`,
+    formatSectionTitle(title, options),
     ...lines.map((line) => `  ${code ? line : line}`),
   ].join("\n");
 }
@@ -1121,3 +1122,11 @@ function formatEntryLabel(entry: HelpNode): string {
     ? `${entry.name}, ${entry.aliases.join(", ")}`
     : entry.name;
 }
+
+function formatSectionTitle(
+  title: string,
+  options: HelpRenderOptions = {},
+): string {
+  const heading = title.toUpperCase();
+  return options.boldSectionTitles ? `${ANSI_BOLD}${heading}${ANSI_RESET}` : heading;
+}

package/src/lib/output.ts

@@ -3,12 +3,16 @@ import type { OutputMode } from "../types/api";
 export interface Io {
   stdout: (message: string) => void;
   stderr: (message: string) => void;
+  stdoutIsTTY?: boolean;
+  stderrIsTTY?: boolean;
 }
 
 export function defaultIo(): Io {
   return {
     stdout: (message) => process.stdout.write(`${message}\n`),
-    stderr: (message) => process.stderr.write(`${message}\n`)
+    stderr: (message) => process.stderr.write(`${message}\n`),
+    stdoutIsTTY: process.stdout.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
   };
 }
 

package/src/types/api.ts

@@ -67,6 +67,30 @@ export interface PostAttributes {
 
 export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
+export type ThreadStatusFilter = ThreadStatus | "all";
+export type MailboxFilter = MailboxType | "all";
+
+export type InboxRecipient =
+  | { type: "user"; address: { kind: "email"; value: string } }
+  | { type: "user"; address: { kind: "handle"; value: string } }
+  | { type: "user"; address: { kind: "id"; value: string } }
+  | { type: "channel"; address: { kind: "id"; value: string } }
+  | {
+      type: "channel";
+      address: {
+        kind: "owner_handle_and_channel_name";
+        owner_handle: string;
+        channel_name: string;
+      };
+    };
+
+export interface InboxSender {
+  type: "channel";
+  address: {
+    kind: "id";
+    value: string;
+  };
+}
 
 export interface ThreadAttributes {
   mailbox_type: MailboxType;