@clanker-chain/clanker-cli 2026.9.7-4 → 2026.9.8-1

package/bin/clanker.mjs

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import os from "node:os";
 import process from "node:process";
 import { getAddress } from "viem";
 import {
   ANVIL_DEFAULT_PRIVATE_KEY,
-  harnessSnippet,
   initProfile,
   isLocalRpc,
   loadConfig,
@@ -26,6 +25,10 @@ import {
 import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/resolve.mjs";
 import { runSetup } from "../lib/setup.mjs";
 import { runDoctor } from "../lib/doctor.mjs";
+import {
+  hubConnectChecklist,
+  wireOpenClawMqtt,
+} from "../lib/openclaw-wire.mjs";
 import {
   c,
   confirmPlan,
@@ -599,19 +602,38 @@ async function main() {
       );
       if (!ok) process.exit(0);
       const result = await chainMintBot(botLabel, operatorLabel, flags);
-      if (hasFlag(flags, "--json")) printJson(result);
-      else {
+      const mqtt = result.channels_mqtt ?? {};
+      const wire = wireOpenClawMqtt({
+        botId: botLabel,
+        operatorId: operatorLabel,
+        network: {
+          rpc: mqtt.chainRpcUrl,
+          registry: mqtt.registryAddress,
+          brokerUrl: mqtt.brokerUrl,
+          mqttAuthServiceUrl: mqtt.mqttAuthServiceUrl,
+        },
+        keyPath: result.key_path,
+      });
+      if (hasFlag(flags, "--json")) {
+        printJson({ ...result, openclaw: wire });
+      } else {
         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@…",
-        ]);
+        console.log(
+          wire.created
+            ? c.green(`Wrote ${wire.path}`)
+            : c.green(`Updated channels.mqtt in ${wire.path}`),
+        );
+        nextHint(
+          hubConnectChecklist({
+            botId: botLabel,
+            channelsMqtt: wire.channelsMqtt,
+            pluginPin: wire.pluginPin,
+          }),
+        );
       }
       return;
     }
@@ -869,22 +891,6 @@ async function main() {
   }
 
   if (cmd === "init-openclaw") {
-    const home = os.homedir();
-    const openclawDir = join(home, ".openclaw");
-    const cfgPath = join(openclawDir, "openclaw.json");
-    if (!existsSync(openclawDir)) {
-      mkdirSync(openclawDir, { recursive: true });
-    }
-
-    if (existsSync(cfgPath)) {
-      console.log(`${cfgPath} already exists.`);
-      console.log(
-        'Ensure plugins.enabled includes "mqtt" and "mqtt-tools", and channels.mqtt has botId, operatorId, brokerUrl, chainRpcUrl, registryAddress.',
-      );
-      console.log("See SETUP.md and docs/operator-cli.md.");
-      process.exit(0);
-    }
-
     const profile = loadConfig();
     const operator = loadOperator();
     // No profile: local defaults only — do not mix Sepolia registry with localhost MQTT.
@@ -902,27 +908,21 @@ async function main() {
           mqttAuthServiceUrl: "http://localhost:9090",
         };
 
-    const mqtt = harnessSnippet({
+    const wire = wireOpenClawMqtt({
       botId: "openclaw.your-bot.local",
       operatorId: operator?.label ?? "org.openclaw.your-operator",
       network,
     });
-    if (!mqtt.registryAddress) {
-      mqtt.registryAddress = "0x0000000000000000000000000000000000000000";
-    }
-
-    const cfg = {
-      plugins: {
-        enabled: ["mqtt", "mqtt-tools"],
-      },
-      channels: {
-        mqtt,
-      },
-    };
-    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2), "utf8");
-    console.log(`Created ${cfgPath} with mqtt + mqtt-tools from ${profile ? "active" : "default"} preset.`);
-    console.log("Next: clanker bot mint <label>, then set channels.mqtt.botId / operatorId.");
-    console.log("See docs/operator-cli.md and SETUP.md.");
+    console.log(
+      wire.created
+        ? `Created ${wire.path} with mqtt + mqtt-tools from ${profile ? "active" : "default"} preset.`
+        : `Updated channels.mqtt in ${wire.path} (plugins mqtt + mqtt-tools ensured).`,
+    );
+    nextHint([
+      "clanker bot mint <label>",
+      "Then channels.mqtt.botId / operatorId / privateKeyFile update automatically",
+      "See docs/operator-cli.md and docs/closed-beta-invite.md",
+    ]);
     process.exit(0);
   }
 

package/lib/doctor.mjs

@@ -14,9 +14,9 @@ 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]
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, openclawDir?: string, castBin?: string, spawn?: Function, fetchImpl?: typeof fetch }} [opts]
  */
