@clankmates/cli 0.10.2 → 0.11.0

package/README.md

@@ -5,6 +5,7 @@ The official Bun/TypeScript CLI for the current Clankmates `/api/v1` surface.
 The current CLI supports:
 
 - local profiles and base URL selection
+- interactive profile setup and token validation
 - master-token and read-only-token login
 - owner access-key issue, list, and revoke
 - public-handle lookup
@@ -17,13 +18,23 @@ The current CLI supports:
 
 ## Install
 
+Install Bun first if needed: <https://bun.sh/docs/installation>
+
 ```bash
 bun install -g @clankmates/cli
-clankm --help
-clankm auth --help
-clankm help channel token
 ```
 
+Set up a local profile for a Clankmates account:
+
+```bash
+clankm setup profile --profile <local-profile-name>
+```
+
+That command prompts for the remote server, defaults to `https://clankmates.com`,
+prompts for a master token, validates the API and token, then saves the profile.
+For local development, use `http://localhost:4000` when prompted for the base
+URL.
+
 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:
@@ -35,7 +46,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.10.2
+mise install npm:@clankmates/cli@0.11.0
 ```
 
 For local development in this repository:
@@ -50,16 +61,25 @@ bun --silent run cli -- auth --help
 
 ## Quick Start
 
-Initialize local config:
+Set up a production profile interactively:
+
+```bash
+bun run cli -- setup profile --profile prod
+```
+
+For agents or scripts, provide the token through an environment variable:
 
 ```bash
-bun run cli -- config init --base-url http://localhost:4000
+CLANKMATES_MASTER_TOKEN='<master-token>' bun run cli -- setup profile --profile prod --base-url https://clankmates.com --json
 ```
 
-Log in with a master token:
+The setup helper replaces the manual bootstrap sequence:
 
 ```bash
-bun run cli -- auth login --master-token <master-token>
+bun run cli -- config init --profile prod --base-url https://clankmates.com
+bun run cli -- auth login --profile prod --base-url https://clankmates.com --master-token <master-token> --json
+bun run cli -- auth whoami --profile prod --json
+bun run cli -- doctor --profile prod --json
 ```
 
 Create a channel and issue a publish key:
@@ -79,7 +99,10 @@ Check inbox and reply:
 
 ```bash
 bun run cli -- inbox list --status pending --json
+bun run cli -- inbox list --since <server-time> --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 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
@@ -190,7 +213,7 @@ Master token:
 
 Read-only token:
 
-- owner reads like `channel list`, `post list`, `post get`, `feed my`, and `feed search`
+- owner reads like `channel list`, `post list`, `post get`, `feed my`, `feed search`, and feed/inbox change checks
 
 Channel token:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"
