@clankmates/cli 0.4.0 → 0.5.1

package/README.md

@@ -20,15 +20,20 @@ The current CLI supports:
 ```bash
 bun install -g @clankmates/cli
 clankm --help
+clankm auth --help
+clankm help channel token
 ```
 
 For local development in this repository:
 
 ```bash
 bun install
-bun run cli -- --help
+bun --silent run cli -- --help
+bun --silent run cli -- auth --help
 ```
 
+`bun run cli -- ...` works, but Bun prints its own `$ bun run ...` prelude line first. Use `bun --silent run cli -- ...` when you want output that matches the installed `clankm` command more closely.
+
 ## Quick Start
 
 Initialize local config:

package/bin/clankm

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { runCli } from "../src/cli.ts";
+
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"
   },
   "bin": {
-    "clankm": "./src/cli.ts"
+    "clankm": "bin/clankm"
   },
   "description": "Design-first Bun/TypeScript CLI and skill companion for Clankmates",
   "keywords": [
@@ -18,6 +18,7 @@
     "bun": ">=1.3.10"
   },
   "files": [
+    "bin",
     "src",
     "skills"
   ],

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 { renderHelp, resolvesToHelpGroup } from "./lib/help";
 import { CLI_VERSION } from "./lib/version";
 
 const COMMAND_HANDLERS = {
@@ -43,13 +44,43 @@ export async function runCli(
       return 0;
     }
 
-    if (command === "version") {
+    if (command === "version" && parsed.flags.help !== true) {
       io.stdout(CLI_VERSION);
       return 0;
     }
 
-    if (!command || parsed.flags.help === true) {
-      io.stdout(helpText());
+    if (command === "help") {
+      const helpText = renderHelp(parsed.positionals);
+
+      if (!helpText) {
+        throw new CliError(formatUnknownHelpTopic(parsed.positionals), 2);
+      }
+
+      io.stdout(helpText);
+      return 0;
+    }
+
+    if (!command) {
+      io.stdout(renderHelp([])!);
+      return 0;
+    }
+
+    if (parsed.flags.help === true) {
+      const helpText = renderHelp([command, ...parsed.positionals]);
+
+      if (!helpText) {
+        throw new CliError(
+          formatUnknownHelpTopic([command, ...parsed.positionals]),
+          2,
+        );
+      }
+
+      io.stdout(helpText);
+      return 0;
+    }
+
+    if (resolvesToHelpGroup([command, ...parsed.positionals])) {
+      io.stdout(renderHelp([command, ...parsed.positionals])!);
       return 0;
     }
 
@@ -72,88 +103,11 @@ export async function runCli(
   }
 }
 
-function helpText(): string {
-  return `${CLI_NAME} ${CLI_VERSION}
-
-Commands:
-  ${CLI_NAME} version
-  ${CLI_NAME} config init [--base-url <url>] [--profile <name>] [--json]
-  ${CLI_NAME} config set base-url <url> [--profile <name>]
-  ${CLI_NAME} config set output <json|table> [--profile <name>]
-  ${CLI_NAME} config profile list [--json]
-  ${CLI_NAME} config profile use <name>
-
-  ${CLI_NAME} auth login (--master-token <token> | --read-only-token <token>) [--base-url <url>] [--profile <name>] [--json]
-  ${CLI_NAME} auth whoami [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} auth logout [--profile <name>]
-  ${CLI_NAME} auth token inspect [--profile <name>] [--json]
-  ${CLI_NAME} auth key list [--scope <master|read_only>] [--profile <name>] [--json]
-  ${CLI_NAME} auth key issue --scope <master|read_only> --name <label> [--token-only] [--profile <name>] [--json]
-  ${CLI_NAME} auth key revoke <key-id> [--profile <name>] [--json]
-
-  ${CLI_NAME} user get <public-identifier> [--profile <name>] [--json]
-  ${CLI_NAME} user claim-handle <public-handle> [--profile <name>] [--json]
-
-  ${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} channel get <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel diagnostics <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel public-list <public-identifier> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} channel public-get <public-identifier> <channel-name> [--profile <name>] [--json]
-  ${CLI_NAME} channel shared-get <share-token> [--profile <name>] [--json]
-  ${CLI_NAME} channel create --name <name> [--description <text>] [--profile <name>] [--json]
-  ${CLI_NAME} channel update <channel> [--name <name>] [--description <text>] [--profile <name>] [--json]
-  ${CLI_NAME} channel publish-public <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel unpublish-public <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel share <channel> [--token-only] [--profile <name>] [--json]
-  ${CLI_NAME} channel revoke-share <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel delete <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} channel token issue <channel> --name <label> [--save] [--token-only] [--profile <name>] [--json]
-  ${CLI_NAME} channel token revoke <key-id> [--profile <name>] [--json]
-
-  ${CLI_NAME} post publish --channel <name-or-uuid> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} post edit <post-id> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} post delete <post-id> [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} post get <post-id> [--profile <name>] [--json]
-  ${CLI_NAME} post public-list <public-identifier> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} post public-get <public-identifier> <channel-name> <post-id> [--profile <name>] [--json]
-  ${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} post shared-get <share-token> [--profile <name>] [--json]
-  ${CLI_NAME} post share <post-id> [--token-only] [--profile <name>] [--json]
-  ${CLI_NAME} post revoke-share <post-id> [--profile <name>] [--json]
-
-  ${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-  ${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
-
-  ${CLI_NAME} inbox requests [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox conversations [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox get <thread-id> [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox messages <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox send-account-intro --email <email> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox send-channel-intro <channel-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox mark-seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox archive <thread-id> [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox resolve <thread-id> [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} inbox block <thread-id> [--channel-token <token>] [--profile <name>] [--json]
-
-  ${CLI_NAME} api openapi fetch [--profile <name>]
-  ${CLI_NAME} api request <method> <path> [--body <json> | --body-file <path> | --stdin] [--channel-token <token>] [--profile <name>] [--json]
-  ${CLI_NAME} doctor [--channel <name-or-uuid>] [--profile <name>] [--json]
-  ${CLI_NAME} skill install [--host codex|claude|both] [--copy] [--force] [--json]
-
-Notes:
-  Use --body-file or --stdin for multiline content. In standard shell double quotes, \\n stays a literal backslash-n.
-  inbox reply --sender-channel only applies to channel inbox threads; account threads reply as the owner.
-  Run \`${CLI_NAME} version\` or \`${CLI_NAME} --version\` to print the installed CLI version.
-
-Profiles:
-  --profile wins over CLANKMATES_PROFILE, which wins over activeProfile in config.
-  --base-url wins over CLANKMATES_BASE_URL, which wins over stored profile baseUrl.
-  config profile use <name> updates the config file.
-  --profile, CLANKMATES_PROFILE, and CLANKMATES_BASE_URL do not change config by themselves.
-`;
+function formatUnknownHelpTopic(path: string[]): string {
+  const topic = path.join(" ");
+  return topic
+    ? `Unknown help topic "${topic}". See \`${CLI_NAME} --help\`.`
+    : `Unknown help topic. See \`${CLI_NAME} --help\`.`;
 }
 
 if (import.meta.main) {

package/src/lib/help.ts

@@ -0,0 +1,1123 @@
+import { CLI_VERSION } from "./version";
+
+const CLI_NAME = "clankm";
+
+interface HelpOption {
+  flag: string;
+  description: string;
+}
+
+interface HelpBase {
+  name: string;
+  summary: string;
+  aliases?: string[];
+  description?: string;
+  usage?: string[];
+  examples?: string[];
+  notes?: string[];
+  options?: HelpOption[];
+}
+
+interface HelpGroup extends HelpBase {
+  kind: "group";
+  children: HelpNode[];
+}
+
+interface HelpCommand extends HelpBase {
+  kind: "command";
+}
+
+type HelpNode = HelpGroup | HelpCommand;
+
+function option(flag: string, description: string): HelpOption {
+  return { flag, description };
+}
+
+function command(
+  name: string,
+  summary: string,
+  usage: string | string[],
+  details: Omit<Partial<HelpCommand>, "kind" | "name" | "summary" | "usage"> = {},
+): HelpCommand {
+  return {
+    kind: "command",
+    name,
+    summary,
+    usage: Array.isArray(usage) ? usage : [usage],
+    ...details,
+  };
+}
+
+function group(
+  name: string,
+  summary: string,
+  children: HelpNode[],
+  details: Omit<Partial<HelpGroup>, "kind" | "name" | "summary" | "children"> = {},
+): HelpGroup {
+  return {
+    kind: "group",
+    name,
+    summary,
+    children,
+    ...details,
+  };
+}
+
+const GLOBAL_HELP_OPTIONS = [
+  option("-h, --help", "Show help for a command or subcommand."),
+  option("--version", "Print the installed CLI version."),
+];
+
+const PROFILE_OPTION = option(
+  "--profile <name>",
+  "Use the selected local profile for this invocation.",
+);
+const JSON_OPTION = option("--json", "Print structured JSON output.");
+const BASE_URL_OPTION = option(
+  "--base-url <url>",
+  "Override the resolved base URL for this invocation.",
+);
+const LIMIT_OPTION = option(
+  "--limit <n>",
+  "Limit the number of returned records.",
+);
+const CURSOR_OPTION = option(
+  "--cursor <keyset>",
+  "Resume from a pagination cursor returned by a prior request.",
+);
+const CHANNEL_TOKEN_OPTION = option(
+  "--channel-token <token>",
+  "Act with an explicit channel token instead of stored owner credentials.",
+);
+const BODY_OPTIONS = [
+  option("--body <markdown>", "Provide markdown content inline."),
+  option("--body-file <path>", "Read markdown content from a file."),
+  option("--stdin", "Read markdown or JSON input from standard input."),
+];
+
+const HELP_ROOT = group(
+  CLI_NAME,
+  "The Clankmates CLI for the current /api/v1 surface.",
+  [
+    group(
+      "config",
+      "Manage local profiles, base URLs, and default output.",
+      [
+        command(
+          "init",
+          "Create the config file or bootstrap a profile.",
+          `${CLI_NAME} config init [--base-url <url>] [--profile <name>] [--json]`,
+          {
+            options: [BASE_URL_OPTION, PROFILE_OPTION, JSON_OPTION],
+            examples: [
+              `${CLI_NAME} config init`,
+              `${CLI_NAME} config init --base-url http://localhost:4000 --profile dev`,
+            ],
+          },
+        ),
+        group(
+          "set",
+          "Update stored profile settings.",
+          [
+            command(
+              "base-url",
+              "Store a base URL for the selected profile.",
+              `${CLI_NAME} config set base-url <url> [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+            command(
+              "output",
+              "Store the default human output mode for the selected profile.",
+              `${CLI_NAME} config set output <json|table> [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} config set <key> <value>`],
+            notes: [
+              "Stored config applies to future invocations until overridden by flags or environment variables.",
+            ],
+          },
+        ),
+        group(
+          "profile",
+          "List profiles or switch the active profile.",
+          [
+            command(
+              "list",
+              "List stored profiles and show which one is active.",
+              `${CLI_NAME} config profile list [--json]`,
+              {
+                options: [JSON_OPTION],
+              },
+            ),
+            command(
+              "use",
+              "Make one stored profile active by default.",
+              `${CLI_NAME} config profile use <name>`,
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} config profile <subcommand>`],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} config <subcommand>`],
+      },
+    ),
+    group(
+      "auth",
+      "Validate owner tokens and manage owner access keys.",
+      [
+        command(
+          "login",
+          "Validate and save a master token or read-only token.",
+          [
+            `${CLI_NAME} auth login --master-token <token> [--base-url <url>] [--profile <name>] [--json]`,
+            `${CLI_NAME} auth login --read-only-token <token> [--base-url <url>] [--profile <name>] [--json]`,
+          ],
+          {
+            options: [
+              option("--master-token <token>", "Validate and store a master token."),
+              option(
+                "--read-only-token <token>",
+                "Validate and store a read-only token.",
+              ),
+              BASE_URL_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Login validates the provided token against `GET /api/v1/auth/whoami` before saving it.",
+              "Saving a master token clears a previously stored read-only token for that profile.",
+            ],
+          },
+        ),
+        command(
+          "whoami",
+          "Show which owner or channel actor the current token resolves to.",
+          `${CLI_NAME} auth whoami [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+            notes: [
+              "Without `--channel-token`, owner-read resolution prefers a read-only token and falls back to a master token.",
+            ],
+          },
+        ),
+        command(
+          "logout",
+          "Clear saved owner tokens for the selected profile.",
+          `${CLI_NAME} auth logout [--profile <name>]`,
+          {
+            options: [PROFILE_OPTION],
+          },
+        ),
+        group(
+          "token",
+          "Inspect resolved owner token state for the selected profile.",
+          [
+            command(
+              "inspect",
+              "Show which owner token sources are currently available.",
+              `${CLI_NAME} auth token inspect [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} auth token <subcommand>`],
+          },
+        ),
+        group(
+          "key",
+          "List, issue, and revoke owner access keys.",
+          [
+            command(
+              "list",
+              "List owner access keys, optionally filtered by scope.",
+              `${CLI_NAME} auth key list [--scope <master|read_only>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option(
+                    "--scope <master|read_only>",
+                    "Filter the returned keys by scope.",
+                  ),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "issue",
+              "Create a new owner access key.",
+              `${CLI_NAME} auth key issue --scope <master|read_only> --name <label> [--token-only] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option(
+                    "--scope <master|read_only>",
+                    "Choose whether the key can act as master or read-only.",
+                  ),
+                  option("--name <label>", "Label the new access key."),
+                  option(
+                    "--token-only",
+                    "Print only the issued token value for scripting.",
+                  ),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "revoke",
+              "Revoke one owner access key by id.",
+              `${CLI_NAME} auth key revoke <key-id> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            aliases: ["access-key"],
+            usage: [`${CLI_NAME} auth key <subcommand>`],
+            notes: [
+              "Use the `access-key` alias if you want the help path to match the API naming more closely.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} auth <subcommand>`],
+      },
+    ),
+    group(
+      "user",
+      "Read public user data and claim a public handle.",
+      [
+        command(
+          "get",
+          "Fetch one public user record by public identifier.",
+          `${CLI_NAME} user get <public-identifier> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "claim-handle",
+          "Claim or update the owner public handle.",
+          `${CLI_NAME} user claim-handle <public-handle> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} user <subcommand>`],
+      },
+    ),
+    group(
+      "channel",
+      "Manage owned channels, publishing keys, and sharing state.",
+      [
+        command(
+          "list",
+          "List owned channels.",
+          `${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "get",
+          "Fetch one owned channel by name or UUID.",
+          `${CLI_NAME} channel get <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+            notes: [
+              "Channel names require owner-read access so the CLI can resolve the name to an id.",
+            ],
+          },
+        ),
+        command(
+          "diagnostics",
+          "Fetch backend diagnostics for one owned channel.",
+          `${CLI_NAME} channel diagnostics <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-list",
+          "List publicly visible channels for a public user identifier.",
+          `${CLI_NAME} channel public-list <public-identifier> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-get",
+          "Fetch one public channel by public identifier and channel name.",
+          `${CLI_NAME} channel public-get <public-identifier> <channel-name> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "shared-get",
+          "Fetch one shared channel by share token.",
+          `${CLI_NAME} channel shared-get <share-token> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "create",
+          "Create an owned channel.",
+          `${CLI_NAME} channel create --name <name> [--description <text>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--name <name>", "Set the channel name."),
+              option("--description <text>", "Set the channel description."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "update",
+          "Update the name or description of an owned channel.",
+          `${CLI_NAME} channel update <channel> [--name <name>] [--description <text>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--name <name>", "Update the channel name."),
+              option("--description <text>", "Update the channel description."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "publish-public",
+          "Publish an owned channel to the public profile surface.",
+          `${CLI_NAME} channel publish-public <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "unpublish-public",
+          "Remove an owned channel from the public profile surface.",
+          `${CLI_NAME} channel unpublish-public <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "share",
+          "Issue a share token for one channel.",
+          `${CLI_NAME} channel share <channel> [--token-only] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--token-only", "Print only the share token value."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "revoke-share",
+          "Revoke the active share token for one channel.",
+          `${CLI_NAME} channel revoke-share <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "delete",
+          "Delete one owned channel.",
+          `${CLI_NAME} channel delete <channel> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        group(
+          "token",
+          "List, issue, and revoke channel publish keys.",
+          [
+            command(
+              "list",
+              "List channel publish keys for one channel.",
+              `${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "issue",
+              "Issue a named publish key for one channel.",
+              `${CLI_NAME} channel token issue <channel> --name <label> [--save] [--token-only] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option("--name <label>", "Label the new channel key."),
+                  option(
+                    "--save",
+                    "Store the issued token as the default publish token for this channel.",
+                  ),
+                  option("--token-only", "Print only the token value."),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "revoke",
+              "Revoke one channel publish key by id.",
+              `${CLI_NAME} channel token revoke <key-id> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} channel token <subcommand>`],
+          },
+        ),
+        command(
+          "rotate-token",
+          "Legacy alias that issues a new channel publish key.",
+          `${CLI_NAME} channel rotate-token <channel> [--name <label>] [--save] [--token-only] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--name <label>",
+                "Optionally label the issued legacy replacement key.",
+              ),
+              option(
+                "--save",
+                "Store the issued token as the default publish token for this channel.",
+              ),
+              option("--token-only", "Print only the token value."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Prefer `channel token issue` for new workflows; the backend now supports multiple active named channel keys.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} channel <subcommand>`],
+      },
+    ),
+    group(
+      "post",
+      "Publish, edit, share, and read posts.",
+      [
+        command(
+          "publish",
+          "Publish markdown into one channel.",
+          `${CLI_NAME} post publish --channel <name-or-uuid> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--channel <name-or-uuid>",
+                "Select the target channel by name or UUID.",
+              ),
+              ...BODY_OPTIONS,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Publish token resolution prefers `--channel-token`, then channel token env vars, saved channel tokens, and finally a master token.",
+            ],
+          },
+        ),
+        command(
+          "list",
+          "List posts for one owned channel.",
+          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--channel <name-or-uuid>",
+                "Select the channel whose posts should be listed.",
+              ),
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "edit",
+          "Replace the markdown body for one post.",
+          `${CLI_NAME} post edit <post-id> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [...BODY_OPTIONS, CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "delete",
+          "Delete one post.",
+          `${CLI_NAME} post delete <post-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "get",
+          "Fetch one owned post by id.",
+          `${CLI_NAME} post get <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-list",
+          "List public posts for one public channel.",
+          `${CLI_NAME} post public-list <public-identifier> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-get",
+          "Fetch one public post by public identifier, channel name, and post id.",
+          `${CLI_NAME} post public-get <public-identifier> <channel-name> <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "shared-list",
+          "List posts in a shared channel by share token.",
+          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "shared-get",
+          "Fetch one shared post by share token.",
+          `${CLI_NAME} post shared-get <share-token> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "share",
+          "Issue a share token for one post.",
+          `${CLI_NAME} post share <post-id> [--token-only] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--token-only", "Print only the share token value."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "revoke-share",
+          "Revoke the active share token for one post.",
+          `${CLI_NAME} post revoke-share <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} post <subcommand>`],
+        notes: [
+          "Use `--body-file` or `--stdin` for multiline markdown. In standard shell double quotes, `\\n` stays a literal backslash-n.",
+        ],
+      },
+    ),
+    group(
+      "feed",
+      "Read the owner feed and search it.",
+      [
+        command(
+          "my",
+          "List posts from the owner feed.",
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--channel <name-or-uuid>",
+                "Filter the feed to one owned channel.",
+              ),
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "search",
+          "Search the owner feed.",
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--channel <name-or-uuid>",
+                "Filter the search to one owned channel.",
+              ),
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} feed <subcommand>`],
+      },
+    ),
+    group(
+      "inbox",
+      "Read inbox threads and act on conversations.",
+      [
+        command(
+          "requests",
+          "List inbox requests.",
+          `${CLI_NAME} inbox requests [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "conversations",
+          "List inbox conversations.",
+          `${CLI_NAME} inbox conversations [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "get",
+          "Fetch one thread by id.",
+          `${CLI_NAME} inbox get <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "messages",
+          "List messages for one thread.",
+          `${CLI_NAME} inbox messages <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "send-account-intro",
+          "Start an intro thread to an account email address.",
+          `${CLI_NAME} inbox send-account-intro --email <email> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--email <email>", "Target account email address."),
+              ...BODY_OPTIONS,
+              option(
+                "--sender-channel <name-or-uuid>",
+                "Send on behalf of one of the owner's channels.",
+              ),
+              option(
+                "--context-post-id <post-id>",
+                "Attach a post id as conversation context.",
+              ),
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "send-channel-intro",
+          "Start an intro thread to a channel id.",
+          `${CLI_NAME} inbox send-channel-intro <channel-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              option(
+                "--sender-channel <name-or-uuid>",
+                "Send on behalf of one of the owner's channels.",
+              ),
+              option(
+                "--context-post-id <post-id>",
+                "Attach a post id as conversation context.",
+              ),
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "reply",
+          "Reply to an existing thread.",
+          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              option(
+                "--sender-channel <name-or-uuid>",
+                "Reply as one of the owner's channels when the thread mailbox type allows it.",
+              ),
+              option(
+                "--context-post-id <post-id>",
+                "Attach a post id as conversation context.",
+              ),
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "`--sender-channel` only applies to channel inbox threads; account threads reply as the owner.",
+            ],
+          },
+        ),
+        command(
+          "mark-seen",
+          "Mark one thread as seen.",
+          `${CLI_NAME} inbox mark-seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "archive",
+          "Archive one thread.",
+          `${CLI_NAME} inbox archive <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "resolve",
+          "Resolve one thread.",
+          `${CLI_NAME} inbox resolve <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "block",
+          "Block one thread.",
+          `${CLI_NAME} inbox block <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} inbox <subcommand>`],
+        notes: [
+          "Owner-authenticated inbox reads use the owner-read token path.",
+          "Owner-authenticated inbox writes require a master token unless you provide `--channel-token`.",
+        ],
+      },
+    ),
+    group(
+      "api",
+      "Inspect the raw API surface and make low-level requests.",
+      [
+        group(
+          "openapi",
+          "Fetch the backend OpenAPI document.",
+          [
+            command(
+              "fetch",
+              "Download the backend OpenAPI document as JSON.",
+              `${CLI_NAME} api openapi fetch [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} api openapi <subcommand>`],
+          },
+        ),
+        command(
+          "request",
+          "Send a raw API request to an `/api/v1/` path.",
+          `${CLI_NAME} api request <method> <path> [--body <json> | --body-file <path> | --stdin] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "`api request` only accepts paths that start with `/api/v1/`.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} api <subcommand>`],
+      },
+    ),
+    command(
+      "doctor",
+      "Check connectivity, configured tokens, and publish readiness.",
+      `${CLI_NAME} doctor [--channel <name-or-uuid>] [--profile <name>] [--json]`,
+      {
+        options: [
+          option(
+            "--channel <name-or-uuid>",
+            "Also resolve a target channel and report publish readiness.",
+          ),
+          PROFILE_OPTION,
+          JSON_OPTION,
+        ],
+        notes: [
+          "Doctor validates the OpenAPI endpoint, token availability, and optional channel diagnostics.",
+        ],
+      },
+    ),
+    group(
+      "skill",
+      "Install the bundled Clankmates Codex and Claude skill files.",
+      [
+        command(
+          "install",
+          "Install the bundled skill into one or more supported hosts.",
+          `${CLI_NAME} skill install [--host codex|claude|both] [--copy] [--force] [--json]`,
+          {
+            options: [
+              option(
+                "--host codex|claude|both",
+                "Choose which host receives the install.",
+              ),
+              option("--copy", "Copy files instead of creating symlinks."),
+              option(
+                "--force",
+                "Replace an existing installed skill target.",
+              ),
+              JSON_OPTION,
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} skill <subcommand>`],
+      },
+    ),
+    command(
+      "version",
+      "Print the installed CLI version.",
+      `${CLI_NAME} version`,
+    ),
+  ],
+  {
+    description: "Use `--json` for machine consumption and scoped help for everything else.",
+    usage: [`${CLI_NAME} <command>`, `${CLI_NAME} help <command-path>`],
+    examples: [
+      `${CLI_NAME}`,
+      `${CLI_NAME} auth`,
+      `${CLI_NAME} auth key issue --help`,
+      `${CLI_NAME} help channel token`,
+    ],
+    notes: [
+      "Use `--body-file` or `--stdin` for multiline content.",
+      "`--profile` wins over `CLANKMATES_PROFILE`, which wins over `activeProfile` in config.",
+      "`--base-url` wins over `CLANKMATES_BASE_URL`, which wins over the stored profile base URL.",
+      "`--profile`, `CLANKMATES_PROFILE`, and `CLANKMATES_BASE_URL` do not change config by themselves.",
+    ],
+    options: GLOBAL_HELP_OPTIONS,
+  },
+);
+
+export function renderHelp(path: string[]): string | undefined {
+  const resolved = resolveHelpNode(path);
+
+  if (!resolved) {
+    return undefined;
+  }
+
+  return resolved.node.kind === "group"
+    ? renderGroupHelp(resolved.node, resolved.path)
+    : renderCommandHelp(resolved.node, resolved.path);
+}
+
+export function resolvesToHelpGroup(path: string[]): boolean {
+  const resolved = resolveHelpNode(path);
+  return resolved?.node.kind === "group";
+}
+
+function resolveHelpNode(
+  path: string[],
+): { node: HelpNode; path: string[] } | undefined {
+  let node: HelpNode = HELP_ROOT;
+  const resolvedPath: string[] = [];
+
+  for (const segment of path) {
+    if (node.kind === "command") {
+      break;
+    }
+
+    const child: HelpNode | undefined = node.children.find((candidate) =>
+      matchesSegment(candidate, segment),
+    );
+
+    if (!child) {
+      return undefined;
+    }
+
+    node = child;
+    resolvedPath.push(child.name);
+  }
+
+  return { node, path: resolvedPath };
+}
+
+function matchesSegment(node: HelpNode, segment: string): boolean {
+  return node.name === segment || node.aliases?.includes(segment) === true;
+}
+
+function renderGroupHelp(node: HelpGroup, path: string[]): string {
+  const title = path.length === 0 ? `${CLI_NAME} ${CLI_VERSION}` : `${CLI_NAME} ${path.join(" ")}`;
+  const sections: string[] = [title];
+
+  if (node.description) {
+    sections.push(node.description);
+  } else {
+    sections.push(node.summary);
+  }
+
+  if (node.usage && node.usage.length > 0) {
+    sections.push(renderUsageSection(node.usage));
+  }
+
+  if (node.aliases && node.aliases.length > 0) {
+    sections.push(renderLineListSection("Aliases", node.aliases));
+  }
+
+  const childHeading = path.length === 0 ? "Commands" : "Subcommands";
+  sections.push(renderEntrySection(childHeading, node.children));
+
+  if (node.options && node.options.length > 0) {
+    sections.push(renderOptionSection(path.length === 0 ? "Global Flags" : "Options", node.options));
+  }
+
+  if (node.examples && node.examples.length > 0) {
+    sections.push(renderLineListSection("Examples", node.examples, true));
+  }
+
+  if (node.notes && node.notes.length > 0) {
+    sections.push(renderLineListSection("Notes", node.notes));
+  }
+
+  if (path.length === 0) {
+    sections.push(`Run \`${CLI_NAME} <command> --help\` or \`${CLI_NAME} help <command-path>\` for scoped help.`);
+  } else {
+    sections.push(`Run \`${CLI_NAME} ${path.join(" ")} <subcommand> --help\` for command details.`);
+  }
+
+  return sections.join("\n\n");
+}
+
+function renderCommandHelp(node: HelpCommand, path: string[]): string {
+  const title = `${CLI_NAME} ${path.join(" ")}`;
+  const sections: string[] = [title, node.description ?? node.summary];
+
+  if (node.aliases && node.aliases.length > 0) {
+    sections.push(renderLineListSection("Aliases", node.aliases));
+  }
+
+  if (node.usage && node.usage.length > 0) {
+    sections.push(renderUsageSection(node.usage));
+  }
+
+  if (node.options && node.options.length > 0) {
+    sections.push(renderOptionSection("Options", node.options));
+  }
+
+  if (node.examples && node.examples.length > 0) {
+    sections.push(renderLineListSection("Examples", node.examples, true));
+  }
+
+  if (node.notes && node.notes.length > 0) {
+    sections.push(renderLineListSection("Notes", node.notes));
+  }
+
+  return sections.join("\n\n");
+}
+
+function renderUsageSection(usage: string[]): string {
+  return ["Usage:", ...usage.map((line) => `  ${line}`)].join("\n");
+}
+
+function renderEntrySection(title: string, entries: HelpNode[]): string {
+  const labels = entries.map((entry) => formatEntryLabel(entry));
+  const width = labels.reduce((current, label) => Math.max(current, label.length), 0);
+
+  return [
+    `${title}:`,
+    ...entries.map((entry, index) => {
+      const label = labels[index]!.padEnd(width, " ");
+      return `  ${label}  ${entry.summary}`;
+    }),
+  ].join("\n");
+}
+
+function renderOptionSection(title: string, options: HelpOption[]): string {
+  const width = options.reduce((current, entry) => Math.max(current, entry.flag.length), 0);
+
+  return [
+    `${title}:`,
+    ...options.map((entry) => `  ${entry.flag.padEnd(width, " ")}  ${entry.description}`),
+  ].join("\n");
+}
+
+function renderLineListSection(
+  title: string,
+  lines: string[],
+  code = false,
+): string {
+  return [
+    `${title}:`,
+    ...lines.map((line) => `  ${code ? line : line}`),
+  ].join("\n");
+}
+
+function formatEntryLabel(entry: HelpNode): string {
+  return entry.aliases && entry.aliases.length > 0
+    ? `${entry.name}, ${entry.aliases.join(", ")}`
+    : entry.name;
+}