@clanker-chain/clanker-cli 2026.9.7-3 → 2026.9.7-4

package/bin/clanker.mjs

@@ -25,6 +25,13 @@ import {
 } from "../lib/identity-query.mjs";
 import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/resolve.mjs";
 import { runSetup } from "../lib/setup.mjs";
+import { runDoctor } from "../lib/doctor.mjs";
+import {
+  c,
+  confirmPlan,
+  exitCliError,
+  nextHint,
+} from "../lib/ui.mjs";
 
 function resolveFoundryBinary(name) {
   const home = os.homedir();
@@ -146,16 +153,17 @@ function usage() {
 
 Usage:
   clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--key-file path] [--force]
+  clanker doctor [--json]
   clanker init --preset sepolia|local [--force]
-  clanker whoami [--json] [--operator <label>] [--address 0x…]
-  clanker operator mint <label> [--json]
-  clanker operator transfer propose <label> <newOwner>
-  clanker operator transfer accept <label>
-  clanker bot mint <label> [operator] [--json]
+  clanker whoami [--json] [--operator <label>] [--address 0x…] [--with-bots]
+  clanker operator mint <label> [--json] [--yes]
+  clanker operator transfer propose <label> <newOwner> [--yes]
+  clanker operator transfer accept <label> [--yes]
+  clanker bot mint <label> [operator] [--json] [--yes]
   clanker bots [--json] [--operator <label>] [--address 0x…]
   clanker bot status <label> [--json]
-  clanker bot revoke <label> [--json]
-  clanker bot rotate <label> <newKeyAddress> [--json]
+  clanker bot revoke <label> [--json] [--yes]
+  clanker bot rotate <label> <newKeyAddress> [--json] [--yes]
   clanker init-openclaw
   clanker chain up|deploy|mint-operator|mint-bot|rotate-bot-key|revoke-bot ...
   clanker check mqtt <bot_id> <operator_id>
@@ -166,11 +174,9 @@ Profile:
   ~/.clanker/operator.json   label + owner + optional key pointer (never raw hex)
   ~/.clanker/keys/           bot keys (also written to ~/.openclaw/keys/)
 
-Humans: prefer \`clanker setup\` (detects Foundry/OpenClaw hints, writes profile).
-Key resolution (mutating commands):
-  --key > --key-file > OPERATOR_PRIVATE_KEY > profile keyFile > profile env
-  Anvil account #0 is allowed only on localhost RPC.
-  Reads (whoami/bots) can use profile owner without a signing key.
+Humans: \`clanker setup\` then \`clanker doctor\` / \`whoami\`.
+Mutates print a plan and confirm unless --yes or --json.
+whoami is fast by default; pass --with-bots to enrich child bots (or use \`clanker bots\`).
 
 See docs/operator-cli.md.
 `);
@@ -223,10 +229,14 @@ async function cmdWhoami(argv) {
     source = resolved.source;
     network = resolved.network;
   } catch (err) {
-    console.error(err.message);
-    process.exit(1);
+    exitCliError({
+      error: err.message,
+      because: "whoami needs an owner address from --address, a key, or operator.json",
+      try: ["clanker setup", "clanker doctor", "clanker whoami --address 0x…"],
+    });
   }
 
+  const withBots = hasFlag(argv, "--with-bots");
   const pub = await publicClientFromRpc(network.rpc);
   const preferred =
     flagValue(argv, "--operator") ?? loadOperator(network.home)?.label ?? null;
@@ -239,9 +249,14 @@ async function cmdWhoami(argv) {
       owner: getAddress(address),
     });
     if (resolved.error) {
-      const err = new Error(resolved.error);
-      err.candidates = resolved.candidates;
-      throw err;
+      exitCliError({
+        error: resolved.error,
+        because: "preferred operator label did not match this owner on-chain",
+        try: [
+          "clanker whoami --address 0x…",
+          "clanker setup --force   # fix label/owner",
+        ],
+      });
     }
     selected = [resolved.operator];
   } else {
@@ -252,12 +267,14 @@ async function cmdWhoami(argv) {
     });
   }
 
-  for (const op of selected) {
-    op.bots = await findBotsByOperator(pub, {
-      registry: network.registry,
-      operatorId: op.id,
-      fromBlock: network.fromBlock,
-    });
+  if (withBots) {
+    for (const op of selected) {
+      op.bots = await findBotsByOperator(pub, {
+        registry: network.registry,
+        operatorId: op.id,
+        fromBlock: network.fromBlock,
+      });
+    }
   }
 
   const data = {
@@ -273,18 +290,26 @@ async function cmdWhoami(argv) {
       active: o.active,
       registeredAt: o.registeredAt.toString(),
       revokedAt: o.revokedAt.toString(),
-      bots: (o.bots ?? []).map((b) => ({
-        label: b.label,
-        botKey: b.botKey,
-        active: b.active,
-        registeredAt: b.registeredAt.toString(),
-        revokedAt: b.revokedAt.toString(),
-      })),
+      bots: withBots
+        ? (o.bots ?? []).map((b) => ({
+            label: b.label,
+            botKey: b.botKey,
+            active: b.active,
+            registeredAt: b.registeredAt.toString(),
+            revokedAt: b.revokedAt.toString(),
+          }))
+        : [],
     })),
   };
 
   if (hasFlag(argv, "--json")) printJson(data);