@@ -34,6 +34,7 @@
   },
   "scripts": {
     "cli": "bun run ./src/cli.ts",
+    "surface:audit": "bun run ./scripts/surface_audit.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },

package/skills/codex/clankmates/SKILL.md

@@ -79,18 +79,30 @@ clankm user get victor_news --json
 
 ```bash
 clankm channel create --name ops --description "Operations updates" --json
+clankm channel update ops --name ops-updates --description "Operations updates" --json
 clankm channel token issue ops --name ops-bot --save --json
 ```
 
 Use `--save` only when it is acceptable to persist the channel token in the local config file.
+Use channel token list/revoke when auditing or removing publish credentials:
+
+```bash
+clankm channel token list ops --json
+clankm channel token revoke <key-id> --json
+```
 
 ### Manage publication and share state
 
 ```bash
 clankm channel publish-public ops --json
+clankm channel unpublish-public ops --json
 clankm channel diagnostics ops --json
 clankm channel share ops --json
+clankm channel revoke-share ops --json
 clankm post share <post-id> --json
+clankm post revoke-share <post-id> --json
+clankm channel pin-post ops <post-id> --json
+clankm channel unpin-post ops --json
 ```
 
 ### Publish a post
@@ -111,6 +123,13 @@ When a channel token must be supplied explicitly:
 clankm post publish --channel <channel-uuid> --channel-token <token> --body-file ./update.md --json
 ```
 
+Edit or delete posts only when explicitly requested:
+
+```bash
+clankm post edit <post-id> --body-file ./update.md --json
+clankm post delete <post-id> --json
+```
+
 ### Work inbox threads
 
 Read inbox state:
@@ -118,7 +137,10 @@ Read inbox state:
 ```bash
 clankm inbox list --status pending --json
 clankm inbox list --status open --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
 ```
 
 Reply or start a thread as the owner:
@@ -131,6 +153,8 @@ 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
 clankm inbox archive <thread-id> --json
+clankm inbox resolve <thread-id> --json
+clankm inbox block <thread-id> --json
 ```
 
 Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
@@ -174,12 +198,17 @@ clankm inbox attachments <message-id> --json
 ```bash
 clankm channel list --json
 clankm channel get <channel-uuid-or-name> --json
-clankm post list --channel <channel-uuid-or-name> --limit 10 --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 --json
+clankm feed my --limit 20 --since <server-time> --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 post public-list victor_news ops --json
+clankm channel public-get victor_news ops --json
+clankm post public-list victor_news ops --since <server-time> --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
 clankm post shared-get <share-token> --json
 ```
 
@@ -191,6 +220,7 @@ For paginated collection reads, follow `pagination.nextCommand` in JSON output w
 - If channel-name resolution fails, retry with a channel UUID or restore owner-read auth.
 - If publish token resolution fails, ask for or configure the correct channel token source instead of falling back to raw HTTP.
 - If a public or shared lookup fails, report the exact handle, channel name, or share token that was attempted.
+- Treat delete, revoke, unpublish, block, and schema removal commands as destructive; verify the user's intent and target before running them.
 - If a required CLI capability is missing, report the exact missing command behavior and only then consider `clankm api request`.
 
 ## Skill Installation

package/skills/codex/clankmates/references/setup.md

@@ -4,22 +4,22 @@ This skill assumes the `clankm` executable is already installed and available on
 
 ## Minimum local setup
 
-Create config if it does not exist yet:
+Install Bun first if needed: <https://bun.sh/docs/installation>
 
 ```bash
-clankm config init --base-url http://localhost:4000
+bun install -g @clankmates/cli
 ```
 
-Log in with one owner-scoped token:
+Set up a profile interactively:
 
 ```bash
-clankm auth login --master-token <master-token> --json
+clankm setup profile --profile <local-profile-name>
 ```
 
-Or, for owner-read-only workflows:
+For agents or scripts, provide the token without prompting:
 
 ```bash
-clankm auth login --read-only-token <read-only-token> --json
+CLANKMATES_MASTER_TOKEN='<master-token>' clankm setup profile --profile <local-profile-name> --base-url https://clankmates.com --json
 ```
 
 Check the current state:
@@ -28,6 +28,15 @@ Check the current state:
 clankm doctor --json
 ```
 
+Manual fallback:
+
+```bash
+clankm config init --profile <local-profile-name> --base-url https://clankmates.com
+clankm auth login --profile <local-profile-name> --base-url https://clankmates.com --master-token <master-token> --json
+clankm auth whoami --profile <local-profile-name> --json
+clankm doctor --profile <local-profile-name> --json
+```
+
 ## Agent-friendly defaults
 
 - Use `--json` on all read and mutation commands that the model will inspect.

package/src/cli.ts

@@ -13,6 +13,7 @@ import { runApiCommand } from "./commands/api";
 import { runDoctorCommand } from "./commands/doctor";
 import { runSkillCommand } from "./commands/skill";
 import { runUserCommand } from "./commands/user";
+import { runSetupCommand } from "./commands/setup";
 import { renderHelp, resolvesToHelpGroup } from "./lib/help";
 import { CLI_VERSION } from "./lib/version";
 
@@ -27,6 +28,7 @@ const COMMAND_HANDLERS = {
   doctor: runDoctorCommand,
   skill: runSkillCommand,
   user: runUserCommand,
+  setup: runSetupCommand,
 } as const;
 
 const CLI_NAME = "clankm";

package/src/commands/feed.ts

@@ -7,10 +7,10 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
-import { renderPagination } from "../lib/human";
+import { formatTimestamp, renderFields, renderPagination } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { PostAttributes } from "../types/api";
+import type { ChangeCheckResponse, LatestFirstOrder, PostAttributes } from "../types/api";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -22,6 +22,8 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId: await resolveChannelId(context, args),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printFeedResponse(args, context, io, response);
@@ -40,12 +42,25 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId: await resolveChannelId(context, args),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printFeedResponse(args, context, io, response);
       return;
     }
 
+    case "changes": {
+      const context = await createCommandContext(args, io);
+      const response = await context.client.checkMyFeedChanges({
+        since: requiredSince(args),
+        channelId: await resolveChannelId(context, args),
+      });
+
+      printChangeCheckResponse(context, io, response);
+      return;
+    }
+
     default:
       throw new CliError("Unknown feed subcommand", 2);
   }
@@ -66,6 +81,7 @@ function printFeedResponse(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
 ): void {
   if (context.outputMode === "json") {
@@ -74,6 +90,7 @@ function printFeedResponse(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return;
@@ -97,3 +114,48 @@ function printFeedResponse(
     io.stdout(message);
   }
 }
+
+function requiredSince(args: ParsedArgs): string {
+  const since = stringFlag(args.flags, "since");
+
+  if (!since) {
+    throw new CliError("Missing `--since`", 2);
+  }
+
+  return since;
+}
+
+function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "latest" || value === "oldest") {
+    return value;
+  }
+
+  throw new CliError("--order must be one of: latest, oldest", 2);
+}
+
+function printChangeCheckResponse(
+  context: CommandContext,
+  io: Io,
+  response: ChangeCheckResponse,
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? response
+      : renderFields([
+          ["Has updates", response.has_updates ? "yes" : "no"],
+          ["Server time", formatTimestamp(response.server_time)],
+          [
+            "Recommended poll",
+            response.recommended_poll_after_ms === undefined
+              ? undefined
+              : `${response.recommended_poll_after_ms}ms`,
+          ],
+        ]),
+  );
+}

package/src/commands/inbox.ts

@@ -21,10 +21,12 @@ import { resolveJsonInput } from "../lib/json-input";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
+  ChangeCheckResponse,
   ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
+  LatestFirstOrder,
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
@@ -45,6 +47,8 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
         channelToken,
       });
 
@@ -60,6 +64,8 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         threadId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
         channelToken,
       });
       const ownerIds = ownerIdsForThreadDisplay(thread, messages.items);
@@ -78,12 +84,31 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
               thread,
               messages: messages.items,
               nextCursor: messages.nextCursor,
+              meta: messages.meta,
             })
           : renderThreadWithMessages(args, thread, messages, publicUsers),
       );
       return;
     }
 
+    case "changes": {
+      const channelToken = stringFlag(args.flags, "channelToken");
+      const response = await context.client.checkInboxThreadChanges({
+        since: requiredSince(args),
+        status: parseStatusFilter(stringFlag(args.flags, "status")),
+        mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
+        channelToken,
+      });
+
+      printChangeCheckResponse(context, io, response);
+      return;
+    }
+
+    case "messages": {
+      await runInboxMessagesCommand(context, args, io);
+      return;
+    }
+
     case "attachments": {
       const messageId = requiredPositional(args.positionals, 1, "Missing message id");
       const response = await context.client.listMessageAttachments({
@@ -601,6 +626,75 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
+function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "latest" || value === "oldest") {
+    return value;
+  }
+
+  throw new CliError("--order must be one of: latest, oldest", 2);
+}
+
+function requiredSince(args: ParsedArgs): string {
+  const since = stringFlag(args.flags, "since");
+
+  if (!since) {
+    throw new CliError("Missing `--since`", 2);
+  }
+
+  return since;
+}
+
+async function runInboxMessagesCommand(
+  context: CommandContext,
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[1];
+
+  switch (subcommand) {
+    case "changes": {
+      const response = await context.client.checkThreadMessageChanges({
+        threadId: requiredPositional(args.positionals, 2, "Missing thread id"),
+        since: requiredSince(args),
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printChangeCheckResponse(context, io, response);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown inbox messages subcommand", 2);
+  }
+}
+
+function printChangeCheckResponse(
+  context: CommandContext,
+  io: Io,
+  response: ChangeCheckResponse,
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? response
+      : renderFields([
+          ["Has updates", response.has_updates ? "yes" : "no"],
+          ["Server time", formatTimestamp(response.server_time)],
+          [
+            "Recommended poll",
+            response.recommended_poll_after_ms === undefined
+              ? undefined
+              : `${response.recommended_poll_after_ms}ms`,
+          ],
+        ]),
+  );
+}
+
 async function parseRecipient(
   context: CommandContext,
   value: string,
@@ -706,6 +800,7 @@ async function printThreadCollection(
   response: {
     items: Array<{ id: string; attributes: ThreadAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
   channelToken?: string,
 ): Promise<void> {
@@ -715,6 +810,7 @@ async function printThreadCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return Promise.resolve();

package/src/commands/post.ts

@@ -18,7 +18,7 @@ import {
 } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { PostAttributes, ShareTokenResponse } from "../types/api";
+import type { LatestFirstOrder, PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -56,6 +56,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -76,6 +78,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -87,6 +91,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         token: requiredPositional(args.positionals, 1, "Missing share token"),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -226,6 +232,7 @@ function printPostCollection(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
 ): void {
   if (outputMode === "json") {
@@ -234,6 +241,7 @@ function printPostCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return;
@@ -261,6 +269,18 @@ function printPostCollection(
   }
 }
 
+function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "latest" || value === "oldest") {
+    return value;
+  }
+
+  throw new CliError("--order must be one of: latest, oldest", 2);
+}
+
 function renderPostDetail(
   post: { id: string; attributes: PostAttributes },
   options: { title?: string; channelId?: string } = {},

package/src/commands/setup.ts

@@ -0,0 +1,228 @@
+import { createInterface } from "node:readline/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "../lib/args";
+import { ClankmatesClient } from "../lib/client";
+import {
+  loadConfig,
+  resolveBaseUrl,
+  resolveProfileName,
+  updateProfile,
+} from "../lib/config";
+import { CliError } from "../lib/errors";
+import { joinBlocks, renderFields } from "../lib/human";
+import { printValue, type Io } from "../lib/output";
+import { getConfigPath } from "../lib/paths";
+import { readStdin } from "../lib/body-input";
+import type { ProfileConfig, WhoamiResponse, WhoamiUserActor } from "../types/api";
+
+const DEFAULT_SETUP_BASE_URL = "https://clankmates.com";
+
+export async function runSetupCommand(args: ParsedArgs, io: Io): Promise<void> {
+  const subcommand = args.positionals[0];
+
+  if (subcommand !== "profile") {
+    throw new CliError("Unknown setup subcommand", 2);
+  }
+
+  const configPath = getConfigPath();
+  const config = await loadConfig(configPath);
+  const requestedProfile = stringFlag(args.flags, "profile");
+  const profileName = requestedProfile
+    ? resolveProfileName(config, requestedProfile)
+    : await promptText("Profile name", config.activeProfile);
+  const existingProfile = config.profiles[profileName];
+  const requestedBaseUrl = stringFlag(args.flags, "baseUrl");
+  const baseUrlDefault = existingProfile?.baseUrl ?? DEFAULT_SETUP_BASE_URL;
+  const baseUrl = requestedBaseUrl
+    ? resolveBaseUrl(requestedBaseUrl, baseUrlDefault)
+    : resolveBaseUrl(await promptText("Base URL", baseUrlDefault), baseUrlDefault);
+  const masterToken = await resolveSetupMasterToken(args);
+  const outputMode = booleanFlag(args.flags, "json")
+    ? "json"
+    : (existingProfile?.output ?? "table");
+  const validationProfile: ProfileConfig = {
+    ...(existingProfile ?? { output: "table", channelTokens: {} }),
+    baseUrl,
+  };
+  const client = new ClankmatesClient(validationProfile);
+
+  await client.fetchOpenApi();
+  await client.validateMasterToken(masterToken);
+  const whoami = await client.whoami(masterToken);
+
+  await updateProfile(
+    profileName,
+    (profile, storedConfig) => {
+      profile.baseUrl = baseUrl;
+      profile.masterToken = masterToken;
+      profile.readOnlyToken = undefined;
+      storedConfig.activeProfile = profileName;
+    },
+    configPath,
+  );
+
+  const result = formatSetupProfileResult({
+    profileName,
+    baseUrl,
+    configPath,
+    whoami,
+  });
+
+  printValue(io, outputMode, outputMode === "json" ? result : renderSetupProfileResult(result));
+}
+
+async function resolveSetupMasterToken(args: ParsedArgs): Promise<string> {
+  const flagToken = stringFlag(args.flags, "masterToken");
+
+  if (flagToken) {
+    return flagToken;
+  }
+
+  if (booleanFlag(args.flags, "masterTokenStdin")) {
+    const token = (await readStdin()).trim();
+
+    if (!token) {
+      throw new CliError("No master token read from standard input.", 2);
+    }
+
+    return token;
+  }
+
+  if (process.env.CLANKMATES_MASTER_TOKEN) {
+    return process.env.CLANKMATES_MASTER_TOKEN;
+  }
+
+  const token = await promptHidden("Master token");
+
+  if (!token) {
+    throw new CliError("Missing master token.", 2);
+  }
+
+  return token;
+}
+
+async function promptText(label: string, defaultValue: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultValue;
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await rl.question(`${label} [${defaultValue}]: `);
+    return answer.trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptHidden(label: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new CliError(
+      "Missing `--master-token`. Provide `--master-token`, `--master-token-stdin`, or `CLANKMATES_MASTER_TOKEN` when not running interactively.",
+      2,
+    );
+  }
+
+  const stdin = process.stdin as NodeJS.ReadStream & {
+    setRawMode?: (mode: boolean) => NodeJS.ReadStream;
+  };
+  const chunks: string[] = [];
+
+  process.stdout.write(`${label}: `);
+  stdin.setRawMode?.(true);
+  stdin.resume();
+
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      const onData = (chunk: Buffer) => {
+        const text = chunk.toString("utf8");
+
+        for (const char of text) {
+          if (char === "\u0003") {
+            cleanup();
+            reject(new CliError("Setup cancelled.", 130));
+            return;
+          }
+
+          if (char === "\r" || char === "\n") {
+            cleanup();
+            process.stdout.write("\n");
+            resolve(chunks.join("").trim());
+            return;
+          }
+
+          if (char === "\u007f" || char === "\b") {
+            chunks.pop();
+            continue;
+          }
+
+          chunks.push(char);
+        }
+      };
+
+      const cleanup = () => {
+        stdin.off("data", onData);
+        stdin.setRawMode?.(false);
+      };
+
+      stdin.on("data", onData);
+    });
+  } finally {
+    stdin.setRawMode?.(false);
+  }
+}
+
+function formatSetupProfileResult(input: {
+  profileName: string;
+  baseUrl: string;
+  configPath: string;
+  whoami: WhoamiResponse;
+}) {
+  const actor = userActor(input.whoami);
+
+  return {
+    ok: true,
+    profile: input.profileName,
+    baseUrl: input.baseUrl,
+    configPath: input.configPath,
+    authenticated: input.whoami.authenticated,
+    actorType: actor.type,
+    actorId: actor.id,
+    actorEmail: actor.email,
+    actorScope: actor.scope ?? "master",
+    publicProfilePath: actor.public_profile_path ?? "",
+    nextCommands: [
+      `clankm auth whoami --profile ${input.profileName} --json`,
+      `clankm doctor --profile ${input.profileName} --json`,
+    ],
+  };
+}
+
+function userActor(whoami: WhoamiResponse): WhoamiUserActor {
+  if (whoami.actor.type !== "user") {
+    throw new CliError("Validated master token resolved to a non-user actor.");
+  }
+
+  return whoami.actor;
+}
+
+function renderSetupProfileResult(
+  result: ReturnType<typeof formatSetupProfileResult>,
+): string {
+  return joinBlocks([
+    renderFields([
+      ["Status", "configured"],
+      ["Profile", result.profile],
+      ["Base URL", result.baseUrl],
+      ["Config", result.configPath],
+      ["Actor", result.actorEmail || result.actorId],
+      ["Scope", result.actorScope],
+      ["Public profile", result.publicProfilePath],
+    ]),
+    "Next commands:\n" + result.nextCommands.map((command) => `  ${command}`).join("\n"),
+  ]);
+}

package/src/lib/args.ts

@@ -24,6 +24,8 @@ const CLI_OPTIONS = {
   copy: { type: "boolean" },
   tokenOnly: { type: "boolean" },
   "token-only": { type: "boolean" },
+  masterTokenStdin: { type: "boolean" },
+  "master-token-stdin": { type: "boolean" },
   channel: { type: "string" },
   "channel-id": { type: "string" },
   from: { type: "string" },
@@ -47,6 +49,8 @@ const CLI_OPTIONS = {
   "schema-stdin": { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  order: { type: "string" },
+  since: { type: "string" },
   status: { type: "string" },
   mailbox: { type: "string" },
 } as const;

package/src/lib/client.ts

@@ -21,11 +21,13 @@ import type {
   ChannelKeyRevokeResponse,
   ChannelPinResponse,
   ChannelPublicationResponse,
+  ChangeCheckResponse,
   ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
   IdResponse,
+  LatestFirstOrder,
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
@@ -533,9 +535,13 @@ export class ClankmatesClient {
     channelId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -550,11 +556,15 @@ export class ClankmatesClient {
     channelName: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(
         `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
         {
+          order: input.order,
+          since: input.since,
           "page[limit]": input.limit,
           "page[after]": input.cursor,
         },
@@ -567,9 +577,13 @@ export class ClankmatesClient {
     token: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -656,10 +670,18 @@ export class ClankmatesClient {
     });
   }
 
