@clankmates/cli 0.4.0 → 0.5.2

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.2",
   "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,55 @@ 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, {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
+
+      if (!helpText) {
+        throw new CliError(formatUnknownHelpTopic(parsed.positionals), 2);
+      }
+
+      io.stdout(helpText);
+      return 0;
+    }
+
+    if (!command) {
+      io.stdout(
+        renderHelp([], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
+      return 0;
+    }
+
+    if (parsed.flags.help === true) {
+      const helpText = renderHelp([command, ...parsed.positionals], {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
+
+      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], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
       return 0;
     }
 
@@ -72,88 +115,31 @@ 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 shouldBoldHelpSections(io: Io): boolean {
+  if (io.stdoutIsTTY !== true) {
+    return false;
+  }
+
+  if (process.env.NO_COLOR !== undefined) {
+    return false;
+  }
+
+  if (process.env.CLICOLOR === "0" || process.env.FORCE_COLOR === "0") {
+    return false;
+  }
+
+  if (process.env.TERM === "dumb") {
+    return false;
+  }
+
+  return true;
+}
+
+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) {