-  else printHumanWhoami(data);
+  else {
+    printHumanWhoami(data);
+    if (!withBots && data.operators.length) {
+      console.log(c.dim("(bots omitted — pass --with-bots or run clanker bots)"));
+    }
+    nextHint(["clanker bots", "clanker doctor"]);
+  }
 }
 
 async function cmdBots(argv) {
@@ -362,12 +387,23 @@ async function main() {
     try {
       await runSetup(rest);
     } catch (err) {
-      console.error(err.message);
-      process.exit(1);
+      exitCliError({
+        error: err.message,
+        because: "setup could not write a valid local profile",
+        try: [
+          "clanker setup --preset sepolia --operator org.you --address 0x… --yes --force",
+          "clanker doctor",
+        ],
+      });
     }
     return;
   }
 
+  if (cmd === "doctor") {
+    const { exitCode } = await runDoctor(rest);
+    process.exit(exitCode);
+  }
+
   if (cmd === "init") {
     const preset = flagValue(rest, "--preset") ?? rest.find((a) => !a.startsWith("--"));
     if (!preset || preset === "init") {
@@ -414,13 +450,38 @@ async function main() {
         console.error("Usage: clanker operator mint <label>");
         process.exit(1);
       }
+      let planRows;
+      try {
+        const preview = resolveOperatorKey(flags);
+        planRows = [
+          ["action", "registerOperator"],
+          ["label", label],
+          ["owner", preview.address],
+          ["rpc", preview.network.rpc],
+          ["registry", preview.network.registry ?? "(none)"],
+          ["key", preview.source],
+        ];
+      } catch (err) {
+        exitCliError({
+          error: err.message,
+          because: "operator mint needs a signing key on this network",
+          try: [
+            "export OPERATOR_PRIVATE_KEY=0x…",
+            "clanker operator mint " + label + " --key-file ~/.clanker/op.key --yes",
+            "clanker doctor",
+          ],
+        });
+      }
+      const ok = await confirmPlan(flags, planRows, `Mint operator ${label}?`);
+      if (!ok) process.exit(0);
       const result = await chainMintOperator(label, flags);
       if (hasFlag(flags, "--json") || hasFlag(opArgv, "--json")) printJson(result);
       else {
-        console.log(`Minted operator ${label}`);
+        console.log(c.green(`Minted operator ${label}`));
         console.log(`owner: ${result.owner}`);
         console.log(`tx:    ${result.tx}`);
         console.log(`Wrote ~/.clanker/operator.json`);
+        nextHint([`clanker bot mint <bot_label>`, "clanker whoami"]);
       }
       return;
     }
@@ -432,9 +493,23 @@ async function main() {
           console.error("Usage: clanker operator transfer propose <label> <newOwner>");
           process.exit(1);
         }
+        const ok = await confirmPlan(
+          flags,
+          [
+            ["action", "proposeOperatorTransfer"],
+            ["label", label],
+            ["newOwner", getAddress(newOwner)],
+          ],
+          `Propose transfer of ${label}?`,
+        );
+        if (!ok) process.exit(0);
         const result = await chainProposeOperatorTransfer(label, getAddress(newOwner), flags);
         if (hasFlag(flags, "--json")) printJson(result);
-        else console.log(`Proposed transfer of ${label} → ${newOwner}\ntx: ${result.tx}`);
+        else {
+          console.log(c.green(`Proposed transfer of ${label} → ${newOwner}`));
+          console.log(`tx: ${result.tx}`);
+          nextHint([`clanker operator transfer accept ${label}   # as new owner`]);
+        }
         return;
       }
       if (action === "accept") {
@@ -442,9 +517,23 @@ async function main() {
           console.error("Usage: clanker operator transfer accept <label>");
           process.exit(1);
         }
+        const ok = await confirmPlan(
+          flags,
+          [
+            ["action", "acceptOperatorTransfer"],
+            ["label", label],
+          ],
+          `Accept transfer of ${label}?`,
+        );
+        if (!ok) process.exit(0);
         const result = await chainAcceptOperatorTransfer(label, flags);
         if (hasFlag(flags, "--json")) printJson(result);
-        else console.log(`Accepted transfer of ${label}\nowner: ${result.owner}\ntx: ${result.tx}`);
+        else {
+          console.log(c.green(`Accepted transfer of ${label}`));
+          console.log(`owner: ${result.owner}`);
+          console.log(`tx: ${result.tx}`);
+          nextHint(["clanker whoami", "clanker bots"]);
+        }
         return;
       }
       console.error("Usage: clanker operator transfer propose|accept ...");
@@ -484,20 +573,45 @@ async function main() {
       }
       let operatorLabel = operatorArg ?? flagValue(flags, "--operator") ?? null;
       if (!operatorLabel) {
-        const { address, network } = resolveOperatorKey(flags);
-        const inferred = await resolveOperatorLabel(flags, address, network);
-        operatorLabel = inferred.label;
+        try {
+          const { address, network } = resolveOperatorKey(flags);
+          const inferred = await resolveOperatorLabel(flags, address, network);
+          operatorLabel = inferred.label;
+        } catch (err) {
+          exitCliError({
+            error: err.message,
+            because: "bot mint needs an operator label or a resolvable signing key",
+            try: [
+              `clanker bot mint ${botLabel} <operator_label> --yes`,
+              "clanker setup",
+            ],
+          });
+        }
       }
+      const ok = await confirmPlan(
+        flags,
+        [
+          ["action", "registerBot"],
+          ["bot", botLabel],
+          ["operator", operatorLabel],
+        ],
+        `Mint bot ${botLabel} under ${operatorLabel}?`,
+      );
+      if (!ok) process.exit(0);
       const result = await chainMintBot(botLabel, operatorLabel, flags);
       if (hasFlag(flags, "--json")) printJson(result);
       else {
-        console.log(`Minted bot ${botLabel} under ${operatorLabel}`);
+        console.log(c.green(`Minted bot ${botLabel} under ${operatorLabel}`));
         console.log(`botKey:   ${result.bot_key}`);
         console.log(`key file: ${result.key_path}`);
         console.log(`also:     ${result.clanker_key_path}`);
         console.log(`tx:       ${result.tx}`);
         console.log("\nchannels.mqtt stub:");
         console.log(JSON.stringify(result.channels_mqtt, null, 2));
+        nextHint([
+          "Paste channels.mqtt into openclaw.json",
+          "openclaw plugins install @clanker-chain/mqtt-channel-plugin@…",
+        ]);
       }
       return;
     }