-export function runDoctorChecks(opts = {}) {
+export async function runDoctorChecks(opts = {}) {
   const env = opts.env ?? process.env;
   const home = opts.home ?? clankerHome(env);
   const hints = detectSetupHints({
@@ -28,6 +28,7 @@ export function runDoctorChecks(opts = {}) {
   });
   const config = hints.config ?? loadConfig(home);
   const operator = hints.operator ?? loadOperator(home);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
 
   /** @type {{ id: string, ok: boolean, level: 'pass'|'warn'|'fail', message: string }[]} */
   const checks = [];
@@ -102,6 +103,46 @@ export function runDoctorChecks(opts = {}) {
       : "Foundry cast not on PATH (optional)",
   });
 
+  const authUrl = config?.mqttAuthServiceUrl;
+  if (authUrl && typeof fetchImpl === "function") {
+    const healthUrl = `${String(authUrl).replace(/\/$/, "")}/health`;
+    try {
+      const ac = new AbortController();
+      const t = setTimeout(() => ac.abort(), 5000);
+      const res = await fetchImpl(healthUrl, { signal: ac.signal });
+      clearTimeout(t);
+      if (res.ok) {
+        checks.push({
+          id: "mqtt_auth_health",
+          ok: true,
+          level: "pass",
+          message: `mqtt-auth health OK (${healthUrl})`,
+        });
+      } else {
+        checks.push({
+          id: "mqtt_auth_health",
+          ok: false,
+          level: "fail",
+          message: `mqtt-auth health HTTP ${res.status} (${healthUrl})`,
+        });
+      }
+    } catch (err) {
+      checks.push({
+        id: "mqtt_auth_health",
+        ok: false,
+        level: "warn",
+        message: `mqtt-auth health unreachable: ${err.message ?? err}`,
+      });
+    }
+  } else if (config) {
+    checks.push({
+      id: "mqtt_auth_health",
+      ok: true,
+      level: "warn",
+      message: "mqttAuthServiceUrl not set — skip hub health",
+    });
+  }
+
   const readyWhoami = checks
     .filter((ch) => ch.id === "config" || ch.id === "registry" || ch.id === "operator")
     .every((ch) => ch.ok);
@@ -125,7 +166,7 @@ export function runDoctorChecks(opts = {}) {
  */
 export async function runDoctor(argv = [], opts = {}) {
   const json = argv.includes("--json");
-  const report = runDoctorChecks(opts);
+  const report = await runDoctorChecks(opts);
 
   if (json) {
     console.log(

package/lib/foundry.mjs

@@ -0,0 +1,114 @@
+/**
+ * Foundry cast helpers for setup (address resolve + key export).
+ * Never logs private keys.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { getAddress } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { normalizePrivateKey } from "./resolve.mjs";
+import { parseCastWalletList } from "./setup-detect.mjs";
+
+/**
+ * @param {{ castBin?: string, spawn?: typeof spawnSync }} [opts]
+ */
+export function listFoundryAccounts(opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const result = spawn(castBin, ["wallet", "list"], {
+    encoding: "utf8",
+    shell: false,
+  });
+  if (result.error || result.status !== 0) {
+    return { available: false, accounts: [] };
+  }
+  return { available: true, accounts: parseCastWalletList(result.stdout ?? "") };
+}
+
+/**
+ * Resolve 0x address for a Foundry account name.
+ * Uses inherit stdio so unlock prompts work when interactive.
+ *
+ * @param {string} account
+ * @param {{ castBin?: string, spawn?: typeof spawnSync, inheritStdio?: boolean }} [opts]
+ * @returns {string} checksummed address
+ */
+export function resolveFoundryAddress(account, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const inherit = opts.inheritStdio !== false;
+  const result = spawn(castBin, ["wallet", "address", account], {
+    encoding: "utf8",
+    shell: false,
+    stdio: inherit ? ["inherit", "pipe", "inherit"] : "pipe",
+  });
+  if (result.error) {
+    throw new Error(`cast failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || "").trim();
+    throw new Error(
+      err || `cast wallet address ${account} failed (status ${result.status})`,
+    );
+  }
+  const line = String(result.stdout ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => /^0x[0-9a-fA-F]{40}$/.test(l));
+  if (!line) {
+    throw new Error(`Could not parse address from cast wallet address ${account}`);
+  }
+  return getAddress(line);
+}
+
+/**
+ * Export Foundry account private key to destPath (mode 0o600).
+ * Does not print the key. Unlock prompts via inherit stdio when interactive.
+ *
+ * @param {string} account
+ * @param {string} destPath
+ * @param {{ castBin?: string, spawn?: typeof spawnSync, inheritStdio?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function exportFoundryKey(account, destPath, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const castBin = opts.castBin ?? "cast";
+  const inherit = opts.inheritStdio !== false;
+  const result = spawn(castBin, ["wallet", "private-key", account], {
+    encoding: "utf8",
+    shell: false,
+    stdio: inherit ? ["inherit", "pipe", "inherit"] : "pipe",
+  });
+  if (result.error) {
+    throw new Error(`cast failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const err = (result.stderr || "").trim();
+    throw new Error(
+      err || `cast wallet private-key ${account} failed (status ${result.status})`,
+    );
+  }
+  const raw = String(result.stdout ?? "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!raw) {
+    throw new Error("cast returned empty private key");
+  }
+  const key = normalizePrivateKey(raw);
+  const address = privateKeyToAccount(key).address;
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Default operator key path under clanker home.
+ * @param {string} home
+ */
+export function defaultOperatorKeyPath(home) {
+  return `${home.replace(/\/$/, "")}/op.key`;
+}

package/lib/openclaw-wire.mjs

@@ -0,0 +1,104 @@
+/**
+ * Merge / create ~/.openclaw/openclaw.json channels.mqtt from clanker profile.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { harnessSnippet } from "./profile.mjs";
+
+/** Current published OpenClaw plugin pins for closed-beta invite. */
+export const OPENCLAW_PLUGIN_PIN = "2026.7.29";
+
+/**
+ * @param {string} [openclawHome]
+ */
+export function openclawConfigPath(openclawHome = join(homedir(), ".openclaw")) {
+  return join(openclawHome, "openclaw.json");
+}
+
+/**
+ * Ensure mqtt + mqtt-tools are in plugins.enabled.
+ * @param {object} cfg
+ */
+export function ensureMqttPlugins(cfg) {
+  const out = { ...cfg };
+  const plugins = { ...(out.plugins ?? {}) };
+  const enabled = Array.isArray(plugins.enabled) ? [...plugins.enabled] : [];
+  for (const id of ["mqtt", "mqtt-tools"]) {
+    if (!enabled.includes(id)) enabled.push(id);
+  }
+  plugins.enabled = enabled;
+  out.plugins = plugins;
+  return out;
+}
+
+/**
+ * Wire channels.mqtt into openclaw.json.
+ *
+ * @param {{
+ *   botId: string,
+ *   operatorId: string,
+ *   network: { rpc: string, registry: string|null, brokerUrl?: string, mqttAuthServiceUrl?: string },
+ *   keyPath?: string|null,
+ *   openclawHome?: string,
+ * }} opts
+ */
+export function wireOpenClawMqtt(opts) {
+  const openclawHome = opts.openclawHome ?? join(homedir(), ".openclaw");
+  const cfgPath = openclawConfigPath(openclawHome);
+  mkdirSync(openclawHome, { recursive: true });
+
+  const mqtt = harnessSnippet({
+    botId: opts.botId,
+    operatorId: opts.operatorId,
+    network: opts.network,
+  });
+  if (!mqtt.registryAddress) {
+    mqtt.registryAddress = "0x0000000000000000000000000000000000000000";
+  }
+  if (opts.keyPath) {
+    mqtt.privateKeyFile = opts.keyPath;
+  }
+
+  let created = false;
+  let cfg;
+  if (!existsSync(cfgPath)) {
+    created = true;
+    cfg = {
+      plugins: { enabled: ["mqtt", "mqtt-tools"] },
+      channels: { mqtt },
+    };
+  } else {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    cfg = ensureMqttPlugins(cfg);
+    const channels = { ...(cfg.channels ?? {}) };
+    const prev = channels.mqtt && typeof channels.mqtt === "object" ? channels.mqtt : {};
+    channels.mqtt = { ...prev, ...mqtt };
+    cfg.channels = channels;
+  }
+
+  writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+  return {
+    created,
+    path: cfgPath,
+    channelsMqtt: cfg.channels.mqtt,
+    pluginPin: OPENCLAW_PLUGIN_PIN,
+  };
+}
+
+/**
+ * Human checklist lines after wiring.
+ * @param {{ botId: string, channelsMqtt: object, pluginPin: string }} opts
+ */
+export function hubConnectChecklist(opts) {
+  const pin = opts.pluginPin ?? OPENCLAW_PLUGIN_PIN;
+  return [
+    `openclaw plugins install @clanker-chain/mqtt-channel-plugin@${pin}`,
+    `openclaw plugins install @clanker-chain/mqtt-tools@${pin}`,
+    "Enable plugin ids mqtt + mqtt-tools (already set in openclaw.json if we wired it)",
+    `CONNECT broker: ${opts.channelsMqtt?.brokerUrl ?? "mqtts://mqtt.clanker-chain.com:8883"}`,
+    `Ask hub operator to allow bot_id "${opts.botId}" in france dmPolicy / allowFrom`,
+    "DM openclaw.france.prod-1 to smoke the mesh",
+  ];
+}

package/lib/operator-key.mjs

@@ -0,0 +1,50 @@
+/**
+ * Consumer-path operator key helpers (generate local op.key).
+ * Never logs private keys.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { defaultOperatorKeyPath } from "./foundry.mjs";
+
+export { defaultOperatorKeyPath };
+
+/** Coinbase Developer Platform faucet UI (Base Sepolia). */
+export const BASE_SEPOLIA_FAUCET_URL =
+  "https://portal.cdp.coinbase.com/products/faucet";
+
+/**
+ * Generate a new secp256k1 key and write it to destPath (mode 0o600).
+ * Does not print the key.
+ *
+ * @param {string} destPath
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function generateOperatorKeyFile(destPath, opts = {}) {
+  if (existsSync(destPath) && !opts.force) {
+    throw new Error(
+      `Key file already exists: ${destPath} (pass --force to overwrite)`,
+    );
+  }
+  const key = generatePrivateKey();
+  const address = privateKeyToAccount(key).address;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Plain-language next steps after creating an operator key on Sepolia.
+ * @param {{ address: string, label?: string }} opts
+ */
+export function consumerFundHints(opts) {
+  const mintLabel = opts.label ? ` ${opts.label}` : "";
+  return [
+    `Your operator address is ${opts.address} — fund it with Base Sepolia ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+    "clanker doctor",
+    `clanker operator mint${mintLabel} --yes`,
+    "clanker bot mint <bot_label> --yes",
+  ];
+}

package/lib/setup.mjs

@@ -28,7 +28,18 @@ import {
   detectSetupHints,
   formatSetupDetectTable,
 } from "./setup-detect.mjs";
+import {
+  defaultOperatorKeyPath,
+  exportFoundryKey,
+  resolveFoundryAddress,
+} from "./foundry.mjs";
+import {
+  BASE_SEPOLIA_FAUCET_URL,
+  consumerFundHints,
+  generateOperatorKeyFile,
+} from "./operator-key.mjs";
 import { c, nextHint } from "./ui.mjs";
+import { join } from "node:path";
 
 /**
  * @param {string[]} argv
@@ -44,6 +55,9 @@ export function parseSetupFlags(argv) {
   let yes = false;
   let skipKey = false;
   let skipChainCheck = false;
+  let foundryAccount = null;
+  let exportKey = false;
+  let generateKey = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -53,6 +67,9 @@ export function parseSetupFlags(argv) {
     else if (a === "--key-file" && argv[i + 1]) keyFile = argv[++i];
     else if (a === "--key-env" && argv[i + 1]) keyEnv = argv[++i];
     else if (a === "--from-block" && argv[i + 1]) fromBlock = BigInt(argv[++i]);
+    else if (a === "--foundry-account" && argv[i + 1]) foundryAccount = argv[++i];
+    else if (a === "--export-key") exportKey = true;
+    else if (a === "--generate-key") generateKey = true;
     else if (a === "--force") force = true;
     else if (a === "--yes" || a === "-y") yes = true;
     else if (a === "--skip-key") skipKey = true;
@@ -70,6 +87,9 @@ export function parseSetupFlags(argv) {
     yes,
     skipKey,
     skipChainCheck,
+    foundryAccount,
+    exportKey,
+    generateKey,
   };
 }
 
@@ -191,21 +211,61 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   if (!flags.preset || !PRESETS[flags.preset]) {
     throw new Error(
       "Non-interactive setup requires --preset sepolia|local (stdin is not a TTY). " +
-        "Also pass --operator <label> and --address 0x…",
+        "Also pass --operator <label> and --generate-key (or --address / --key-file)",
     );
   }
   if (!flags.operator) {
     throw new Error("Non-interactive setup requires --operator <label>");
   }
-  if (!flags.address && !flags.keyFile && !env.OPERATOR_PRIVATE_KEY) {
-    throw new Error(
-      "Non-interactive setup requires --address 0x…, --key-file, or OPERATOR_PRIVATE_KEY",
-    );
-  }
 
   let address = flags.address;
-  if (!address && flags.keyFile) address = addressFromKeyFile(flags.keyFile);
+  let keyFile = flags.keyFile;
+  const castOpts = {
+    castBin: opts.castBin,
+    spawn: opts.spawn,
+    inheritStdio: false,
+  };
+
+  if (flags.generateKey) {
+    if (flags.skipKey) {
+      throw new Error("Cannot combine --generate-key with --skip-key");
+    }
+    const dest = keyFile || defaultOperatorKeyPath(home);
+    const created = generateOperatorKeyFile(dest, {
+      force: flags.force,
+    });
+    keyFile = created.path;
+    if (address && getAddress(address) !== getAddress(created.address)) {
+      throw new Error(
+        `Generated key address ${created.address} does not match --address ${getAddress(address)}`,
+      );
+    }
+    address = created.address;
+  }
+
+  if (flags.foundryAccount) {
+    if (!address) {
+      address = resolveFoundryAddress(flags.foundryAccount, castOpts);
+    }
+    if (flags.exportKey && !keyFile && !flags.skipKey) {
+      const dest = defaultOperatorKeyPath(home);
+      const exported = exportFoundryKey(flags.foundryAccount, dest, castOpts);
+      keyFile = exported.path;
+      if (getAddress(exported.address) !== getAddress(address)) {
+        throw new Error(
+          `Exported Foundry key address ${exported.address} does not match ${address}`,
+        );
+      }
+    }
+  }
+
+  if (!address && keyFile) address = addressFromKeyFile(keyFile);
   if (!address && env.OPERATOR_PRIVATE_KEY) address = addressFromEnv(env);
+  if (!address) {
+    throw new Error(
+      "Non-interactive setup requires --generate-key, --address 0x…, --key-file, OPERATOR_PRIVATE_KEY, or --foundry-account",
+    );
+  }
 
   const preset = PRESETS[flags.preset];
   let fromBlock = flags.fromBlock;
@@ -225,14 +285,14 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   });
 
   const key = buildKeyPointer({
-    keyFile: flags.keyFile,
+    keyFile,
     keyEnv: flags.keyEnv,
     skipKey: flags.skipKey,
     env,
   });
 
-  if (flags.keyFile && flags.address) {
-    const fromKey = getAddress(addressFromKeyFile(flags.keyFile));
+  if (keyFile && flags.address) {
+    const fromKey = getAddress(addressFromKeyFile(keyFile));
     if (fromKey !== getAddress(flags.address)) {
       throw new Error(
         `Key file address ${fromKey} does not match --address ${getAddress(flags.address)}`,
@@ -270,9 +330,13 @@ export async function runSetupInteractive(argv, opts = {}) {
   });
 
   clack.intro(c.bold("clanker setup"));
-  clack.log.step("Creates ~/.clanker/config.json (network) and operator.json (identity).");
+  clack.log.step(
+    "Sets up your operator identity (org account) and network for OpenClaw bots.",
+  );
   clack.log.message(
-    c.dim("whoami works from owner without a key; mint/revoke need a key pointer later."),
+    c.dim(
+      "New here? Create a key file — no wallet app or Foundry required. Mint needs a little test ETH later.",
+    ),
   );
   clack.log.message(c.dim(`Profile: ${home}`));
   console.log("");
@@ -330,6 +394,29 @@ export async function runSetupInteractive(argv, opts = {}) {
   }
 
   let address = flags.address ?? null;
+  let foundryAccountUsed = null;
+  let generatedKeyFile = null;
+  if (!address && flags.generateKey) {
+    const dest = flags.keyFile || defaultOperatorKeyPath(home);
+    let forceGen = flags.force;
+    if (existsSync(dest) && !forceGen) {
+      forceGen = cancelIf(
+        await clack.confirm({
+          message: `Overwrite existing ${dest}?`,
+          initialValue: false,
+        }),
+      );
+      if (!forceGen) {
+        clack.cancel("Aborted.");
+        process.exit(0);
+      }
+    }
+    const created = generateOperatorKeyFile(dest, { force: true });
+    generatedKeyFile = created.path;
+    address = created.address;
+    clack.log.success(`Created operator key at ${created.path}`);
+    clack.log.info(`Your operator address: ${created.address}`);
+  }
   if (!address && flags.keyFile) {
     address = addressFromKeyFile(flags.keyFile);
     clack.log.info(`Address from --key-file: ${address}`);
@@ -352,23 +439,86 @@ export async function runSetupInteractive(argv, opts = {}) {
     );
     if (useOp) address = hints.operator.owner;
   }
-  if (!address && hints.foundryAccounts.length) {
+  if (!address) {
     const options = [
-      ...hints.foundryAccounts.map((n) => ({
-        value: n,
-        label: n,
-        hint: "Foundry keystore — paste 0x next",
-      })),
-      { value: "__paste__", label: "Paste an address…", hint: "0x…" },
+      {
+        value: "__generate__",
+        label: "Create a new operator key for me",
+        hint: "writes ~/.clanker/op.key (recommended)",
+      },
+      {
+        value: "__keyfile__",
+        label: "Use an existing key file…",
+        hint: "path to a 0x private key file",
+      },
     ];
+    if (hints.foundryAccounts.length) {
+      for (const n of hints.foundryAccounts) {
+        options.push({
+          value: n,
+          label: `Foundry: ${n}`,
+          hint: "advanced — cast wallet",
+        });
+      }
+    } else {
+      options.push({
+        value: "__foundry_missing__",
+        label: "Foundry account…",
+        hint: "advanced — install Foundry first",
+      });
+    }
+    options.push({
+      value: "__paste__",
+      label: "Paste an address…",
+      hint: "read-only unless you add a key later",
+    });
+
     const pick = cancelIf(
       await clack.select({
-        message: "Operator owner source",
+        message: "How do you want to set your operator identity?",
         options,
-        initialValue: hints.foundryAccounts[0],
+        initialValue: "__generate__",
       }),
     );
-    if (pick === "__paste__") {
+
+    if (pick === "__generate__") {
+      const dest = defaultOperatorKeyPath(home);
+      let forceGen = flags.force;
+      if (existsSync(dest) && !forceGen) {
+        forceGen = cancelIf(
+          await clack.confirm({
+            message: `Overwrite existing ${dest}?`,
+            initialValue: false,
+          }),
+        );
+        if (!forceGen) {
+          clack.cancel("Aborted.");
+          process.exit(0);
+        }
+      }
+      const created = generateOperatorKeyFile(dest, { force: true });
+      generatedKeyFile = created.path;
+      address = created.address;
+      clack.log.success(`Created operator key at ${created.path}`);
+      clack.log.info(`Your operator address: ${created.address}`);
+    } else if (pick === "__keyfile__") {
+      const path = cancelIf(
+        await clack.text({
+          message: "Path to operator key file",
+          placeholder: join(home, "op.key"),
+          validate: (v) =>
+            v && String(v).trim() && existsSync(String(v).trim())
+              ? undefined
+              : "File not found",
+        }),
+      );
+      generatedKeyFile = String(path).trim();
+      address = addressFromKeyFile(generatedKeyFile);
+      clack.log.info(`Address from key file: ${address}`);
+    } else if (pick === "__foundry_missing__") {
+      clack.log.warn(
+        "Foundry (cast) is not available. Install https://book.getfoundry.sh/ or choose Create a new operator key.",
+      );
       address = cancelIf(
         await clack.text({
           message: "Operator owner address",
@@ -377,27 +527,38 @@ export async function runSetupInteractive(argv, opts = {}) {
             /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
         }),
       );
-    } else {
+    } else if (pick === "__paste__") {
       address = cancelIf(
         await clack.text({
-          message: `Paste 0x address for Foundry account "${pick}"`,
+          message: "Operator owner address",
           placeholder: "0x…",
           validate: (v) =>
             /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
         }),
       );
+    } else {
+      foundryAccountUsed = pick;
+      try {
+        clack.log.step(`Resolving address for Foundry account "${pick}" (unlock if prompted)…`);
+        address = resolveFoundryAddress(pick, {
+          castBin: opts.castBin,
+          spawn: opts.spawn,
+          inheritStdio: true,
+        });
+        clack.log.success(`Foundry address: ${address}`);
+      } catch (err) {
+        clack.log.warn(err.message);
+        address = cancelIf(
+          await clack.text({
+            message: `Paste 0x address for "${pick}"`,
+            placeholder: "0x…",
+            validate: (v) =>
+              /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+          }),
+        );
+      }
     }
   }
-  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;
@@ -435,11 +596,36 @@ export async function runSetupInteractive(argv, opts = {}) {
     throw err;
   }
 
-  let keyFile = flags.keyFile;
+  let keyFile = flags.keyFile || generatedKeyFile;
   let keyEnv = flags.keyEnv;
   let skipKey = flags.skipKey;
   if (!skipKey && !keyFile && !keyEnv) {
-    if (hints.hasOperatorPrivateKeyEnv) {
+    if (foundryAccountUsed) {
+      const doExport = cancelIf(
+        await clack.confirm({
+          message: `Export Foundry key for "${foundryAccountUsed}" to ~/.clanker/op.key for minting?`,
+          initialValue: true,
+        }),
+      );
+      if (doExport) {
+        const dest = defaultOperatorKeyPath(home);
+        clack.log.step("Exporting key via cast (unlock if prompted; key is not printed)…");
+        const exported = exportFoundryKey(foundryAccountUsed, dest, {
+          castBin: opts.castBin,
+          spawn: opts.spawn,
+          inheritStdio: true,
+        });
+        if (getAddress(exported.address) !== address) {
+          throw new Error(
+            `Exported key address ${exported.address} does not match owner ${address}`,
+          );
+        }
+        keyFile = exported.path;
+        clack.log.success(`Wrote ${keyFile} (mode 600)`);
+      } else {
+        skipKey = true;
+      }
+    } else if (hints.hasOperatorPrivateKeyEnv) {
       const use = cancelIf(
         await clack.confirm({
           message: "Store OPERATOR_PRIVATE_KEY pointer for signing?",
@@ -452,7 +638,7 @@ export async function runSetupInteractive(argv, opts = {}) {
       const path = cancelIf(
         await clack.text({
           message: "Operator key file path (Enter = read-only)",
-          placeholder: "~/.clanker/op.key",
+          placeholder: join(home, "op.key"),
         }),
       );
       if (path && String(path).trim()) keyFile = String(path).trim();
@@ -506,7 +692,16 @@ export async function runSetupInteractive(argv, opts = {}) {
   if (!key) {
     nextHint([
       "clanker whoami",
-      "clanker setup --key-file ~/.clanker/op.key --force   # when you need mint",
+      "clanker setup — choose Create a new operator key when you need mint",
+    ]);
+  } else if (preset === "sepolia" && generatedKeyFile) {
+    nextHint(consumerFundHints({ address, label }));
+  } else if (preset === "sepolia") {
+    nextHint([
+      `If this address needs test ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+      "clanker doctor",
+      "clanker whoami",
+      `clanker bot mint <label>`,
     ]);
   } else {
     nextHint(["clanker whoami", `clanker bot mint <label>`]);
@@ -520,23 +715,20 @@ export async function runSetupInteractive(argv, opts = {}) {
 export async function runSetup(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
   const isTTY = opts.isTTY ?? Boolean(input.isTTY);
+  const hasIdentitySource = Boolean(
+    flags.address ||
+      flags.keyFile ||
+      flags.generateKey ||
+      flags.foundryAccount ||
+      opts.env?.OPERATOR_PRIVATE_KEY ||
+      process.env.OPERATOR_PRIVATE_KEY,
+  );
 
-  if (
-    !isTTY ||
-    (flags.yes && flags.preset && flags.operator && (flags.address || flags.keyFile))
-  ) {
+  if (!isTTY || (flags.yes && flags.preset && flags.operator && hasIdentitySource)) {
     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 && hasIdentitySource) {
       return runSetupNonInteractive(argv, opts);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.7-4",
+  "version": "2026.9.8-1",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {