@clankmates/cli 0.10.1 → 0.10.3

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.1
+mise install npm:@clankmates/cli@0.10.3
 ```
 
 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:
@@ -92,11 +112,11 @@ Use `--payload`, `--payload-file`, or `--payload-stdin` when the destination inb
 Inspect and manage typed inbox schemas:
 
 ```bash
-bun run cli -- inbox schema show @victor_news/ops --json
-bun run cli -- inbox schema set account --schema-file ./account-inbox.schema.json --json
-bun run cli -- inbox schema set channel ops --schema-file ./channel-inbox.schema.json --json
-bun run cli -- inbox schema acceptance account screen-unknown-senders --json
-bun run cli -- inbox schema acceptance channel ops accept-valid-typed-email --json
+clankm inbox schema show @victor_news/ops --json
+clankm inbox schema set account --schema-file ./account-inbox.schema.json --json
+clankm inbox schema set channel ops --schema-file ./channel-inbox.schema.json --json
+clankm inbox schema acceptance account screen-unknown-senders --json
+clankm inbox schema acceptance channel ops accept-valid-typed-email --json
 ```
 
 Setting a typed inbox schema defaults that inbox to accept valid typed external email without sender screening. Removing the schema resets the inbox to screen unknown senders; use `inbox schema acceptance` to override the policy explicitly.

package/package.json

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

package/skills/codex/clankmates/SKILL.md

@@ -134,7 +134,7 @@ clankm inbox archive <thread-id> --json
 ```
 
 Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
-When a destination inbox has a typed schema, inspect it first and send a JSON object with `--payload`, `--payload-file`, or `--payload-stdin`.
+When a destination inbox has a typed schema, inspect public handle targets first with `clankm inbox schema show <@handle|@handle/channel> --json` and send a JSON object with `--payload`, `--payload-file`, or `--payload-stdin`.
 
 Inspect and manage typed inbox schemas:
 

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/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" },

package/src/lib/help.ts

@@ -311,6 +311,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.",
@@ -766,6 +797,7 @@ const HELP_ROOT = group(
             notes: [
               "Recipient addresses support `@handle`, `@handle/channel`, user UUIDs, and channel UUIDs.",
               "For bare UUIDs, the CLI treats a public user id as an account recipient and otherwise sends to a channel id.",
+              "Before sending to a typed inbox, inspect public handle targets with `clankm inbox schema show <@handle|@handle/channel> --json`.",
               "Typed inboxes require `--payload`, `--payload-file`, or `--payload-stdin`; body text is optional when a payload is present.",
             ],
           },