@@ -508,9 +622,22 @@ async function main() {
         console.error("Usage: clanker bot revoke <label>");
         process.exit(1);
       }
+      const ok = await confirmPlan(
+        flags,
+        [
+          ["action", "revokeBot"],
+          ["bot", botLabel],
+        ],
+        `Revoke bot ${botLabel}?`,
+      );
+      if (!ok) process.exit(0);
       const result = await chainRevokeBot(botLabel, flags);
       if (hasFlag(flags, "--json")) printJson(result);
-      else console.log(`Revoked ${botLabel}\ntx: ${result.tx}`);
+      else {
+        console.log(c.yellow(`Revoked ${botLabel}`));
+        console.log(`tx: ${result.tx}`);
+        nextHint(["clanker bots", "clanker bot status " + botLabel]);
+      }
       return;
     }
 
@@ -520,9 +647,23 @@ async function main() {
         console.error("Usage: clanker bot rotate <label> <newKeyAddress>");
         process.exit(1);
       }
+      const ok = await confirmPlan(
+        flags,
+        [
+          ["action", "rotateBotKey"],
+          ["bot", botLabel],
+          ["newKey", getAddress(newKey)],
+        ],
+        `Rotate key for ${botLabel}?`,
+      );
+      if (!ok) process.exit(0);
       const result = await chainRotateBotKey(botLabel, getAddress(newKey), flags);
       if (hasFlag(flags, "--json")) printJson(result);
-      else console.log(`Rotated ${botLabel} → ${newKey}\ntx: ${result.tx}`);
+      else {
+        console.log(c.green(`Rotated ${botLabel} → ${newKey}`));
+        console.log(`tx: ${result.tx}`);
+        nextHint(["Update ~/.openclaw/keys/" + botLabel + ".key", "clanker bot status " + botLabel]);
+      }
       return;
     }
 

package/lib/doctor.mjs

@@ -0,0 +1,185 @@
+/**
+ * `clanker doctor` — local readiness checks (mise-doctor habit).
+ */
+
+import { getAddress } from "viem";
+import {
+  ANVIL_DEFAULT_ADDRESS,
+  isLocalRpc,
+  loadConfig,
+  loadOperator,
+  clankerHome,
+} from "./profile.mjs";
+import { detectSetupHints, formatSetupDetectTable } from "./setup-detect.mjs";
+import { c, nextHint } from "./ui.mjs";
+
+/**
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, openclawDir?: string, castBin?: string, spawn?: Function }} [opts]
+ */
+export function runDoctorChecks(opts = {}) {
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? clankerHome(env);
+  const hints = detectSetupHints({
+    home,
+    env,
+    openclawDir: opts.openclawDir,
+    castBin: opts.castBin,
+    spawn: opts.spawn,
+  });
+  const config = hints.config ?? loadConfig(home);
+  const operator = hints.operator ?? loadOperator(home);
+
+  /** @type {{ id: string, ok: boolean, level: 'pass'|'warn'|'fail', message: string }[]} */
+  const checks = [];
+
+  checks.push({
+    id: "config",
+    ok: Boolean(config),
+    level: config ? "pass" : "fail",
+    message: config
+      ? `config.json present (preset=${config.preset})`
+      : "config.json missing — run clanker setup",
+  });
+
+  const registry = config?.registryAddress;
+  const rpc = config?.chainRpcUrl ?? "";
+  checks.push({
+    id: "registry",
+    ok: Boolean(registry && /^0x[0-9a-fA-F]{40}$/.test(registry)),
+    level: registry && /^0x[0-9a-fA-F]{40}$/.test(registry) ? "pass" : "fail",
+    message:
+      registry && /^0x[0-9a-fA-F]{40}$/.test(registry)
+        ? `registry ${registry}`
+        : "registry missing — run clanker setup --preset sepolia (or set after local deploy)",
+  });
+
+  const hasOwner =
+    Boolean(operator?.owner) && /^0x[0-9a-fA-F]{40}$/.test(operator.owner);
+  const hasLabel = Boolean(operator?.label);
+  checks.push({
+    id: "operator",
+    ok: hasOwner && hasLabel,
+    level: hasOwner && hasLabel ? "pass" : "fail",
+    message:
+      hasOwner && hasLabel
+        ? `operator.json ${operator.label} · ${operator.owner}`
+        : "operator.json incomplete — run clanker setup",
+  });
+
+  if (hasOwner && rpc && !isLocalRpc(rpc)) {
+    const anvil =
+      getAddress(operator.owner).toLowerCase() ===
+      ANVIL_DEFAULT_ADDRESS.toLowerCase();
+    checks.push({
+      id: "anvil_public",
+      ok: !anvil,
+      level: anvil ? "fail" : "pass",
+      message: anvil
+        ? "owner is Anvil #0 on a public RPC — refuse for mutate; fix owner address"
+        : "owner is not Anvil #0",
+    });
+  }
+
+  const hasKey =
+    Boolean(operator?.key?.type === "keyFile" && operator.key.value) ||
+    Boolean(operator?.key?.type === "env" && operator.key.value) ||
+    Boolean(env.OPERATOR_PRIVATE_KEY);
+  checks.push({
+    id: "signing",
+    ok: true,
+    level: hasKey ? "pass" : "warn",
+    message: hasKey
+      ? "signing key pointer available (mint/revoke OK)"
+      : "read-only profile — whoami/bots OK; mint needs --key-file or OPERATOR_PRIVATE_KEY",
+  });
+
+  checks.push({
+    id: "foundry",
+    ok: true,
+    level: hints.foundryAvailable ? "pass" : "warn",
+    message: hints.foundryAvailable
+      ? `Foundry cast OK (${hints.foundryAccounts.length} account(s))`
+      : "Foundry cast not on PATH (optional)",
+  });
+
+  const readyWhoami = checks
+    .filter((ch) => ch.id === "config" || ch.id === "registry" || ch.id === "operator")
+    .every((ch) => ch.ok);
+  const readyMint = readyWhoami && hasKey &&
+    !checks.some((ch) => ch.id === "anvil_public" && !ch.ok);
+
+  return {
+    home,
+    hints,
+    checks,
+    readyWhoami,
+    readyMint,
+    ok: readyWhoami,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {Promise<{ exitCode: number, report: object }>}
+ */
+export async function runDoctor(argv = [], opts = {}) {
+  const json = argv.includes("--json");
+  const report = runDoctorChecks(opts);
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: report.ok,
+          readyWhoami: report.readyWhoami,
+          readyMint: report.readyMint,
+          home: report.home,
+          checks: report.checks,
+        },
+        null,
+        2,
+      ),
+    );
+    return { exitCode: report.ok ? 0 : 1, report };
+  }
+
+  console.log(c.bold("clanker doctor"));
+  console.log("");
+  console.log(formatSetupDetectTable(report.hints));
+  console.log("");
+  console.log(c.bold("Checks"));
+  for (const ch of report.checks) {
+    const mark =
+      ch.level === "pass"
+        ? c.green("pass")
+        : ch.level === "warn"
+          ? c.yellow("warn")
+          : c.red("fail");
+    console.log(`  [${mark}] ${ch.message}`);
+  }
+  console.log("");
+  if (report.readyWhoami) {
+    console.log(c.green("Ready for: clanker whoami"));
+  } else {
+    console.log(c.red("Not ready for whoami"));
+  }
+  if (report.readyMint) {
+    console.log(c.green("Ready for: clanker operator mint / bot mint"));
+  } else {
+    console.log(c.dim("Mint/revoke: need signing key (and non-Anvil owner on public RPC)"));
+  }
+
+  if (!report.readyWhoami) {
+    nextHint(["clanker setup"]);
+  } else if (!report.readyMint) {
+    nextHint([
+      "clanker whoami",
+      "clanker setup --key-file ~/.clanker/op.key --force   # to enable mint",
+    ]);
+  } else {
+    nextHint(["clanker whoami", "clanker bots"]);
+  }
+
+  return { exitCode: report.ok ? 0 : 1, report };
+}

