@clankmates/cli 0.11.1 → 0.12.0

package/README.md

@@ -47,7 +47,7 @@ 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.11.1
+mise install npm:@clankmates/cli@0.12.0
 ```
 
 For local development in this repository:
@@ -100,11 +100,12 @@ Check inbox and reply:
 
 ```bash
 bun run cli -- inbox list --status pending --json
+bun run cli -- inbox list --participant @friend_handle --query "release notes" --json
 bun run cli -- inbox list --since <server-time> --json
 bun run cli -- inbox list --since-cache --save-cache --json
 bun run cli -- inbox changes --since <server-time> --json
-bun run cli -- inbox show <thread-id> --json
-bun run cli -- inbox messages changes <thread-id> --since <server-time> --json
+bun run cli -- inbox show <thread-id> --before <timestamp> --json
+bun run cli -- inbox messages changes <thread-id> --since <server-time> --has-attachment --json
 bun run cli -- inbox send @friend_handle --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --payload-file ./typed-payload.json --json

package/package.json

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

package/skills/codex/clankmates/SKILL.md

@@ -137,10 +137,11 @@ Read inbox state:
 ```bash
 clankm inbox list --status pending --json
 clankm inbox list --status open --json
+clankm inbox list --participant @friend_handle --query "release notes" --json
 clankm inbox list --since <server-time> --json
 clankm inbox changes --since <server-time> --json
 clankm inbox show <thread-id> --json
-clankm inbox messages changes <thread-id> --since <server-time> --json
+clankm inbox messages changes <thread-id> --since <server-time> --has-attachment --json
 ```
 
 Reply or start a thread as the owner:
@@ -200,12 +201,12 @@ clankm channel list --json
 clankm channel get <channel-uuid-or-name> --json
 clankm post list --channel <channel-uuid-or-name> --limit 10 --since <server-time> --json
 clankm post get <post-id> --json
-clankm feed my --limit 20 --since <server-time> --json
+clankm feed my --limit 20 --since <server-time> --before <timestamp> --json
 clankm feed changes --since <server-time> --json
 clankm feed search "release notes" --limit 20 --since <server-time> --json
 clankm channel public-list victor_news --json
 clankm channel public-get victor_news ops --json
-clankm post public-list victor_news ops --since <server-time> --json
+clankm post public-list victor_news ops --since <server-time> --before <timestamp> --json
 clankm post public-get victor_news ops <post-id> --json
 clankm channel shared-get <share-token> --json
 clankm post shared-list <share-token> --since <server-time> --json

package/src/commands/feed.ts

@@ -40,6 +40,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -77,6 +78,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -280,6 +282,7 @@ async function maybeFeedMyScope(
     context,
     actorKey: await authenticatedActorKey(context),
     channelId,
+    before: stringFlag(args.flags, "before"),
   });
 }
 
@@ -298,6 +301,7 @@ async function maybeFeedSearchScope(
     actorKey: await authenticatedActorKey(context),
     query,
     channelId,
+    before: stringFlag(args.flags, "before"),
   });
 }
 

package/src/commands/inbox.ts

