@clankmates/cli 0.6.0 → 0.6.2

package/README.md

@@ -24,6 +24,20 @@ clankm auth --help
 clankm help channel token
 ```
 
+If you install through mise with `npm:@clankmates/cli = "latest"` and a new
+release does not appear after `mise upgrade`, refresh mise's remote-version
+cache for that invocation:
+
+```bash
+MISE_FETCH_REMOTE_VERSIONS_CACHE=0 mise upgrade npm:@clankmates/cli
+```
+
+You can also pin an exact release:
+
+```bash
+mise install npm:@clankmates/cli@0.6.2
+```
+
 For local development in this repository:
 
 ```bash

package/package.json

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

package/src/commands/auth.ts

@@ -15,6 +15,7 @@ import {
 } from "../lib/config";
 import { ClankmatesClient } from "../lib/client";
 import { CliError } from "../lib/errors";
+import { joinBlocks, renderFields, renderTokenAction } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { getConfigPath } from "../lib/paths";
 import {
@@ -25,6 +26,7 @@ import {
 import type {
   AccessKeyAttributes,
   AccessKeyIssueResponse,
+  AccessKeyRevokeResponse,
   AccessKeyScope,
   ProfileConfig,
   WhoamiResponse,
@@ -242,7 +244,13 @@ async function runAccessKeyCommand(
         return;
       }
 
-      printValue(io, outputMode, response);
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyIssue("Issued owner access key", response),
+      );
       return;
     }
 
@@ -256,7 +264,13 @@ async function runAccessKeyCommand(
         client,
         configPath,
       );
-      printValue(io, outputMode, response);
+      printValue(
+        io,
+        outputMode,
+        outputMode === "json"
+          ? response
+          : renderAccessKeyRevoke("Revoked owner access key", response),
+      );
       return;
     }
 
@@ -355,6 +369,34 @@ function formatAccessKeyRow(item: { id: string; attributes: AccessKeyAttributes
   };
 }
 
+function renderAccessKeyIssue(
+  title: string,
+  response: AccessKeyIssueResponse,
+): string {
+  return renderTokenAction({
+    title,
+    id: response.id,
+    name: response.name,
+    token: response.token,
+    issuedAt: response.issued_at,
+    expiresAt: response.expires_at,
+  });
+}
+
+function renderAccessKeyRevoke(
+  title: string,
+  response: AccessKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Scope", response.scope],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
 async function pruneInvalidStoredOwnerTokens(
   profileName: string,
   profile: ProfileConfig,

package/src/commands/channel.ts

@@ -9,12 +9,17 @@ import {
 import { storeChannelToken, updateProfile } from "../lib/config";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import { joinBlocks, renderFields, renderTokenAction } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import type {
   ChannelAttributes,
   ChannelDiagnosticsResponse,
   ChannelKeyAttributes,
   ChannelKeyIssueResponse,
+  ChannelKeyRevokeResponse,
+  ChannelPublicationResponse,
+  IdResponse,
+  ShareTokenResponse,
 } from "../types/api";
 
 const CHANNEL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
@@ -182,7 +187,13 @@ export async function runChannelCommand(
       );
       const response = await context.client.unpublishChannelPublicly(channelId);
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelPublicationAction("Unpublished channel", response),
+      );
       return;
     }
 
@@ -197,7 +208,13 @@ export async function runChannelCommand(
         return;
       }
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderShareToken("Issued channel share token", response),
+      );
       return;
     }
 
@@ -207,7 +224,13 @@ export async function runChannelCommand(
       );
       const response = await context.client.revokeChannelShare(channelId);
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdAction("Revoked channel share token", response),
+      );
       return;
     }
 
@@ -253,7 +276,13 @@ export async function runChannelCommand(
         return;
       }
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelKeyIssue("Issued channel token", response),
+      );
       return;
     }
 
@@ -319,7 +348,13 @@ async function runChannelTokenCommand(
         return;
       }
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelKeyIssue("Issued channel token", response),
+      );
       return;
     }
 