package/lib/profile.mjs

@@ -17,11 +17,14 @@ export const ANVIL_DEFAULT_ADDRESS = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
 export const SEPOLIA_REGISTRY = "0xD650467f9D7A20f37E55ec23Ca1c711598f97958";
 
 /**
- * Safe floor for Sepolia getLogs (before registry deploy). Documented so scans
- * stay cheap; bump only if you redeploy the registry earlier.
+ * Safe floor for Sepolia getLogs (before registry deploy). Use for full historical
+ * scans via --from-block; default preset uses the faster public-RPC floor below.
  */
 export const SEPOLIA_FROM_BLOCK = 35_000_000n;
 
+/** Default Sepolia fromBlock for public RPC (faster whoami/bots scans). */
+export const SEPOLIA_FAST_FROM_BLOCK = 46_000_000n;
+
 export const PRESETS = {
   local: {
     preset: "local",
@@ -37,7 +40,7 @@ export const PRESETS = {
     chainRpcUrl: "https://sepolia.base.org",
     brokerUrl: "mqtts://mqtt.clanker-chain.com:8883",
     mqttAuthServiceUrl: "https://mqtt-auth.clanker-chain.com",
-    fromBlock: SEPOLIA_FROM_BLOCK,
+    fromBlock: SEPOLIA_FAST_FROM_BLOCK,
   },
 };
 
@@ -187,7 +190,7 @@ export function resolveNetwork(argv = [], opts = {}) {
   }
 
   if (fromBlock == null) {
-    fromBlock = isLocalRpc(rpc) ? 0n : SEPOLIA_FROM_BLOCK;
+    fromBlock = isLocalRpc(rpc) ? 0n : SEPOLIA_FAST_FROM_BLOCK;
   }
 
   return {

package/lib/setup-detect.mjs

@@ -12,11 +12,11 @@ import {
   loadConfig,
   loadOperator,
   openclawKeysDir,
+  SEPOLIA_FAST_FROM_BLOCK,
 } from "./profile.mjs";
 import { normalizePrivateKey } from "./resolve.mjs";
 
-/** Faster Sepolia log floor for public RPC (registry floor remains SEPOLIA_FROM_BLOCK). */
-export const SEPOLIA_FAST_FROM_BLOCK = 46_000_000n;
+export { SEPOLIA_FAST_FROM_BLOCK };
 
 /**
  * Parse `cast wallet list` stdout into account names.

package/lib/setup.mjs

@@ -2,13 +2,14 @@
  * Interactive / flag-driven `clanker setup`.
  */
 
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
+import { stdin as input } from "node:process";
 import { existsSync } from "node:fs";
 import { getAddress } from "viem";
+import * as clack from "@clack/prompts";
 import {
   ANVIL_DEFAULT_ADDRESS,
   PRESETS,
+  SEPOLIA_FAST_FROM_BLOCK,
   clankerHome,
   configPath,
   initProfile,
@@ -22,12 +23,12 @@ import {
   resolvePreferredOperator,
 } from "./identity-query.mjs";
 import {
-  SEPOLIA_FAST_FROM_BLOCK,
   addressFromEnv,
   addressFromKeyFile,
   detectSetupHints,
   formatSetupDetectTable,
 } from "./setup-detect.mjs";
+import { c, nextHint } from "./ui.mjs";
 
 /**
  * @param {string[]} argv
@@ -72,6 +73,14 @@ export function parseSetupFlags(argv) {
   };
 }
 
+function cancelIf(value) {
+  if (clack.isCancel(value)) {
+    clack.cancel("Setup aborted.");
+    process.exit(0);
+  }
+  return value;
+}
+
 /**
  * Validate address + label against registry (and Anvil-on-public).
  * @param {{ rpc: string, registry: string, label: string, address: string, skipChainCheck?: boolean }} opts
@@ -101,7 +110,6 @@ export async function assertSetupIdentity(opts) {
   const op = await readOperator(pub, opts.registry, opts.label);
 
   if (op.registeredAt === 0n) {
-    // New operator — fine; mint later
     return { address, operator: op, skipped: false, unregistered: true };
   }
 
@@ -117,14 +125,12 @@ export async function assertSetupIdentity(opts) {
 }
 
 /**
- * Build key pointer from flags / choices.
  * @returns {{ type: 'env'|'keyFile', value: string }|null}
  */
 export function buildKeyPointer({ keyFile, keyEnv, skipKey, env = process.env }) {
   if (skipKey) return null;
   if (keyFile) {
     if (!existsSync(keyFile)) throw new Error(`Key file not found: ${keyFile}`);
-    // validate readable
     addressFromKeyFile(keyFile);
     return { type: "keyFile", value: keyFile };
   }
@@ -176,8 +182,6 @@ export function applySetup(choices, opts = {}) {
 
 /**
  * Non-interactive setup (agents / CI).
- * @param {string[]} argv
- * @param {{ home?: string, env?: NodeJS.ProcessEnv, skipChainCheck?: boolean }} [opts]
  */
 export async function runSetupNonInteractive(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
@@ -227,7 +231,6 @@ export async function runSetupNonInteractive(argv, opts = {}) {
     env,
   });
 
-  // Address from key must match --address when both set
   if (flags.keyFile && flags.address) {
     const fromKey = getAddress(addressFromKeyFile(flags.keyFile));
     if (fromKey !== getAddress(flags.address)) {
@@ -252,7 +255,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
 }
 
 /**
- * Interactive wizard when stdin is a TTY.
+ * Interactive wizard (Clack) when stdin is a TTY.
  */
 export async function runSetupInteractive(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
@@ -266,237 +269,249 @@ export async function runSetupInteractive(argv, opts = {}) {
     openclawDir: opts.openclawDir,
   });
 
-  const rl =
-    opts.rl ??
-    createInterface({ input, output });
-  const ask = async (q, def) => {
-    const suffix = def != null && def !== "" ? ` [${def}]` : "";
-    const ans = (await rl.question(`${q}${suffix}: `)).trim();
-    return ans || def || "";
-  };
-  const askYesNo = async (q, defaultYes = true) => {
-    const def = defaultYes ? "Y/n" : "y/N";
-    const ans = (await rl.question(`${q} (${def}): `)).trim().toLowerCase();
-    if (!ans) return defaultYes;
-    return ans === "y" || ans === "yes";
-  };
-
-  try {
-    console.log("");
-    console.log("clanker setup — create your local operator profile");
-    console.log("");
-    console.log(
-      "This writes ~/.clanker/config.json (network) and operator.json (who you are).",
-    );
-    console.log(
-      "Reads like `clanker whoami` can use the owner address without a private key;",
-    );
-    console.log("mint/revoke still need a key file or OPERATOR_PRIVATE_KEY later.");
-    console.log("");
-    console.log(`Profile directory: ${home}`);
-    console.log("");
-    console.log(formatSetupDetectTable(hints));
-    console.log("");
-
-    if ((hints.hasConfig || hints.hasOperator) && !flags.force) {
-      if (hints.hasConfig && !hints.hasOperator) {
-        console.log(
-          "You already have network settings from `clanker init`, but no operator identity.",
-        );
-        console.log(
-          "Continuing will refresh config.json if needed and create operator.json.",
-        );
-        const cont = await askYesNo("Continue setup?", true);
-        if (!cont) {
-          throw new Error("Aborted. Re-run `clanker setup` when ready.");
-        }
-        flags.force = true;
-      } else {
-        console.log(
-          "A full profile already exists. Continuing will REPLACE config.json and/or operator.json",
-        );
-        console.log("with the answers you give next (same files, new contents).");
-        const overwrite = await askYesNo("Replace existing profile files?", false);
-        if (!overwrite) {
-          throw new Error(
-            "Aborted. Pass --force to replace, or edit ~/.clanker/*.json by hand.",
-          );
-        }
-        flags.force = true;
+  clack.intro(c.bold("clanker setup"));
+  clack.log.step("Creates ~/.clanker/config.json (network) and operator.json (identity).");
+  clack.log.message(
+    c.dim("whoami works from owner without a key; mint/revoke need a key pointer later."),
+  );
+  clack.log.message(c.dim(`Profile: ${home}`));
+  console.log("");
+  console.log(c.dim(formatSetupDetectTable(hints)));
+  console.log("");
+
+  if ((hints.hasConfig || hints.hasOperator) && !flags.force) {
+    if (hints.hasConfig && !hints.hasOperator) {
+      const cont = cancelIf(
+        await clack.confirm({
+          message: "Network config exists; continue to create operator.json?",
+          initialValue: true,
+        }),
+      );
+      if (!cont) {
+        clack.cancel("Aborted.");
+        process.exit(0);
       }
-      console.log("");
-    }
-
-    console.log("— Network —");
-    let preset =
-      flags.preset ||
-      hints.config?.preset ||
-      (await ask("Which network? sepolia (public hub) or local (Anvil)", "sepolia"));
-    preset = String(preset).toLowerCase();
-    if (!PRESETS[preset]) throw new Error(`Unknown preset "${preset}"`);
-
-    let fromBlock = flags.fromBlock;
-    if (preset === "sepolia") {
-      const useFast =
-        fromBlock != null
-          ? false
-          : await askYesNo(
-              `Speed up chain scans? Use fromBlock ${SEPOLIA_FAST_FROM_BLOCK} (recommended on public RPC)`,
-              true,
-            );
-      if (fromBlock == null) {
-        fromBlock = useFast ? SEPOLIA_FAST_FROM_BLOCK : PRESETS.sepolia.fromBlock;
+      flags.force = true;
+    } else {
+      const overwrite = cancelIf(
+        await clack.confirm({
+          message: "Replace existing config.json / operator.json?",
+          initialValue: false,
+        }),
+      );
+      if (!overwrite) {
+        clack.cancel("Aborted. Pass --force to replace.");
+        process.exit(0);
       }
+      flags.force = true;
     }
+  }
 
-    console.log("");
-    console.log("— Operator identity —");
-    console.log(
-      "We need the wallet address that owns (or will own) your on-chain operator label.",
+  let preset = flags.preset || hints.config?.preset || null;
+  if (!preset) {
+    preset = cancelIf(
+      await clack.select({
+        message: "Network",
+        options: [
+          { value: "sepolia", label: "sepolia", hint: "public closed-beta hub" },
+          { value: "local", label: "local", hint: "Anvil" },
+        ],
+        initialValue: "sepolia",
+      }),
     );
-    let address = flags.address ?? null;
-    if (!address && flags.keyFile) {
-      address = addressFromKeyFile(flags.keyFile);
-      console.log(`Using address from --key-file: ${address}`);
-    }
-    if (!address && hints.envAddress) {
-      const useEnv = await askYesNo(
-        `Use address from OPERATOR_PRIVATE_KEY (${hints.envAddress})?`,
-        true,
-      );
-      if (useEnv) address = hints.envAddress;
-    }
-    if (!address && hints.operator?.owner) {
-      const useOp = await askYesNo(
-        `Keep existing operator.json owner (${hints.operator.owner})?`,
-        true,
+  }
+  preset = String(preset).toLowerCase();
+  if (!PRESETS[preset]) throw new Error(`Unknown preset "${preset}"`);
+
+  // Fast Sepolia default — no interactive fromBlock question
+  let fromBlock = flags.fromBlock;
+  if (fromBlock == null && preset === "sepolia") {
+    fromBlock = SEPOLIA_FAST_FROM_BLOCK;
+  }
+
+  let address = flags.address ?? null;
+  if (!address && flags.keyFile) {
+    address = addressFromKeyFile(flags.keyFile);
+    clack.log.info(`Address from --key-file: ${address}`);
+  }
+  if (!address && hints.envAddress) {
+    const useEnv = cancelIf(
+      await clack.confirm({
+        message: `Use OPERATOR_PRIVATE_KEY address (${hints.envAddress})?`,
+        initialValue: true,
+      }),
+    );
+    if (useEnv) address = hints.envAddress;
+  }
+  if (!address && hints.operator?.owner) {
+    const useOp = cancelIf(
+      await clack.confirm({
+        message: `Keep existing owner (${hints.operator.owner})?`,
+        initialValue: true,
+      }),
+    );
+    if (useOp) address = hints.operator.owner;
+  }
+  if (!address && hints.foundryAccounts.length) {
+    const options = [
+      ...hints.foundryAccounts.map((n) => ({
+        value: n,
+        label: n,
+        hint: "Foundry keystore — paste 0x next",
+      })),
+      { value: "__paste__", label: "Paste an address…", hint: "0x…" },
+    ];
+    const pick = cancelIf(
+      await clack.select({
+        message: "Operator owner source",
+        options,
+        initialValue: hints.foundryAccounts[0],
+      }),
+    );
+    if (pick === "__paste__") {
+      address = cancelIf(
+        await clack.text({
+          message: "Operator owner address",
+          placeholder: "0x…",
+          validate: (v) =>
+            /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+        }),
       );
-      if (useOp) address = hints.operator.owner;
-    }
-    if (!address && hints.foundryAccounts.length) {
-      console.log("");
-      console.log("Foundry accounts on this machine (passwords are never stored here):");
-      hints.foundryAccounts.forEach((n, i) => console.log(`  ${i + 1}. ${n}`));
-      const pick = await ask(
-        "Type a Foundry account name to use, or leave blank to paste an address",
-        hints.foundryAccounts[0] ?? "",
+    } else {
+      address = cancelIf(
+        await clack.text({
+          message: `Paste 0x address for Foundry account "${pick}"`,
+          placeholder: "0x…",
+          validate: (v) =>
+            /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+        }),
       );
-      if (pick) {
-        address = await ask(
-          `Paste the 0x address for "${pick}" (cast wallet address ${pick} after unlock)`,
-          "",
-        );
-      }
-    }
-    if (!address) {
-      address = await ask("Operator owner address (0x…)", "");
-    }
-    if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address)) {
-      throw new Error("A valid 0x operator address is required");
     }
-    address = getAddress(address);
-
-    let label =
-      flags.operator ||
-      hints.operator?.label ||
-      (await ask("Operator label on-chain (e.g. org.openclaw.pat or org.you)", ""));
-    if (!label) throw new Error("Operator label is required");
-
-    const presetCfg = PRESETS[preset];
-    console.log("");
-    console.log("— Chain check —");
-    console.log(`Looking up "${label}" on ${preset}…`);
-    const check = await assertSetupIdentity({
+  }
+  if (!address) {
+    address = cancelIf(
+      await clack.text({
+        message: "Operator owner address",
+        placeholder: "0x…",
+        validate: (v) =>
+          /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+      }),
+    );
+  }
+  address = getAddress(address);
+
+  let label = flags.operator || hints.operator?.label || null;
+  if (!label) {
+    label = cancelIf(
+      await clack.text({
+        message: "Operator label",
+        placeholder: "org.openclaw.pat",
+        validate: (v) => (v && v.trim() ? undefined : "Label required"),
+      }),
+    );
+  }
+
+  const presetCfg = PRESETS[preset];
+  const spin = clack.spinner();
+  spin.start(`Looking up "${label}" on ${preset}`);
+  let check;
+  try {
+    check = await assertSetupIdentity({
       rpc: presetCfg.chainRpcUrl,
       registry: presetCfg.registryAddress,
       label,
       address,
       skipChainCheck: flags.skipChainCheck || !presetCfg.registryAddress,
     });
-    if (check.unregistered) {
-      console.log(
-        `OK: "${label}" is not registered yet — after setup, run: clanker operator mint ${label}`,
+    spin.stop(
+      check.unregistered
+        ? c.yellow(`"${label}" not registered yet — mint after setup`)
+        : check.skipped
+          ? "Chain check skipped"
+          : c.green(`"${label}" active and owned by this address`),
+    );
+  } catch (err) {
+    spin.stop(c.red("Chain check failed"));
+    throw err;
+  }
+
+  let keyFile = flags.keyFile;
+  let keyEnv = flags.keyEnv;
+  let skipKey = flags.skipKey;
+  if (!skipKey && !keyFile && !keyEnv) {
+    if (hints.hasOperatorPrivateKeyEnv) {
+      const use = cancelIf(
+        await clack.confirm({
+          message: "Store OPERATOR_PRIVATE_KEY pointer for signing?",
+          initialValue: true,
+        }),
       );
-    } else if (check.operator) {
-      console.log(`OK: "${label}" is active on-chain and owned by this address.`);
+      if (use) keyEnv = "OPERATOR_PRIVATE_KEY";
+      else skipKey = true;
+    } else {
+      const path = cancelIf(
+        await clack.text({
+          message: "Operator key file path (Enter = read-only)",
+          placeholder: "~/.clanker/op.key",
+        }),
+      );
+      if (path && String(path).trim()) keyFile = String(path).trim();
+      else skipKey = true;
     }
+  }
 
-    console.log("");
-    console.log("— Signing key (optional) —");
-    console.log(
-      "Only needed for mint/revoke/transfer. Skip for read-only whoami/bots.",
-    );
-    let keyFile = flags.keyFile;
-    let keyEnv = flags.keyEnv;
-    let skipKey = flags.skipKey;
-    if (!skipKey && !keyFile && !keyEnv) {
-      if (hints.hasOperatorPrivateKeyEnv) {
-        const use = await askYesNo(
-          "Remember OPERATOR_PRIVATE_KEY as the signing pointer in operator.json?",
-          true,
-        );
-        if (use) keyEnv = "OPERATOR_PRIVATE_KEY";
-        else skipKey = true;
-      } else {
-        const path = await ask(
-          "Path to operator private-key file (blank = read-only profile)",
-          "",
-        );
-        if (path) keyFile = path;
-        else skipKey = true;
-      }
+  const key = buildKeyPointer({ keyFile, keyEnv, skipKey, env });
+  if (key?.type === "keyFile") {
+    const fromKey = getAddress(addressFromKeyFile(key.value));
+    if (fromKey !== address) {
+      throw new Error(`Key file address ${fromKey} does not match chosen owner ${address}`);
     }
+  }
 
-    const key = buildKeyPointer({ keyFile, keyEnv, skipKey, env });
-    if (key?.type === "keyFile") {
-      const fromKey = getAddress(addressFromKeyFile(key.value));
-      if (fromKey !== address) {
-        throw new Error(`Key file address ${fromKey} does not match chosen owner ${address}`);
-      }
-    }
+  clack.note(
+    [
+      `network:   ${preset}`,
+      `fromBlock: ${fromBlock ?? presetCfg.fromBlock}`,
+      `label:     ${label}`,
+      `owner:     ${address}`,
+      `signing:   ${key ? `${key.type}=${key.value}` : "none (read-only)"}`,
+    ].join("\n"),
+    "Summary",
+  );
 
-    console.log("");
-    console.log("— Summary (about to write) —");
-    console.log(`  network:  ${preset}`);
-    console.log(`  fromBlock:${fromBlock ?? presetCfg.fromBlock}`);
-    console.log(`  label:    ${label}`);
-    console.log(`  owner:    ${address}`);
-    console.log(
-      `  signing:  ${key ? `${key.type}=${key.value}` : "none (read-only whoami/bots)"}`,
-    );
-    const ok = flags.yes || (await askYesNo("Write these files now?", true));
-    if (!ok) throw new Error("Aborted");
-
-    const result = applySetup(
-      {
-        preset,
-        force: true,
-        fromBlock: fromBlock ?? undefined,
-        registryAddress: presetCfg.registryAddress,
-        label,
-        address,
-        key,
-      },
-      { home, env },
+  if (!flags.yes) {
+    const ok = cancelIf(
+      await clack.confirm({ message: "Write these files?", initialValue: true }),
     );
-
-    console.log("");
-    console.log(`Wrote ${result.configPath}`);
-    console.log(`Wrote ${result.operatorPath}`);
-    if (!key) {
-      console.log("");
-      console.log("Next: clanker whoami");
-      console.log(
-        "For mint/revoke later: re-run setup with a key file, or pass --key-file / OPERATOR_PRIVATE_KEY.",
-      );
-    } else {
-      console.log("");
-      console.log("Next: clanker whoami");
+    if (!ok) {
+      clack.cancel("Aborted.");
+      process.exit(0);
     }
-    return result;
-  } finally {
-    if (!opts.rl) rl.close();
   }
+
+  const result = applySetup(
+    {
+      preset,
+      force: true,
+      fromBlock: fromBlock ?? undefined,
+      registryAddress: presetCfg.registryAddress,
+      label,
+      address,
+      key,
+    },
+    { home, env },
+  );
+
+  clack.outro(c.green(`Wrote ${result.configPath}\nWrote ${result.operatorPath}`));
+  if (!key) {
+    nextHint([
+      "clanker whoami",
+      "clanker setup --key-file ~/.clanker/op.key --force   # when you need mint",
+    ]);
+  } else {
+    nextHint(["clanker whoami", `clanker bot mint <label>`]);
+  }
+  return result;
 }
 
 /**
@@ -506,7 +521,6 @@ export async function runSetup(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
   const isTTY = opts.isTTY ?? Boolean(input.isTTY);
 
-  // Fully flagged non-interactive path
   if (
     !isTTY ||
     (flags.yes && flags.preset && flags.operator && (flags.address || flags.keyFile))
@@ -514,7 +528,15 @@ export async function runSetup(argv, opts = {}) {
     if (!isTTY && !(flags.preset && flags.operator)) {
       return runSetupNonInteractive(argv, opts);
     }
-    if (flags.yes && flags.preset && flags.operator && (flags.address || flags.keyFile || opts.env?.OPERATOR_PRIVATE_KEY || process.env.OPERATOR_PRIVATE_KEY)) {
+    if (
+      flags.yes &&
+      flags.preset &&
+      flags.operator &&
+      (flags.address ||
+        flags.keyFile ||
+        opts.env?.OPERATOR_PRIVATE_KEY ||
+        process.env.OPERATOR_PRIVATE_KEY)
+    ) {
       return runSetupNonInteractive(argv, opts);
     }
   }

package/lib/ui.mjs

@@ -0,0 +1,104 @@
+/**
+ * Shared human-path CLI UX (color, plans, next hints, structured errors).
+ * Respects NO_COLOR / non-TTY via picocolors.
+ */
+
+import pc from "picocolors";
+import * as clack from "@clack/prompts";
+
+export const c = {
+  dim: (s) => pc.dim(String(s)),
+  green: (s) => pc.green(String(s)),
+  yellow: (s) => pc.yellow(String(s)),
+  red: (s) => pc.red(String(s)),
+  bold: (s) => pc.bold(String(s)),
+  cyan: (s) => pc.cyan(String(s)),
+};
+
+/**
+ * @param {string[]} argv
+ * @param {{ stdinTTY?: boolean }} [opts]
+ */
+export function isInteractive(argv = [], opts = {}) {
+  const tty = opts.stdinTTY ?? Boolean(process.stdin.isTTY);
+  if (!tty) return false;
+  if (argv.includes("--yes") || argv.includes("-y")) return false;
+  if (argv.includes("--json")) return false;
+  return true;
+}
+
+/**
+ * @param {string|string[]} lines
+ */
+export function nextHint(lines) {
+  const list = Array.isArray(lines) ? lines : [lines];
+  console.log("");
+  console.log(c.bold("Next:"));
+  for (const line of list) {
+    console.log(`  ${c.cyan(line)}`);
+  }
+}
+
+/**
+ * Cargo-style human error.
+ * @param {{ error: string, because?: string, try?: string[] }} opts
+ * @returns {string}
+ */
+export function formatCliError(opts) {
+  const lines = [c.red(`error: ${opts.error}`)];
+  if (opts.because) {
+    lines.push(c.dim(`because: ${opts.because}`));
+  }
+  if (opts.try?.length) {
+    lines.push(c.yellow("try:"));
+    for (const t of opts.try) {
+      lines.push(`  ${t}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Print a plan table (key/value rows).
+ * @param {[string, string][]} rows
+ * @param {string} [title]
+ */
+export function printPlan(rows, title = "Plan") {
+  console.log("");
+  console.log(c.bold(title));
+  const w = Math.min(18, Math.max(4, ...rows.map(([k]) => k.length)));
+  for (const [k, v] of rows) {
+    const pad = k + " ".repeat(Math.max(0, w - k.length));
+    console.log(`  ${c.dim(pad)}  ${v}`);
+  }
+}
+
+/**
+ * Confirm a mutating plan. Skips when not interactive.
+ * @param {string[]} argv
+ * @param {[string, string][]} rows
+ * @param {string} [message]
+ * @returns {Promise<boolean>}
+ */
+export async function confirmPlan(argv, rows, message = "Proceed?") {
+  printPlan(rows);
+  if (!isInteractive(argv)) return true;
+  const ok = await clack.confirm({
+    message,
+    initialValue: true,
+  });
+  if (clack.isCancel(ok) || ok === false) {
+    clack.cancel("Aborted.");
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Print structured error to stderr and exit.
+ * @param {{ error: string, because?: string, try?: string[], status?: number }} opts
+ */
+export function exitCliError(opts) {
+  console.error(formatCliError(opts));
+  process.exit(opts.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.7-3",
+  "version": "2026.9.7-4",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {
@@ -23,6 +23,8 @@
     "mint-bot:sepolia": "bash ./scripts/with-sepolia-env.sh mint-bot"
   },
   "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "picocolors": "^1.1.1",
     "viem": "^2.21.0"
   }
 }