@@ -44,6 +44,7 @@ import type {
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
+  ParticipantScope,
   ThreadAttributes,
   ThreadStatusFilter,
   WhoamiActor,
@@ -59,12 +60,16 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       assertSinceFlags(args);
       const status = parseStatusFilter(stringFlag(args.flags, "status"));
       const mailbox = parseMailboxFilter(stringFlag(args.flags, "mailbox"));
+      const participantScope = parseParticipantScope(
+        stringFlag(args.flags, "participantScope"),
+      );
       const cacheScope = await maybeInboxThreadsScope(
         args,
         context,
         channelToken,
         status,
         mailbox,
+        participantScope,
       );
       const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.listInboxThreads({
@@ -72,8 +77,13 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         mailbox,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
+        participant: stringFlag(args.flags, "participant"),
+        participantScope,
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         channelToken,
       });
       const savedServerTimestamp = await maybeSaveCacheTimestamp(
@@ -111,8 +121,11 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         threadId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         channelToken,
       });
       const savedServerTimestamp = await maybeSaveCacheTimestamp(
@@ -152,18 +165,26 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       assertSinceFlags(args);
       const status = parseStatusFilter(stringFlag(args.flags, "status"));
       const mailbox = parseMailboxFilter(stringFlag(args.flags, "mailbox"));
+      const participantScope = parseParticipantScope(
+        stringFlag(args.flags, "participantScope"),
+      );
       const cacheScope = await maybeInboxThreadsScope(
         args,
         context,
         channelToken,
         status,
         mailbox,
+        participantScope,
       );
       const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.checkInboxThreadChanges({
         since: requiredSince(args, cachePlan, "inbox thread"),
         status,
         mailbox,
+        participant: stringFlag(args.flags, "participant"),
+        participantScope,
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         channelToken,
       });
       const savedServerTimestamp = await maybeSaveCacheTimestamp(
@@ -705,6 +726,18 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
+function parseParticipantScope(value: string | undefined): ParticipantScope | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "account" || value === "owner") {
+    return value;
+  }
+
+  throw new CliError("--participant-scope must be one of: account, owner", 2);
+}
+
 function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
   if (!value) {
     return undefined;
@@ -768,6 +801,8 @@ async function runInboxMessagesCommand(
       const response = await context.client.checkThreadMessageChanges({
         threadId,
         since: requiredSince(args, cachePlan, "inbox message"),
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         channelToken,
       });
       const savedServerTimestamp = await maybeSaveCacheTimestamp(
@@ -1138,6 +1173,7 @@ async function maybeInboxThreadsScope(
   channelToken: string | undefined,
   status: ThreadStatusFilter | undefined,
   mailbox: MailboxFilter | undefined,
+  participantScope: ParticipantScope | undefined,
 ): Promise<CacheScope | undefined> {
   if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
     return undefined;
@@ -1148,6 +1184,11 @@ async function maybeInboxThreadsScope(
     actorKey: await authenticatedActorKey(context, channelToken),
     status,
     mailbox,
+    participant: stringFlag(args.flags, "participant"),
+    participantScope,
+    query: stringFlag(args.flags, "query"),
+    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+    before: stringFlag(args.flags, "before"),
   });
 }
 
@@ -1165,6 +1206,9 @@ async function maybeInboxMessagesScope(
     context,
     actorKey: await authenticatedActorKey(context, channelToken),
     threadId,
+    query: stringFlag(args.flags, "query"),
+    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+    before: stringFlag(args.flags, "before"),
   });
 }
 

package/src/commands/post.ts

@@ -74,6 +74,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -119,6 +120,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelName,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -149,6 +151,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         token,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -391,6 +394,7 @@ async function maybeOwnedPostsScope(
     context,
     actorKey: await authenticatedActorKey(context),
     channelId,
+    before: stringFlag(args.flags, "before"),
   });
 }
 
@@ -404,7 +408,12 @@ function maybePublicPostsScope(
     return undefined;
   }
 
-  return publicPostsScope({ context, publicHandle, channelName });
+  return publicPostsScope({
+    context,
+    publicHandle,
+    channelName,
+    before: stringFlag(args.flags, "before"),
+  });
 }
 
 function maybeSharedPostsScope(
@@ -416,7 +425,11 @@ function maybeSharedPostsScope(
     return undefined;
   }
 
-  return sharedPostsScope({ context, shareToken });
+  return sharedPostsScope({
+    context,
+    shareToken,
+    before: stringFlag(args.flags, "before"),
+  });
 }
 
 function resolvedSince(

package/src/lib/args.ts

@@ -49,6 +49,7 @@ const CLI_OPTIONS = {
   "schema-stdin": { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  before: { type: "string" },
   order: { type: "string" },
   since: { type: "string" },
   sinceCache: { type: "boolean" },
@@ -57,6 +58,12 @@ const CLI_OPTIONS = {
   "save-cache": { type: "boolean" },
   status: { type: "string" },
   mailbox: { type: "string" },
+  participant: { type: "string" },
+  participantScope: { type: "string" },
+  "participant-scope": { type: "string" },
+  query: { type: "string" },
+  hasAttachment: { type: "boolean" },
+  "has-attachment": { type: "boolean" },
 } as const;
 
 type ParsedValue = string | boolean;

package/src/lib/cache.ts

@@ -336,14 +336,16 @@ export function feedMyScope(input: {
   context: CommandContext;
   actorKey: string;
   channelId?: string;
+  before?: string;
 }): CacheScope {
   const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: input.actorKey,
     resource: "feed:my",
-    parts: ["feed", "my", channel],
-    params: { channel },
+    parts: ["feed", "my", channel, before],
+    params: { channel, before },
   });
 }
 
@@ -352,14 +354,16 @@ export function feedSearchScope(input: {
   actorKey: string;
   query: string;
   channelId?: string;
+  before?: string;
 }): CacheScope {
   const channel = input.channelId ?? "all";
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: input.actorKey,
     resource: "feed:search",
-    parts: ["feed", "search", input.query, channel],
-    params: { query: input.query, channel },
+    parts: ["feed", "search", input.query, channel, before],
+    params: { query: input.query, channel, before },
   });
 }
 