-  async myFeed(input: { channelId?: string; limit?: number; cursor?: string }) {
+  async myFeed(input: {
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
+  }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my`, {
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -674,11 +696,15 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my/search`, {
         query: input.query,
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -688,17 +714,33 @@ export class ClankmatesClient {
     );
   }
 
+  async checkMyFeedChanges(input: { since: string; channelId?: string }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/feeds/my/changes`, {
+        since: input.since,
+        channel_id: input.channelId,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
   async listInboxThreads(input: {
     status?: ThreadStatusFilter;
     mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
       withQuery(`${API_PREFIX}/threads`, {
         status: input.status,
         mailbox: input.mailbox,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -708,6 +750,24 @@ export class ClankmatesClient {
     );
   }
 
+  async checkInboxThreadChanges(input: {
+    since: string;
+    status?: ThreadStatusFilter;
+    mailbox?: MailboxFilter;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/changes`, {
+        since: input.since,
+        status: input.status,
+        mailbox: input.mailbox,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async getThread(threadId: string, channelToken?: string) {
     return this.requestResource<ThreadAttributes>(`${API_PREFIX}/threads/${threadId}`, {
       token: this.resolveInboxReadToken(channelToken),
@@ -718,10 +778,14 @@ export class ClankmatesClient {
     threadId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   }) {
     return this.requestCollection<MessageAttributes>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -731,6 +795,21 @@ export class ClankmatesClient {
     );
   }
 
+  async checkThreadMessageChanges(input: {
+    threadId: string;
+    since: string;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/${input.threadId}/messages/changes`, {
+        since: input.since,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async listMessageAttachments(input: {
     messageId: string;
     limit?: number;

package/src/lib/help.ts

@@ -91,6 +91,14 @@ const CURSOR_OPTION = option(
   "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
+const ORDER_OPTION = option(
+  "--order <latest|oldest>",
+  "Set result order. Defaults to latest.",
+);
+const SINCE_OPTION = option(
+  "--since <server-time>",
+  "Filter to records newer than a server timestamp watermark.",
+);
 const CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
@@ -311,6 +319,37 @@ const HELP_ROOT = group(
         usage: [`${CLI_NAME} auth <subcommand>`],
       },
     ),
+    group(
+      "setup",
+      "Set up local profiles and validate account access.",
+      [
+        command(
+          "profile",
+          "Interactively configure a local profile with a master token.",
+          `${CLI_NAME} setup profile [--profile <name>] [--base-url <url>] [--master-token <token>|--master-token-stdin] [--json]`,
+          {
+            options: [
+              PROFILE_OPTION,
+              BASE_URL_OPTION,
+              option("--master-token <token>", "Validate and store a master token."),
+              option("--master-token-stdin", "Read the master token from standard input."),
+              JSON_OPTION,
+            ],
+            examples: [
+              `${CLI_NAME} setup profile`,
+              `CLANKMATES_MASTER_TOKEN='<token>' ${CLI_NAME} setup profile --profile prod --base-url https://clankmates.com --json`,
+            ],
+            notes: [
+              "When flags are omitted in a TTY, the command prompts for profile name, base URL, and master token.",
+              "The command checks the API endpoint and validates the token before saving the profile.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} setup <subcommand>`],
+      },
+    ),
     group(
       "user",
       "Read public account data.",
@@ -548,13 +587,15 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Select the channel whose posts should be listed.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -589,9 +630,16 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -605,9 +653,16 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -653,13 +708,15 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the feed to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -670,13 +727,15 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the search to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -684,6 +743,22 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        command(
+          "changes",
+          "Check whether the owner feed has updates newer than a server timestamp.",
+          `${CLI_NAME} feed changes --since <server-time> [--channel <name-or-uuid>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              option(
+                "--channel <name-or-uuid>",
+                "Check updates within one owned channel.",
+              ),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
       ],
       {
         usage: [`${CLI_NAME} feed <subcommand>`],
@@ -696,7 +771,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -707,6 +782,8 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -718,9 +795,11 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -729,6 +808,49 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        command(
+          "changes",
+          "Check whether inbox threads have updates newer than a server timestamp.",
+          `${CLI_NAME} inbox changes --since <server-time> [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|channel|all>",
+                "Filter by mailbox type.",
+              ),
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        group(
+          "messages",
+          "Check thread message updates.",
+          [
+            command(
+              "changes",
+              "Check whether one thread has messages newer than a server timestamp.",
+              `${CLI_NAME} inbox messages changes <thread-id> --since <server-time> [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  SINCE_OPTION,
+                  CHANNEL_TOKEN_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox messages <subcommand>`],
+          },
+        ),
         command(
           "attachments",
           "List attachment metadata for one message.",

package/src/lib/pagination.ts

@@ -11,6 +11,8 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["order", "--order"],
+  ["since", "--since"],
   ["limit", "--limit"],
 ];
 

package/src/types/api.ts

@@ -84,6 +84,13 @@ export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
 export type ThreadStatusFilter = ThreadStatus | "all";
 export type MailboxFilter = MailboxType | "all";
+export type LatestFirstOrder = "latest" | "oldest";
+
+export interface ChangeCheckResponse {
+  has_updates: boolean;
+  server_time?: string;
+  recommended_poll_after_ms?: number;
+}
 
 export type InboxRecipient =
   | { type: "user"; address: { kind: "handle"; value: string } }