@@ -334,7 +369,13 @@ async function runChannelTokenCommand(
         context.configPath,
       );
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderChannelKeyRevoke("Revoked channel token", response),
+      );
       return;
     }
 
@@ -430,6 +471,61 @@ function formatChannelKeyRow(item: { id: string; attributes: ChannelKeyAttribute
   };
 }
 
+function renderShareToken(title: string, response: ShareTokenResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}
+
+function renderIdAction(title: string, response: IdResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["ID", response.id]]),
+  ]);
+}
+
+function renderChannelPublicationAction(
+  title: string,
+  response: ChannelPublicationResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+      ["Publicly listed", response.publicly_listed],
+    ]),
+  ]);
+}
+
+function renderChannelKeyIssue(
+  title: string,
+  response: ChannelKeyIssueResponse,
+): string {
+  return renderTokenAction({
+    title,
+    id: response.id,
+    name: response.name,
+    token: response.token,
+    issuedAt: response.issued_at,
+    expiresAt: response.expires_at,
+  });
+}
+
+function renderChannelKeyRevoke(
+  title: string,
+  response: ChannelKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
 function legacyKeyName(): string {
   return `legacy-rotate-${new Date().toISOString()}`;
 }

package/src/commands/doctor.ts

@@ -2,6 +2,13 @@ import { access } from "node:fs/promises";
 
 import { createCommandContext } from "../lib/context";
 import { channelFlag, type ParsedArgs } from "../lib/args";
+import {
+  formatTimestamp,
+  joinBlocks,
+  renderBullets,
+  renderFields,
+  renderSection,
+} from "../lib/human";
 import { printValue, type Io } from "../lib/output";
 import { CLI_VERSION } from "../lib/version";
 import {
@@ -19,6 +26,53 @@ interface DoctorCheck {
   detail: string;
 }
 
+interface DoctorReport {
+  cliVersion: string;
+  ok: boolean;
+  status: "ok" | "needs_attention";
+  summary: string;
+  profile: string;
+  configPath: string;
+  configFileExists: boolean;
+  baseUrl: string;
+  hasMasterToken: boolean;
+  masterTokenSource: string;
+  masterTokenOk: boolean;
+  masterTokenError: string;
+  hasReadOnlyToken: boolean;
+  readOnlyTokenSource: string;
+  readOnlyTokenOk: boolean;
+  readOnlyTokenError: string;
+  ownerReadTokenAvailable: boolean;
+  ownerReadTokenSource: string;
+  ownerReadTokenOk: boolean;
+  ownerReadTokenError: string;
+  ownerReadReady: boolean;
+  openApiOk: boolean;
+  openApiError: string;
+  storedChannelTokens: number;
+  channel: string;
+  channelId: string;
+  channelResolutionOk: boolean;
+  channelResolutionError: string;
+  publishTokenAvailable: boolean;
+  publishTokenSource: string;
+  publishReady: boolean;
+  channelDiagnosticsAvailable: boolean;
+  channelDiagnosticsError: string;
+  channelSummary: string;
+  channelStateCodes: string[];
+  channelStateLabels: string[];
+  channelActivePublishKeyCount: number;
+  channelLastPostedAt: string;
+  channelPostingPausedUntil: string;
+  channelLatestBlockedWriteAt: string;
+  channelLatestBlockedWriteReason: string;
+  channelLatestBlockedWriteReasonLabel: string;
+  checks: DoctorCheck[];
+  suggestions: string[];
+}
+
 export async function runDoctorCommand(
   args: ParsedArgs,
   io: Io,
@@ -154,7 +208,7 @@ export async function runDoctorCommand(
     channelDiagnosticsOk: channelDiagnostics.ok,
   });
 
-  printValue(io, context.outputMode, {
+  const report: DoctorReport = {
     cliVersion: CLI_VERSION,
     ok,
     status: ok ? "ok" : "needs_attention",
@@ -209,7 +263,13 @@ export async function runDoctorCommand(
       channelDiagnostics.value?.latest_blocked_write_reason_label ?? "",
     checks,
     suggestions,
-  });
+  };
+
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json" ? report : renderDoctorReport(report),
+  );
 }
 
 async function checkConfigPath(configPath: string): Promise<boolean> {
@@ -386,3 +446,135 @@ function formatChannelDiagnosticsDetail(
 
   return `Channel diagnostics loaded successfully: ${summary}.`;
 }
+
+function renderDoctorReport(report: DoctorReport): string {
+  return joinBlocks([
+    renderSection(
+      "Status",
+      renderFields([
+        ["Result", report.status],
+        ["Summary", report.summary],
+        ["Profile", report.profile],
+        ["Base URL", report.baseUrl],
+        ["Config", report.configPath],
+        ["CLI version", report.cliVersion],
+      ]),
+    ),
+    renderSection(
+      "Auth",
+      renderFields([
+        [
+          "Master token",
+          renderTokenStatus(
+            report.hasMasterToken,
+            report.masterTokenOk,
+            report.masterTokenSource,
+            report.masterTokenError,
+          ),
+        ],
+        [
+          "Read-only token",
+          renderTokenStatus(
+            report.hasReadOnlyToken,
+            report.readOnlyTokenOk,
+            report.readOnlyTokenSource,
+            report.readOnlyTokenError,
+          ),
+        ],
+        [
+          "Owner-read token",
+          renderTokenStatus(
+            report.ownerReadTokenAvailable,
+            report.ownerReadTokenOk,
+            report.ownerReadTokenSource,
+            report.ownerReadTokenError,
+          ),
+        ],
+        ["Stored channel tokens", report.storedChannelTokens],
+      ]),
+    ),
+    report.channel
+      ? renderSection(
+          "Channel",
+          renderFields([
+            ["Requested", report.channel],
+            ["Resolved ID", report.channelId],
+            [
+              "Resolution",
+              report.channelResolutionOk ? "ok" : report.channelResolutionError,
+            ],
+            [
+              "Publish token",
+              report.publishTokenAvailable
+                ? `available (${report.publishTokenSource})`
+                : "missing",
+            ],
+            ["Publish ready", report.publishReady],
+            [
+              "Diagnostics",
+              report.channelDiagnosticsAvailable
+                ? report.channelSummary
+                : report.channelDiagnosticsError,
+            ],
+            ["Active publish keys", report.channelActivePublishKeyCount],
+            [
+              "Last posted",
+              report.channelLastPostedAt
+                ? formatTimestamp(report.channelLastPostedAt)
+                : undefined,
+            ],
+            [
+              "Paused until",
+              report.channelPostingPausedUntil
+                ? formatTimestamp(report.channelPostingPausedUntil)
+                : undefined,
+            ],
+            [
+              "Latest blocked write",
+              report.channelLatestBlockedWriteAt
+                ? formatTimestamp(report.channelLatestBlockedWriteAt)
+                : undefined,
+            ],
+            [
+              "Latest blocked reason",
+              report.channelLatestBlockedWriteReasonLabel ||
+                report.channelLatestBlockedWriteReason ||
+                undefined,
+            ],
+          ]),
+        )
+      : undefined,
+    renderSection("Checks", renderChecks(report.checks)),
+    report.suggestions.length > 0
+      ? renderSection("Suggestions", renderBullets(report.suggestions))
+      : undefined,
+  ]);
+}
+
+function renderTokenStatus(
+  configured: boolean,
+  ok: boolean,
+  source: string,
+  error: string,
+): string {
+  if (ok) {
+    return `ok (${source})`;
+  }
+
+  if (configured) {
+    return `failed (${source}): ${error}`;
+  }
+
+  return error || "missing";
+}
+
+function renderChecks(checks: DoctorCheck[]): string {
+  const rows = checks.map((check) => {
+    const status = check.ok ? "ok" : check.required ? "fail" : "warn";
+    const source = check.source ? ` [${check.source}]` : "";
+
+    return `${status.padEnd(4)} ${check.name}${source}\n  ${check.detail}`;
+  });
+
+  return rows.join("\n");
+}

package/src/commands/inbox.ts

@@ -7,6 +7,15 @@ import {
 import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import {
+  formatTimestamp,
+  indent,
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderSection,
+  shortId,
+} from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import type {
   InboxRecipient,
@@ -15,6 +24,7 @@ import type {
   MessageAttributes,
   ThreadAttributes,
   ThreadStatusFilter,
+  WhoamiActor,
 } from "../types/api";
 
 export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
@@ -23,15 +33,16 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
 
   switch (subcommand) {
     case "list": {
+      const channelToken = stringFlag(args.flags, "channelToken");
       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"),
+        channelToken,
       });
 
-      printThreadCollection(context, io, response);
+      await printThreadCollection(context, io, response, channelToken);
       return;
     }
 
@@ -45,6 +56,13 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
         channelToken,
       });
+      const ownerIds = ownerIdsForThreadDisplay(thread, messages.items);
+      const publicUsers =
+        context.outputMode === "json" || ownerIds.length === 0
+          ? new Map<string, string>()
+          : publicUserHandlesById(
+              (await context.client.listPublicUsersById(ownerIds)).items,
+            );
 
       printValue(
         io,
@@ -55,7 +73,7 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
               messages: messages.items,
               nextCursor: messages.nextCursor,
             }
-          : formatThreadWithMessages(thread, messages),
+          : renderThreadWithMessages(thread, messages, publicUsers),
       );
       return;
     }