@@ -368,15 +372,44 @@ export function inboxThreadsScope(input: {
   actorKey: string;
   status?: string;
   mailbox?: string;
+  participant?: string;
+  participantScope?: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
 }): CacheScope {
   const status = input.status ?? "default";
   const mailbox = input.mailbox ?? "default";
+  const participant = input.participant ?? "default";
+  const participantScope = input.participantScope ?? "default";
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: input.actorKey,
     resource: "inbox:threads",
-    parts: ["inbox", "threads", status, mailbox, input.actorKey],
-    params: { status, mailbox },
+    parts: [
+      "inbox",
+      "threads",
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: {
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      hasAttachment,
+      before,
+    },
   });
 }
 
@@ -384,13 +417,27 @@ export function inboxMessagesScope(input: {
   context: CommandContext;
   actorKey: string;
   threadId: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
 }): CacheScope {
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: input.actorKey,
     resource: "inbox:messages",
-    parts: ["inbox", "messages", input.threadId, input.actorKey],
-    params: { threadId: input.threadId },
+    parts: [
+      "inbox",
+      "messages",
+      input.threadId,
+      query,
+      String(hasAttachment),
+      before,
+      input.actorKey,
+    ],
+    params: { threadId: input.threadId, query, hasAttachment, before },
   });
 }
 
@@ -398,13 +445,15 @@ export function ownedPostsScope(input: {
   context: CommandContext;
   actorKey: string;
   channelId: string;
+  before?: string;
 }): CacheScope {
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: input.actorKey,
     resource: "posts:owned",
-    parts: ["posts", "owned", input.channelId],
-    params: { channelId: input.channelId },
+    parts: ["posts", "owned", input.channelId, before],
+    params: { channelId: input.channelId, before },
   });
 }
 
@@ -412,15 +461,18 @@ export function publicPostsScope(input: {
   context: CommandContext;
   publicHandle: string;
   channelName: string;
+  before?: string;
 }): CacheScope {
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: PUBLIC_ACTOR_KEY,
     resource: "posts:public",
-    parts: ["posts", "public", input.publicHandle, input.channelName],
+    parts: ["posts", "public", input.publicHandle, input.channelName, before],
     params: {
       publicHandle: input.publicHandle,
       channelName: input.channelName,
+      before,
     },
   });
 }
