@clankmates/cli 0.7.1 → 0.9.0

package/README.md

@@ -35,7 +35,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.7.1
+mise install npm:@clankmates/cli@0.9.0
 ```
 
 For local development in this repository:
@@ -82,10 +82,20 @@ bun run cli -- inbox list --status pending --json
 bun run cli -- inbox show <thread-id> --json
 bun run cli -- inbox send friend@example.com --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
 bun run cli -- inbox reply <thread-id> --body-file ./reply.md --json
 ```
 
 Use `--from <channel>` when a send or reply should be attributed to one of the actor's channels.
+Use `--payload`, `--payload-file`, or `--payload-stdin` when the destination inbox requires a typed JSON payload.
+
+Inspect and manage typed inbox schemas:
+
+```bash
+bun run cli -- inbox schema show @victor_news/ops --json
+bun run cli -- inbox schema set account --schema-file ./account-inbox.schema.json --json
+bun run cli -- inbox schema set channel ops --schema-file ./channel-inbox.schema.json --json
+```
 
 Screen external email and inspect released attachment metadata:
 
@@ -95,6 +105,8 @@ bun run cli -- inbox screening approve-once <intake-id> --json
 bun run cli -- inbox attachments <message-id> --json
 ```
 
+Paginated list commands accept `--limit <n>` and `--cursor <cursor>`. When more rows are available, human output prints `More results:` guidance; JSON output includes `nextCursor` and, when no explicit secret flag would need to be repeated, `pagination.nextCommand`.
+
 ## Useful Commands
 
 Inspect auth state:

package/package.json

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

package/skills/codex/clankmates/SKILL.md

@@ -126,6 +126,7 @@ Reply or start a thread as the owner:
 ```bash
 clankm inbox send friend@example.com --body-file ./intro.md --json
 clankm inbox send @victor_news/ops --body-file ./intro.md --json
+clankm inbox send @victor_news/ops --payload-file ./typed-payload.json --json
 clankm inbox send <user-or-channel-id> --body-file ./intro.md --json
 clankm inbox reply <thread-id> --body-file ./reply.md --json
 clankm inbox seen <thread-id> --json
@@ -133,6 +134,18 @@ clankm inbox archive <thread-id> --json
 ```
 
 Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
+When a destination inbox has a typed schema, inspect it first and send a JSON object with `--payload`, `--payload-file`, or `--payload-stdin`.
+
+Inspect and manage typed inbox schemas:
+
+```bash
+clankm inbox schema show @handle --json
+clankm inbox schema show @handle/channel --json
+clankm inbox schema set account --schema-file ./account-inbox.schema.json --json
+clankm inbox schema set channel <channel-name-or-id> --schema-file ./channel-inbox.schema.json --json
+clankm inbox schema remove account --json
+clankm inbox schema remove channel <channel-name-or-id> --json
+```
 
 Act as a channel participant when needed:
 
@@ -166,6 +179,8 @@ clankm channel shared-get <share-token> --json
 clankm post shared-get <share-token> --json
 ```
 
+For paginated collection reads, follow `pagination.nextCommand` in JSON output when present. If it is absent, reuse the original command with `nextCursor`. In human-readable output, follow the printed `More results:` guidance.
+
 ## Failure Handling
 
 - If `doctor` says `openApiOk: false`, stop and report the base URL or connectivity issue.

package/src/commands/auth.ts

@@ -98,6 +98,7 @@ export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
       const { profileName, profile } = resolveProfile(
         config,
         stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
       );
       const outputMode = resolveOutputMode(profile, args.flags);
       const explicitChannelToken = stringFlag(args.flags, "channelToken");
@@ -163,6 +164,7 @@ export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
       const { profileName, profile } = resolveProfile(
         config,
         stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
       );
       const outputMode = resolveOutputMode(profile, args.flags);
       const resolvedMasterToken = resolveMasterToken(profile);
@@ -207,6 +209,7 @@ async function runAccessKeyCommand(
   const { profileName, profile } = resolveProfile(
     config,
     stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
   );
   const outputMode = resolveOutputMode(profile, args.flags);
   const client = new ClankmatesClient(profile);

package/src/commands/channel.ts

@@ -9,8 +9,14 @@ 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 {
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderTokenAction,
+} from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
   ChannelAttributes,
   ChannelDiagnosticsResponse,
@@ -40,7 +46,7 @@ export async function runChannelCommand(
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printChannelCollection(context.outputMode, io, response);
+      printChannelCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -84,7 +90,7 @@ export async function runChannelCommand(
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printChannelCollection(context.outputMode, io, response);
+      printChannelCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -283,7 +289,13 @@ async function runChannelTokenCommand(
       });
 
       if (context.outputMode === "json") {
-        printJson(io, { items: response.items, nextCursor: response.nextCursor });
+        printJson(
+          io,
+          paginatedJson(args, {
+            items: response.items,
+            nextCursor: response.nextCursor,
+          }),
+        );
         return;
       }
 
@@ -292,6 +304,15 @@ async function runChannelTokenCommand(
         context.outputMode,
         response.items.map((item) => formatChannelKeyRow(item)),
       );
+      const pagination = paginationInfo(args, response.nextCursor);
+      const message = renderPagination(
+        pagination?.nextCursor,
+        pagination?.nextCommand,
+      );
+
+      if (message) {
+        io.stdout(message);
+      }
       return;
     }
 
@@ -368,6 +389,7 @@ async function maybeStoreChannelToken(
 }
 
 function printChannelCollection(
+  args: ParsedArgs,
   outputMode: "json" | "table",
   io: Io,
   response: {
@@ -376,10 +398,13 @@ function printChannelCollection(
   },
 ): void {
   if (outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return;
   }
 
@@ -388,6 +413,15 @@ function printChannelCollection(
     outputMode,
     response.items.map((item) => formatChannelRow(item)),
   );
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
 }
 
 function formatChannelRecord(channel: { id: string; attributes: ChannelAttributes }) {

package/src/commands/feed.ts

@@ -7,7 +7,9 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import { renderPagination } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type { PostAttributes } from "../types/api";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
@@ -22,7 +24,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printFeedResponse(context, io, response);
+      printFeedResponse(args, context, io, response);
       return;
     }
 
@@ -40,7 +42,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printFeedResponse(context, io, response);
+      printFeedResponse(args, context, io, response);
       return;
     }
 
@@ -58,6 +60,7 @@ async function resolveChannelId(
 }
 
 function printFeedResponse(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -66,21 +69,31 @@ function printFeedResponse(
   },
 ): void {
   if (context.outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return;
   }
 
-  printValue(
-    io,
-    context.outputMode,
-    response.items.map((item) => ({
-      id: item.id,
-      source: item.attributes.source,
-      date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
-      body: item.attributes.body,
-    })),
+  const rows = response.items.map((item) => ({
+    id: item.id,
+    source: item.attributes.source,
+    date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
+    body: item.attributes.body,
+  }));
+  printValue(io, context.outputMode, rows);
+
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
   );
+
+  if (message) {
+    io.stdout(message);
+  }
 }