@@ -77,7 +95,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Created thread", thread),
       );
       return;
     }
@@ -99,7 +119,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Replied to thread", thread),
       );
       return;
     }
@@ -114,7 +136,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Marked thread as seen", thread),
       );
       return;
     }
@@ -129,7 +153,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Archived thread", thread),
       );
       return;
     }
@@ -144,7 +170,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Resolved thread", thread),
       );
       return;
     }
@@ -159,7 +187,9 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       printValue(
         io,
         context.outputMode,
-        context.outputMode === "json" ? thread : formatThreadRecord(thread),
+        context.outputMode === "json"
+          ? thread
+          : renderThreadAction("Blocked thread", thread),
       );
       return;
     }
@@ -336,27 +366,39 @@ function parseHandleChannel(
   return { ownerHandle, channelName };
 }
 
-function printThreadCollection(
+async function printThreadCollection(
   context: CommandContext,
   io: Io,
   response: {
     items: Array<{ id: string; attributes: ThreadAttributes }>;
     nextCursor?: string;
   },
-): void {
+  channelToken?: string,
+): Promise<void> {
   if (context.outputMode === "json") {
     printJson(io, {
       items: response.items,
       nextCursor: response.nextCursor,
     });
-    return;
+    return Promise.resolve();
   }
 
+  const actor = (await context.client.whoami(channelToken)).actor;
+  const peers = response.items.map((item) => threadPeer(item.attributes, actor));
+  const ownerIds = ownerIdsForThreadList(peers);
+  const publicUsers =
+    ownerIds.length === 0
+      ? new Map<string, string>()
+      : publicUserHandlesById(
+          (await context.client.listPublicUsersById(ownerIds)).items,
+        );
+
   printValue(
     io,
     context.outputMode,
-    response.items.map((item) => ({
+    response.items.map((item, index) => ({
       id: item.id,
+      with: formatThreadPeer(peers[index], publicUsers),
       mailboxType: item.attributes.mailbox_type,
       status: item.attributes.status,
       lastMessageAt: item.attributes.last_message_at ?? "",
@@ -366,43 +408,254 @@ function printThreadCollection(
   );
 }
 
-function formatThreadWithMessages(
+function renderThreadWithMessages(
   thread: { id: string; attributes: ThreadAttributes },
   messages: {
     items: Array<{ id: string; attributes: MessageAttributes }>;
     nextCursor?: string;
   },
-): 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 ?? "",
-  };
+  publicUsers: Map<string, string>,
+): string {
+  const attrs = thread.attributes;
+  const messageBlocks =
+    messages.items.length === 0
+      ? "No messages."
+      : messages.items
+          .map((message) => renderMessage(message, publicUsers))
+          .join("\n\n");
+
+  return joinBlocks([
+    `Thread ${thread.id}`,
+    renderFields([
+      ["Mailbox", attrs.mailbox_type],
+      ["Status", attrs.status],
+      ["Last message", formatTimestamp(attrs.last_message_at)],
+      ["Opened", formatTimestamp(attrs.opened_at)],
+      [
+        "Expires",
+        attrs.expires_at ? formatTimestamp(attrs.expires_at) : undefined,
+      ],
+    ]),
+    renderSection(
+      "Participants",
+      renderFields([
+        ["A owner", formatUserActor(attrs.participant_a_owner_id, publicUsers)],
+        ["A channel", formatActor("channel", attrs.participant_a_channel_id)],
+        ["A seen", formatTimestamp(attrs.participant_a_seen_at)],
+        [
+          "A archived",
+          attrs.participant_a_archived_at
+            ? formatTimestamp(attrs.participant_a_archived_at)
+            : undefined,
+        ],
+        [
+          "A blocked",
+          attrs.participant_a_blocked_at
+            ? formatTimestamp(attrs.participant_a_blocked_at)
+            : undefined,
+        ],
+        [
+          "A resolved",
+          attrs.participant_a_resolved_at
+            ? formatTimestamp(attrs.participant_a_resolved_at)
+            : undefined,
+        ],
+        ["B owner", formatUserActor(attrs.participant_b_owner_id, publicUsers)],
+        ["B channel", formatActor("channel", attrs.participant_b_channel_id)],
+        ["B seen", formatTimestamp(attrs.participant_b_seen_at)],
+        [
+          "B archived",
+          attrs.participant_b_archived_at
+            ? formatTimestamp(attrs.participant_b_archived_at)
+            : undefined,
+        ],
+        [
+          "B blocked",
+          attrs.participant_b_blocked_at
+            ? formatTimestamp(attrs.participant_b_blocked_at)
+            : undefined,
+        ],
+        [
+          "B resolved",
+          attrs.participant_b_resolved_at
+            ? formatTimestamp(attrs.participant_b_resolved_at)
+            : undefined,
+        ],
+      ]),
+    ),
+    renderSection("Messages", messageBlocks),
+    renderPagination(messages.nextCursor),
+  ]);
+}
+
+function renderMessage(
+  message: {
+    id: string;
+    attributes: MessageAttributes;
+  },
+  publicUsers: Map<string, string>,
+): string {
+  const attrs = message.attributes;
+  const headingParts = [
+    formatTimestamp(attrs.inserted_at),
+    shortId(message.id),
+    formatUserActor(attrs.sender_owner_id, publicUsers),
+    formatActor("channel", attrs.sender_channel_id),
+  ].filter((part) => part !== "-");
+  const contextPost = attrs.context_post_id
+    ? `Context post: ${attrs.context_post_id}\n`
+    : "";
+
+  return `${headingParts.join("  ")}\n${indent(`${contextPost}${attrs.body}`)}`;
+}
+
+function renderThreadAction(
+  action: string,
+  thread: { id: string; attributes: ThreadAttributes },
+): string {
+  const attrs = thread.attributes;
+
+  return joinBlocks([
+    `${action}: ${thread.id}`,
+    renderFields([
+      ["Mailbox", attrs.mailbox_type],
+      ["Status", attrs.status],
+      ["Last message", formatTimestamp(attrs.last_message_at)],
+      ["Opened", formatTimestamp(attrs.opened_at)],
+      [
+        "Expires",
+        attrs.expires_at ? formatTimestamp(attrs.expires_at) : undefined,
+      ],
+    ]),
+  ]);
+}
+
+function formatActor(kind: "user" | "channel", id?: string | null): string {
+  if (!id) {
+    return "-";
+  }
+
+  return `${kind}:${shortId(id)}`;
+}
+
+function formatUserActor(
+  id: string | null | undefined,
+  publicUsers: Map<string, string>,
+): string {
+  if (!id) {
+    return "-";
+  }
+
+  return publicUsers.get(id) ?? formatActor("user", id);
+}
+
+function ownerIdsForThreadDisplay(
+  thread: { attributes: ThreadAttributes },
+  messages: Array<{ attributes: MessageAttributes }>,
+): string[] {
+  const ids = [
+    thread.attributes.participant_a_owner_id,
+    thread.attributes.participant_b_owner_id,
+    ...messages.map((message) => message.attributes.sender_owner_id),
+  ];
+
+  return Array.from(new Set(ids.filter((id): id is string => Boolean(id))));
+}
+
+function ownerIdsForThreadList(
+  peers: Array<ThreadPeer>,
+): string[] {
+  return Array.from(
+    new Set(
+      peers
+        .map((peer) => peer.ownerId)
+        .filter((id): id is string => Boolean(id)),
+    ),
+  );
+}
+
+interface ThreadPeer {
+  ownerId?: string | null;
+  channelId?: string | null;
 }
 
-function formatThreadRecord(thread: {
-  id: string;
-  attributes: ThreadAttributes;
-}): Record<string, string> {
+function threadPeer(attrs: ThreadAttributes, actor: WhoamiActor): ThreadPeer {
+  const side = threadActorSide(attrs, actor);
+
+  if (side === "a") {
+    return {
+      ownerId: attrs.participant_b_owner_id,
+      channelId: attrs.participant_b_channel_id,
+    };
+  }
+
+  if (side === "b") {
+    return {
+      ownerId: attrs.participant_a_owner_id,
+      channelId: attrs.participant_a_channel_id,
+    };
+  }
+
   return {
-    id: thread.id,
-    mailboxType: thread.attributes.mailbox_type,
-    status: thread.attributes.status,
-    lastMessageAt: thread.attributes.last_message_at ?? "",
-    openedAt: thread.attributes.opened_at ?? "",
-    expiresAt: thread.attributes.expires_at ?? "",
-    participantASeenAt: thread.attributes.participant_a_seen_at ?? "",
-    participantAArchivedAt: thread.attributes.participant_a_archived_at ?? "",
-    participantABlockedAt: thread.attributes.participant_a_blocked_at ?? "",
-    participantAResolvedAt: thread.attributes.participant_a_resolved_at ?? "",
-    participantBSeenAt: thread.attributes.participant_b_seen_at ?? "",
-    participantBArchivedAt: thread.attributes.participant_b_archived_at ?? "",
-    participantBBlockedAt: thread.attributes.participant_b_blocked_at ?? "",
-    participantBResolvedAt: thread.attributes.participant_b_resolved_at ?? "",
+    ownerId: attrs.participant_a_owner_id,
+    channelId: attrs.participant_a_channel_id,
   };
 }
+
+function threadActorSide(
+  attrs: ThreadAttributes,
+  actor: WhoamiActor,
+): "a" | "b" | undefined {
+  if (actor.type === "channel") {
+    if (attrs.participant_a_channel_id === actor.id) {
+      return "a";
+    }
+
+    if (attrs.participant_b_channel_id === actor.id) {
+      return "b";
+    }
+  }
+
+  const ownerId = actor.type === "user" ? actor.id : actor.owner_id;
+
+  if (attrs.participant_a_owner_id === ownerId) {
+    return "a";
+  }
+
+  if (attrs.participant_b_owner_id === ownerId) {
+    return "b";
+  }
+
+  return undefined;
+}
+
+function formatThreadPeer(
+  peer: ThreadPeer | undefined,
+  publicUsers: Map<string, string>,
+): string {
+  if (!peer) {
+    return "-";
+  }
+
+  if (peer.channelId) {
+    return formatActor("channel", peer.channelId);
+  }
+
+  return formatUserActor(peer.ownerId, publicUsers);
+}
+
+function publicUserHandlesById(
+  users: Array<{ id: string; attributes: { public_handle?: string | null } }>,
+): Map<string, string> {
+  const handles = new Map<string, string>();
+
+  for (const user of users) {
+    const handle = user.attributes.public_handle?.trim();
+
+    if (handle) {
+      handles.set(user.id, `@${handle}`);
+    }
+  }
+
+  return handles;
+}

package/src/commands/post.ts

@@ -9,8 +9,14 @@ import {
 import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import {
+  formatTimestamp,
+  joinBlocks,
+  renderBodyBlock,
+  renderFields,
+} from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
-import type { PostAttributes } from "../types/api";
+import type { PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -36,12 +42,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              channelId,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post, { channelId, title: "Published post" }),
       );
       return;
     }
@@ -105,11 +106,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post, { title: "Updated post" }),
       );
       return;
     }
@@ -141,11 +138,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -170,11 +163,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -189,11 +178,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -208,7 +193,13 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         return;
       }
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderShareToken("Issued post share token", response),
+      );
       return;
     }
 
@@ -253,3 +244,37 @@ function printPostCollection(
     })),
   );
 }