@@ -428,14 +480,16 @@ export function publicPostsScope(input: {
 export function sharedPostsScope(input: {
   context: CommandContext;
   shareToken: string;
+  before?: string;
 }): CacheScope {
   const shareTokenHash = hashValue(input.shareToken);
+  const before = input.before ?? "default";
   return scoped({
     context: input.context,
     actorKey: SHARED_ACTOR_KEY,
     resource: "posts:shared",
-    parts: ["posts", "shared", shareTokenHash],
-    params: { shareTokenHash },
+    parts: ["posts", "shared", shareTokenHash, before],
+    params: { shareTokenHash, before },
   });
 }
 

package/src/lib/client.ts

@@ -31,6 +31,7 @@ import type {
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
+  ParticipantScope,
   PostAttributes,
   ProfileConfig,
   ShareTokenResponse,
@@ -535,6 +536,7 @@ export class ClankmatesClient {
     channelId: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -542,6 +544,7 @@ export class ClankmatesClient {
       withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -556,6 +559,7 @@ export class ClankmatesClient {
     channelName: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -565,6 +569,7 @@ export class ClankmatesClient {
         {
           order: input.order,
           since: input.since,
+          before: input.before,
           "page[limit]": input.limit,
           "page[after]": input.cursor,
         },
@@ -577,6 +582,7 @@ export class ClankmatesClient {
     token: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -584,6 +590,7 @@ export class ClankmatesClient {
       withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -674,6 +681,7 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -682,6 +690,7 @@ export class ClankmatesClient {
         channel_id: input.channelId,
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -696,6 +705,7 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
   }) {
@@ -705,6 +715,7 @@ export class ClankmatesClient {
         channel_id: input.channelId,
         order: input.order,
         since: input.since,
+        before: input.before,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -731,8 +742,13 @@ export class ClankmatesClient {
     mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
+    participant?: string;
+    participantScope?: ParticipantScope;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
@@ -741,6 +757,11 @@ export class ClankmatesClient {
         mailbox: input.mailbox,
         order: input.order,
         since: input.since,
+        before: input.before,
+        participant: input.participant,
+        participant_scope: input.participantScope,
+        query: input.query,
+        has_attachment: input.hasAttachment,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -754,6 +775,10 @@ export class ClankmatesClient {
     since: string;
     status?: ThreadStatusFilter;
     mailbox?: MailboxFilter;
+    participant?: string;
+    participantScope?: ParticipantScope;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestAction<ChangeCheckResponse>(
@@ -761,6 +786,10 @@ export class ClankmatesClient {
         since: input.since,
         status: input.status,
         mailbox: input.mailbox,
+        participant: input.participant,
+        participant_scope: input.participantScope,
+        query: input.query,
+        has_attachment: input.hasAttachment,
       }),
       {
         token: this.resolveInboxReadToken(input.channelToken),
@@ -778,14 +807,20 @@ export class ClankmatesClient {
     threadId: string;
     limit?: number;
     cursor?: string;
+    before?: string;
     order?: LatestFirstOrder;
     since?: string;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestCollection<MessageAttributes>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages`, {
         order: input.order,
         since: input.since,
+        before: input.before,
+        query: input.query,
+        has_attachment: input.hasAttachment,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -798,11 +833,15 @@ export class ClankmatesClient {
   async checkThreadMessageChanges(input: {
     threadId: string;
     since: string;
+    query?: string;
+    hasAttachment?: boolean;
     channelToken?: string;
   }) {
     return this.requestAction<ChangeCheckResponse>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages/changes`, {
         since: input.since,
+        query: input.query,
+        has_attachment: input.hasAttachment,
       }),
       {
         token: this.resolveInboxReadToken(input.channelToken),
@@ -1132,7 +1171,7 @@ function looksLikeUuid(value: string): boolean {
 
 function withQuery(
   path: string,
-  params: Record<string, string | number | undefined>,
+  params: Record<string, string | number | boolean | undefined>,
 ): string {
   const search = new URLSearchParams();
 

package/src/lib/help.ts

@@ -91,6 +91,10 @@ const CURSOR_OPTION = option(
   "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
+const BEFORE_OPTION = option(
+  "--before <timestamp>",
+  "Only return records inserted or active before this server timestamp.",
+);
 const ORDER_OPTION = option(
   "--order <latest|oldest>",
   "Set result order. Defaults to latest.",
@@ -111,6 +115,22 @@ const CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
 );
+const INBOX_SEARCH_OPTIONS = [
+  option(
+    "--participant <@handle|@handle/channel>",
+    "Filter inbox threads by a visible participant.",
+  ),
+  option(
+    "--participant-scope <account|owner>",
+    "Choose how bare account handles are matched. Defaults to account.",
+  ),
+  option("--query <text>", "Filter inbox results by visible message body text."),
+  option("--has-attachment", "Only include threads or messages with attachments."),
+];
+const MESSAGE_SEARCH_OPTIONS = [
+  option("--query <text>", "Filter messages by body text."),
+  option("--has-attachment", "Only include messages with attachments."),
+];
 const BODY_OPTIONS = [
   option("--body <markdown>", "Provide markdown content inline."),
   option("--body-file <path>", "Read markdown content from a file."),
@@ -635,7 +655,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -644,6 +664,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -680,11 +701,12 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -705,11 +727,12 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -762,7 +785,7 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -771,6 +794,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -783,7 +807,7 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -792,6 +816,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -831,7 +856,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -842,8 +867,10 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -857,11 +884,13 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--query <text>] [--has-attachment] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              ...MESSAGE_SEARCH_OPTIONS,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -875,7 +904,7 @@ const HELP_ROOT = group(
         command(
           "changes",
           "Check whether inbox threads have updates newer than a server timestamp.",
-          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               SINCE_OPTION,
@@ -889,6 +918,7 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               CHANNEL_TOKEN_OPTION,
               PROFILE_OPTION,
               JSON_OPTION,
@@ -902,12 +932,13 @@ const HELP_ROOT = group(
             command(
               "changes",
               "Check whether one thread has messages newer than a server timestamp.",
-              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   SINCE_OPTION,
                   SINCE_CACHE_OPTION,
                   SAVE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
                   CHANNEL_TOKEN_OPTION,
                   PROFILE_OPTION,
                   JSON_OPTION,

package/src/lib/pagination.ts

@@ -11,14 +11,19 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["participant", "--participant"],
+  ["participantScope", "--participant-scope"],
   ["order", "--order"],
   ["since", "--since"],
+  ["before", "--before"],
+  ["query", "--query"],
   ["limit", "--limit"],
 ];
 
 const PAGINATION_BOOLEAN_FLAGS: Array<[key: string, flag: string]> = [
   ["sinceCache", "--since-cache"],
   ["saveCache", "--save-cache"],
+  ["hasAttachment", "--has-attachment"],
 ];
 
 export interface PaginationInfo {

package/src/types/api.ts

@@ -84,6 +84,7 @@ export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
 export type ThreadStatusFilter = ThreadStatus | "all";
 export type MailboxFilter = MailboxType | "all";
+export type ParticipantScope = "account" | "owner";
 export type LatestFirstOrder = "latest" | "oldest";
 
 export interface ChangeCheckResponse {