+
+function renderPostDetail(
+  post: { id: string; attributes: PostAttributes },
+  options: { title?: string; channelId?: string } = {},
+): string {
+  return joinBlocks([
+    options.title ?? `Post ${post.id}`,
+    renderFields([
+      ["ID", post.id],
+      ["Channel", options.channelId],
+      ["Source", post.attributes.source],
+      [
+        "Inserted",
+        post.attributes.inserted_at
+          ? formatTimestamp(post.attributes.inserted_at)
+          : undefined,
+      ],
+      [
+        "Updated",
+        post.attributes.updated_at
+          ? formatTimestamp(post.attributes.updated_at)
+          : undefined,
+      ],
+    ]),
+    "Body\n" + renderBodyBlock(post.attributes.body),
+  ]);
+}
+
+function renderShareToken(title: string, response: ShareTokenResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}

package/src/lib/client.ts

@@ -142,6 +142,12 @@ export class ClankmatesClient {
     );
   }
 
+  async listPublicUsersById(ids: string[]) {
+    const path = withRepeatedQuery(`${API_PREFIX}/public/users/by-id`, "ids[]", ids);
+
+    return this.requestCollection<UserAttributes>(path, {});
+  }
+
   async listChannels(input: { limit?: number; cursor?: string } = {}) {
     return this.requestCollection<ChannelAttributes>(
       withQuery(`${API_PREFIX}/channels`, {
@@ -814,3 +820,14 @@ function withQuery(
   const query = search.toString();
   return query ? `${path}?${query}` : path;
 }
+
+function withRepeatedQuery(path: string, key: string, values: string[]): string {
+  const search = new URLSearchParams();
+
+  for (const value of values) {
+    search.append(key, value);
+  }
+
+  const query = search.toString();
+  return query ? `${path}?${query}` : path;
+}

package/src/lib/human.ts

@@ -0,0 +1,134 @@
+export type FieldValue = string | number | boolean | null | undefined;
+
+export function formatEmpty(value: FieldValue): string {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+
+  return String(value);
+}
+
+export function formatTimestamp(value?: string | null): string {
+  if (!value) {
+    return "-";
+  }
+
+  const timestamp = Date.parse(value);
+
+  if (Number.isNaN(timestamp)) {
+    return value;
+  }
+
+  return formatLocalTimestamp(new Date(timestamp));
+}
+
+export function shortId(id?: string | null): string {
+  if (!id) {
+    return "-";
+  }
+
+  return id.length > 12 ? `${id.slice(0, 8)}...` : id;
+}
+
+export function renderFields(fields: Array<[label: string, value: FieldValue]>): string {
+  const visibleFields = fields.filter(([, value]) => value !== undefined);
+
+  if (visibleFields.length === 0) {
+    return "";
+  }
+
+  const labelWidth = Math.max(...visibleFields.map(([label]) => label.length));
+
+  return visibleFields
+    .map(([label, value]) => `${label.padEnd(labelWidth)}  ${formatEmpty(value)}`)
+    .join("\n");
+}
+
+export function renderSection(title: string, body: string): string {
+  const trimmed = body.trimEnd();
+
+  if (!trimmed) {
+    return "";
+  }
+
+  return `${title}\n${trimmed}`;
+}
+
+export function renderBullets(items: string[]): string {
+  if (items.length === 0) {
+    return "-";
+  }
+
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function indent(text: string, spaces = 2): string {
+  const prefix = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? `${prefix}${line}` : ""))
+    .join("\n");
+}
+
+export function renderBodyBlock(body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n").trimEnd();
+
+  if (!normalized) {
+    return indent("(empty)");
+  }
+
+  return indent(normalized);
+}
+
+export function renderPagination(nextCursor?: string | null): string {
+  return nextCursor ? `More results: --cursor ${nextCursor}` : "";
+}
+
+export function joinBlocks(blocks: Array<string | undefined | null | false>): string {
+  return blocks.filter(Boolean).join("\n\n");
+}
+
+export function renderTokenAction(input: {
+  title: string;
+  id?: string | null;
+  name?: string | null;
+  token?: string | null;
+  issuedAt?: string | null;
+  expiresAt?: string | null;
+}): string {
+  return joinBlocks([
+    input.title,
+    renderFields([
+      ["ID", input.id],
+      ["Name", input.name],
+      ["Token", input.token],
+      ["Issued", input.issuedAt ? formatTimestamp(input.issuedAt) : undefined],
+      ["Expires", input.expiresAt ? formatTimestamp(input.expiresAt) : undefined],
+    ]),
+  ]);
+}
+
+function formatLocalTimestamp(value: Date): string {
+  const year = value.getFullYear();
+  const month = padDatePart(value.getMonth() + 1);
+  const day = padDatePart(value.getDate());
+  const hours = padDatePart(value.getHours());
+  const minutes = padDatePart(value.getMinutes());
+  const seconds = padDatePart(value.getSeconds());
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${formatTimezoneOffset(value)}`;
+}
+
+function formatTimezoneOffset(value: Date): string {
+  const offsetMinutes = -value.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteMinutes = Math.abs(offsetMinutes);
+  const hours = padDatePart(Math.floor(absoluteMinutes / 60));
+  const minutes = padDatePart(absoluteMinutes % 60);
+
+  return `${sign}${hours}:${minutes}`;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, "0");
+}

package/src/types/api.ts

@@ -44,7 +44,8 @@ export interface JsonApiDocument<TAttributes extends object> {
 export type AccessKeyScope = "master" | "read_only";
 
 export interface UserAttributes {
-  email: string;
+  email?: string;
+  public_profile_id?: string;
   public_handle?: string | null;
 }
 
@@ -95,6 +96,10 @@ export interface InboxSender {
 export interface ThreadAttributes {
   mailbox_type: MailboxType;
   status: ThreadStatus;
+  participant_a_owner_id?: string | null;
+  participant_a_channel_id?: string | null;
+  participant_b_owner_id?: string | null;
+  participant_b_channel_id?: string | null;
   opened_at?: string | null;
   expires_at?: string | null;
   last_message_at?: string;
@@ -112,6 +117,9 @@ export interface ThreadAttributes {
 
 export interface MessageAttributes {
   body: string;
+  sender_owner_id?: string | null;
+  sender_channel_id?: string | null;
+  thread_id?: string | null;
   context_post_id?: string | null;
   inserted_at?: string;
 }