towns-agent 2.0.5 → 2.0.6

package/dist/index.js

@@ -35,9 +35,18 @@ var jsonc = __toESM(require("jsonc-parser"));
 // src/modules/utils.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
+var import_node_url = require("url");
 var import_cross_spawn = __toESM(require("cross-spawn"));
 var import_prompts = __toESM(require("prompts"));
 var import_picocolors = __toESM(require("picocolors"));
+var import_dotenv = require("dotenv");
+var import_sdk = require("@towns-labs/sdk");
+
+// package.json
+var version = "2.0.6";
+
+// src/modules/utils.ts
+var import_meta = {};
 var getPackageManager = () => {
   if (process.env.npm_config_user_agent) {
     const agent = process.env.npm_config_user_agent;
@@ -85,7 +94,7 @@ function getDlxCommand(packageManager) {
   }
 }
 function runCommand(command, args, opts = { cwd: void 0, silent: false }) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = (0, import_cross_spawn.default)(command, args, {
       stdio: opts.silent ? "ignore" : "inherit",
       cwd: opts.cwd,
@@ -95,118 +104,58 @@ function runCommand(command, args, opts = { cwd: void 0, silent: false }) {
       if (code !== 0) {
         reject(new Error(`Command failed with exit code ${code}`));
       } else {
-        resolve2();
-      }
-    });
-    child.on("error", reject);
-  });
-}
-async function getLatestTownsProtocolVersion() {
-  return new Promise((resolve2, reject) => {
-    const child = (0, import_cross_spawn.default)("npm", ["view", "@towns-labs/agent", "version"], {
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-    let output = "";
-    child.stdout?.on("data", (data) => {
-      output += data.toString();
-    });
-    child.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error("Failed to fetch latest @towns-labs/agent version"));
-      } else {
-        resolve2(output.trim());
+        resolve3();
       }
     });
     child.on("error", reject);
   });
 }
-function getLatestSdkTag() {
-  const tagsResult = import_cross_spawn.default.sync(
-    "git",
-    ["ls-remote", "--tags", "https://github.com/HereNotThere/chat.git", "@towns-labs/sdk@*"],
-    { encoding: "utf8" }
-  );
-  if (tagsResult.status !== 0 || !tagsResult.stdout) return null;
-  const tags = tagsResult.stdout.split("\n").filter(Boolean).map((line) => {
-    const [_hash, ref] = line.split("	");
-    const tag = ref.replace("refs/tags/", "").replace(/\^{}$/, "");
-    const match = tag.match(/^@towns-protocol\/sdk@(\d+)\.(\d+)\.(\d+)$/);
-    if (!match) return null;
-    return {
-      tag,
-      version: [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])]
-    };
-  }).filter(
-    (item) => item !== null && Array.isArray(item.version) && item.version.length === 3
-  ).sort((a, b) => {
-    for (let i = 0; i < 3; i++) {
-      if (a.version[i] !== b.version[i]) {
-        return b.version[i] - a.version[i];
-      }
-    }
-    return 0;
-  });
-  return tags.length > 0 ? tags[0].tag : null;
+function getTemplatesDir() {
+  const currentDir = typeof __dirname !== "undefined" ? __dirname : path.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+  const fromDist = path.resolve(currentDir, "..", "templates");
+  if (fs.existsSync(fromDist)) return fromDist;
+  const fromSrc = path.resolve(currentDir, "..", "..", "templates");
+  if (fs.existsSync(fromSrc)) return fromSrc;
+  throw new Error("Templates directory not found");
 }
-async function cloneTemplate(packagePath, targetDir) {
-  console.log(import_picocolors.default.blue("Cloning template from GitHub..."));
-  const tempDir = `${targetDir}-temp`;
-  const fullTemplatePath = `packages/examples/${packagePath}`;
-  const latestSdkTag = getLatestSdkTag();
-  if (!latestSdkTag) {
-    console.error(import_picocolors.default.red("Failed to get latest SDK tag."));
-    return false;
-  }
-  const cloneResult = import_cross_spawn.default.sync(
-    "git",
-    [
-      "clone",
-      "--no-checkout",
-      "--depth",
-      "1",
-      "--sparse",
-      "--branch",
-      latestSdkTag,
-      "https://github.com/towns-protocol/towns.git",
-      tempDir
-    ],
-    { stdio: "pipe" }
-  );
-  if (cloneResult.status !== 0) return false;
-  const sparseResult = import_cross_spawn.default.sync("git", ["sparse-checkout", "set", fullTemplatePath], {
-    stdio: "pipe",
-    cwd: tempDir
-  });
-  if (sparseResult.status !== 0) {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-    return false;
-  }
-  const checkoutResult = import_cross_spawn.default.sync("git", ["checkout"], {
-    stdio: "pipe",
-    cwd: tempDir
-  });
-  if (checkoutResult.status !== 0) {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-    return false;
-  }
-  const sourceDir = path.join(tempDir, fullTemplatePath);
+function copyTemplate(templateName, targetDir) {
+  console.log(import_picocolors.default.blue("Copying template..."));
+  const templatesDir = getTemplatesDir();
+  const sourceDir = path.join(templatesDir, templateName);
   if (!fs.existsSync(sourceDir)) {
-    console.error(import_picocolors.default.red(`
-Template directory not found at ${sourceDir}`));
-    fs.rmSync(tempDir, { recursive: true, force: true });
+    console.error(import_picocolors.default.red(`Template "${templateName}" not found at ${sourceDir}`));
     return false;
   }
   fs.mkdirSync(targetDir, { recursive: true });
   fs.cpSync(sourceDir, targetDir, {
     recursive: true,
-    filter: () => {
-      return true;
+    filter: (source) => {
+      const basename2 = path.basename(source);
+      return basename2 !== "node_modules" && basename2 !== "dist";
     }
   });
-  fs.rmSync(tempDir, { recursive: true, force: true });
-  console.log(import_picocolors.default.green("\u2713"), "Template cloned successfully!");
+  const gitignoreSrc = path.join(targetDir, "_gitignore");
+  const gitignoreDest = path.join(targetDir, ".gitignore");
+  if (fs.existsSync(gitignoreSrc)) {
+    fs.renameSync(gitignoreSrc, gitignoreDest);
+  }
+  console.log(import_picocolors.default.green("\u2713"), "Template copied successfully!");
   return true;
 }
+function copyAgentsMd(projectDir) {
+  try {
+    const templatesDir = getTemplatesDir();
+    const sourceFile = path.join(templatesDir, "quickstart", "AGENTS.md");
+    if (!fs.existsSync(sourceFile)) {
+      return false;
+    }
+    const destFile = path.join(projectDir, "AGENTS.md");
+    fs.copyFileSync(sourceFile, destFile);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function applyReplacements(targetDir, replacements) {
   function processDirectory(dir) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -332,70 +281,34 @@ async function installTownsSkills(projectDir) {
     return false;
   }
 }
-async function downloadAgentsMd(projectDir) {
-  const tempDir = `${projectDir}-agents-md-temp`;
+function parseDotenv() {
+  return (0, import_dotenv.config)({ override: false }).parsed;
+}
+function envFromAppPrivateData(parsed) {
+  const appPrivateData = parsed?.APP_PRIVATE_DATA;
+  if (!appPrivateData) {
+    return void 0;
+  }
   try {
-    const agentsMdPath = "packages/examples/agent-quickstart/AGENTS.md";
-    const latestSdkTag = getLatestSdkTag();
-    if (!latestSdkTag) {
-      return false;
-    }
-    const cloneResult = import_cross_spawn.default.sync(
-      "git",
-      [
-        "clone",
-        "--no-checkout",
-        "--depth",
-        "1",
-        "--sparse",
-        "--branch",
-        latestSdkTag,
-        "https://github.com/towns-protocol/towns.git",
-        tempDir
-      ],
-      { stdio: "pipe" }
-    );
-    if (cloneResult.status !== 0) {
-      if (fs.existsSync(tempDir)) {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-      }
-      return false;
-    }
-    const sparseResult = import_cross_spawn.default.sync("git", ["sparse-checkout", "set", agentsMdPath], {
-      stdio: "pipe",
-      cwd: tempDir
-    });
-    if (sparseResult.status !== 0) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-      return false;
-    }
-    const checkoutResult = import_cross_spawn.default.sync("git", ["checkout"], {
-      stdio: "pipe",
-      cwd: tempDir
-    });
-    if (checkoutResult.status !== 0) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-      return false;
-    }
-    const sourceFile = path.join(tempDir, agentsMdPath);
-    if (!fs.existsSync(sourceFile)) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-      return false;
-    }
-    const destFile = path.join(projectDir, "AGENTS.md");
-    fs.copyFileSync(sourceFile, destFile);
-    fs.rmSync(tempDir, { recursive: true, force: true });
-    return true;
-  } catch (error) {
-    console.error(
-      import_picocolors.default.red("Error downloading AGENTS.md:"),
-      error instanceof Error ? error.message : error
-    );
-    if (fs.existsSync(tempDir)) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-    }
-    return false;
+    return (0, import_sdk.parseAppPrivateData)(appPrivateData);
+  } catch {
+    return void 0;
+  }
+}
+function resolveAppAddress(positionalArg) {
+  if (positionalArg) {
+    return positionalArg;
+  }
+  const parsed = parseDotenv();
+  const appAddress = parsed?.APP_ADDRESS;
+  if (appAddress) {
+    return appAddress;
   }
+  return envFromAppPrivateData(parsed)?.appAddress;
+}
+function resolveRiverEnv() {
+  const parsed = parseDotenv();
+  return parsed?.RIVER_ENV ?? envFromAppPrivateData(parsed)?.env;
 }
 async function promptAuth() {
   const { method } = await (0, import_prompts.default)({
@@ -424,7 +337,7 @@ var TEMPLATES = {
   quickstart: {
     name: "Agent Quickstart",
     description: "Simple starter agent with basic commands",
-    packagePath: "agent-quickstart"
+    packagePath: "quickstart"
   }
 };
 async function init(argv) {
@@ -461,12 +374,12 @@ async function init(argv) {
   const packageManager = getPackageManager();
   const selectedTemplate = TEMPLATES[template];
   try {
-    const success = await cloneTemplate(selectedTemplate.packagePath, targetDir);
+    const success = copyTemplate(selectedTemplate.packagePath, targetDir);
     if (!success) {
-      console.error((0, import_picocolors2.red)("Failed to clone template"));
+      console.error((0, import_picocolors2.red)("Failed to copy template"));
       process.exit(1);
     }
-    const latestVersion = await getLatestTownsProtocolVersion();
+    const latestVersion = version;
     const replacements = /* @__PURE__ */ new Map([
       ["workspace:\\^", `^${latestVersion}`],
       ["workspace:\\*", `^${latestVersion}`]
@@ -491,19 +404,12 @@ async function init(argv) {
       if (skillSuccess) {
         console.log((0, import_picocolors2.green)("\u2713"), "Towns Agent Skills installed successfully!");
       } else {
-        console.log(
-          (0, import_picocolors2.yellow)("\u26A0"),
-          "Failed to install Towns Agent Skills. You can install them later with:"
-        );
+        console.log((0, import_picocolors2.yellow)("\u26A0"), "Skipping Towns Agent Skills. Install later with:");
         console.log((0, import_picocolors2.yellow)(`  cd ${projectName} && towns-agent install-skill`));
       }
-    } catch (error) {
-      console.log(
-        (0, import_picocolors2.yellow)("\u26A0"),
-        "Error installing skills:",
-        error instanceof Error ? error.message : error
-      );
-      console.log((0, import_picocolors2.yellow)(`  You can install them later with: towns-agent install-skill`));
+    } catch {
+      console.log((0, import_picocolors2.yellow)("\u26A0"), "Skipping Towns Agent Skills. Install later with:");
+      console.log((0, import_picocolors2.yellow)(`  cd ${projectName} && towns-agent install-skill`));
     }
     await initializeGitRepository(targetDir);
     printSuccess(projectName, packageManager);
@@ -522,9 +428,9 @@ function getTownsVersions(packageJson) {
   const versions = {};
   for (const deps of [packageJson.dependencies, packageJson.devDependencies]) {
     if (deps) {
-      for (const [pkg, version] of Object.entries(deps)) {
+      for (const [pkg, version2] of Object.entries(deps)) {
         if (pkg.startsWith("@towns-labs/") || pkg.startsWith("@towns-protocol/")) {
-          versions[pkg] = version;
+          versions[pkg] = version2;
         }
       }
     }
@@ -607,7 +513,7 @@ async function update(_argv) {
       console.log();
       console.log((0, import_picocolors3.cyan)("Updating AGENTS.md..."));
       try {
-        const agentsMdSuccess = await downloadAgentsMd(projectDir);
+        const agentsMdSuccess = copyAgentsMd(projectDir);
         if (agentsMdSuccess) {
           console.log((0, import_picocolors3.green)("\u2713"), "AGENTS.md updated successfully!");
         } else {
@@ -661,7 +567,7 @@ var import_picocolors5 = require("picocolors");
 var import_viem = require("viem");
 var import_accounts = require("viem/accounts");
 var import_relayer_client = require("@towns-labs/relayer-client");
-var import_sdk = require("@towns-labs/sdk");
+var import_sdk2 = require("@towns-labs/sdk");
 var import_deployments = require("@towns-labs/contracts/deployments");
 async function create(argv) {
   let ownerPrivateKey = argv.ownerPrivateKey;
@@ -694,12 +600,12 @@ async function create(argv) {
     process.exit(1);
   }
   const imageUrl = argv.imageUrl ?? await promptText("Bot image URL (optional)", true);
-  const owner = ownerPrivateKey ? await (0, import_sdk.makeSignerContextFromViem)(
+  const owner = ownerPrivateKey ? await (0, import_sdk2.makeSignerContextFromViem)(
     (0, import_accounts.privateKeyToAccount)(ownerPrivateKey),
     (0, import_accounts.generatePrivateKey)(),
     { days: 1 }
-  ) : await (0, import_sdk.makeSignerContextFromBearerToken)(bearerToken);
-  const townsConfig = (0, import_sdk.townsEnv)().makeTownsConfig();
+  ) : await (0, import_sdk2.makeSignerContextFromBearerToken)(bearerToken);
+  const townsConfig = (0, import_sdk2.townsEnv)().makeTownsConfig();
   const chainId = townsConfig.base.chainConfig.chainId;
   const addresses = (0, import_deployments.getAddressesWithFallback)(townsConfig.environmentId, chainId);
   if (!addresses?.accountProxy) {
@@ -715,7 +621,7 @@ async function create(argv) {
     },
     transport: (0, import_viem.http)(townsConfig.base.rpcUrl)
   }).extend((0, import_relayer_client.relayerActions)({ relayerUrl }));
-  const result = await (0, import_sdk.createApp)({
+  const result = await (0, import_sdk2.createApp)({
     owner,
     metadata: {
       username,
@@ -747,7 +653,7 @@ async function promptText(message, optional = false) {
 var import_prompts4 = __toESM(require("prompts"));
 var import_picocolors6 = require("picocolors");
 var import_accounts2 = require("viem/accounts");
-var import_sdk2 = require("@towns-labs/sdk");
+var import_sdk3 = require("@towns-labs/sdk");
 var import_utils5 = require("@towns-labs/utils");
 var FIELD_DEFS = [
   { flag: "username", label: "USERNAME", mask: "username", prompt: "Username" },
@@ -765,21 +671,25 @@ var FIELD_DEFS = [
 ];
 async function metadata(argv) {
   const subcommand = argv._[1];
-  const appAddress = argv._[2];
+  const appAddress = resolveAppAddress(argv._[2]);
   if (!subcommand || !["view", "update"].includes(subcommand)) {
-    console.error((0, import_picocolors6.red)("Usage: towns-agent metadata <view|update> <appAddress> [options]"));
+    console.error((0, import_picocolors6.red)("Usage: towns-agent metadata <view|update> [appAddress] [options]"));
     process.exit(1);
   }
   if (!appAddress) {
-    console.error((0, import_picocolors6.red)("App address is required."));
+    console.error(
+      (0, import_picocolors6.red)(
+        "App address is required. Provide it as an argument, or set APP_ADDRESS or APP_PRIVATE_DATA in .env."
+      )
+    );
     process.exit(1);
   }
-  const env = (0, import_sdk2.townsEnv)();
+  const env = (0, import_sdk3.townsEnv)();
   const townsConfig = env.makeTownsConfig();
   const appRegistryUrl = env.getAppRegistryUrl(townsConfig.environmentId);
   const appId = (0, import_utils5.bin_fromHexString)(appAddress);
   if (subcommand === "view") {
-    const client = (0, import_sdk2.makeAppRegistryRpcClient)(appRegistryUrl, "");
+    const client = (0, import_sdk3.makeAppRegistryRpcClient)(appRegistryUrl, "");
     const { metadata: meta } = await client.getAppMetadata({ appId });
     if (!meta) {
       console.error((0, import_picocolors6.red)("No metadata found for this app."));
@@ -807,12 +717,12 @@ async function metadata(argv) {
       bearerToken = auth.value;
     }
   }
-  const signerContext = ownerPrivateKey ? await (0, import_sdk2.makeSignerContextFromViem)(
+  const signerContext = ownerPrivateKey ? await (0, import_sdk3.makeSignerContextFromViem)(
     (0, import_accounts2.privateKeyToAccount)(ownerPrivateKey),
     (0, import_accounts2.generatePrivateKey)(),
     { days: 1 }
-  ) : await (0, import_sdk2.makeSignerContextFromBearerToken)(bearerToken);
-  const { appRegistryRpcClient } = await import_sdk2.AppRegistryService.authenticate(
+  ) : await (0, import_sdk3.makeSignerContextFromBearerToken)(bearerToken);
+  const { appRegistryRpcClient } = await import_sdk3.AppRegistryService.authenticate(
     signerContext,
     appRegistryUrl
   );
@@ -826,7 +736,7 @@ async function metadata(argv) {
       }
     }
   } else {
-    const unauthClient = (0, import_sdk2.makeAppRegistryRpcClient)(appRegistryUrl, "");
+    const unauthClient = (0, import_sdk3.makeAppRegistryRpcClient)(appRegistryUrl, "");
     const { metadata: current } = await unauthClient.getAppMetadata({ appId });
     values = {};
     for (const field of FIELD_DEFS) {
@@ -874,7 +784,7 @@ async function metadata(argv) {
 var import_prompts5 = __toESM(require("prompts"));
 var import_picocolors7 = require("picocolors");
 var import_accounts3 = require("viem/accounts");
-var import_sdk3 = require("@towns-labs/sdk");
+var import_sdk4 = require("@towns-labs/sdk");
 var import_proto = require("@towns-labs/proto");
 var import_utils7 = require("@towns-labs/utils");
 var NOTIFY_MAP = {
@@ -888,9 +798,13 @@ var NOTIFY_LABELS = {
   NONE: "No messages"
 };
 async function setup(argv) {
-  const appAddress = argv._[1];
+  const appAddress = resolveAppAddress(argv._[1]);
   if (!appAddress) {
-    console.error((0, import_picocolors7.red)("Usage: towns-agent setup <appAddress> [options]"));
+    console.error(
+      (0, import_picocolors7.red)(
+        "App address is required. Provide it as an argument, or set APP_ADDRESS or APP_PRIVATE_DATA in .env."
+      )
+    );
     process.exit(1);
   }
   let ownerPrivateKey = argv.ownerPrivateKey;
@@ -907,11 +821,18 @@ async function setup(argv) {
       bearerToken = auth.value;
     }
   }
-  const webhookUrl = argv.webhookUrl ?? await promptWebhookUrl();
+  let webhookUrl = argv.webhookUrl ?? await promptWebhookUrl();
   if (!webhookUrl) {
     console.error((0, import_picocolors7.red)("Webhook URL is required."));
     process.exit(1);
   }
+  if (argv.webhookUrl) {
+    const urlError = validateWebhookUrl(webhookUrl);
+    if (urlError !== true) {
+      console.error((0, import_picocolors7.red)(urlError));
+      process.exit(1);
+    }
+  }
   let notifyKey;
   if (argv.notify) {
     notifyKey = argv.notify.toUpperCase();
@@ -927,20 +848,39 @@ async function setup(argv) {
     );
     process.exit(1);
   }
-  const env = (0, import_sdk3.townsEnv)();
+  const env = (0, import_sdk4.townsEnv)();
   const townsConfig = env.makeTownsConfig();
   const appRegistryUrl = env.getAppRegistryUrl(townsConfig.environmentId);
   const appId = (0, import_utils7.bin_fromHexString)(appAddress);
-  const signerContext = ownerPrivateKey ? await (0, import_sdk3.makeSignerContextFromViem)(
+  const signerContext = ownerPrivateKey ? await (0, import_sdk4.makeSignerContextFromViem)(
     (0, import_accounts3.privateKeyToAccount)(ownerPrivateKey),
     (0, import_accounts3.generatePrivateKey)(),
     { days: 1 }
-  ) : await (0, import_sdk3.makeSignerContextFromBearerToken)(bearerToken);
-  const { appRegistryRpcClient } = await import_sdk3.AppRegistryService.authenticate(
+  ) : await (0, import_sdk4.makeSignerContextFromBearerToken)(bearerToken);
+  const { appRegistryRpcClient } = await import_sdk4.AppRegistryService.authenticate(
     signerContext,
     appRegistryUrl
   );
-  await appRegistryRpcClient.registerWebhook({ appId, webhookUrl });
+  try {
+    await appRegistryRpcClient.registerWebhook({ appId, webhookUrl });
+  } catch (error) {
+    if (!hasWebhookPath(webhookUrl)) {
+      const webhookUrlWithPath = appendWebhookPath(webhookUrl);
+      try {
+        await appRegistryRpcClient.registerWebhook({
+          appId,
+          webhookUrl: webhookUrlWithPath
+        });
+        console.log();
+        console.log((0, import_picocolors7.yellow)(`Registration succeeded with ${webhookUrlWithPath}`));
+        webhookUrl = webhookUrlWithPath;
+      } catch {
+        throw error;
+      }
+    } else {
+      throw error;
+    }
+  }
   await appRegistryRpcClient.setAppSettings({
     appId,
     settings: { forwardSetting }
@@ -953,12 +893,48 @@ async function setup(argv) {
   console.log();
   process.exit(0);
 }
+function hasWebhookPath(url) {
+  const trimmed = url.trim();
+  try {
+    const parsed = new URL(trimmed);
+    const normalizedPath = parsed.pathname.endsWith("/") ? parsed.pathname.slice(0, -1) : parsed.pathname;
+    return normalizedPath.endsWith("/webhook");
+  } catch {
+    return trimmed.replace(/\s*$/, "").endsWith("/webhook");
+  }
+}
+function appendWebhookPath(url) {
+  const trimmed = url.trim();
+  const parsed = new URL(trimmed);
+  const normalizedPath = parsed.pathname.endsWith("/") ? parsed.pathname.slice(0, -1) : parsed.pathname;
+  parsed.pathname = normalizedPath === "/" ? "/webhook" : `${normalizedPath}/webhook`;
+  return parsed.toString();
+}
+function validateWebhookUrl(url) {
+  const trimmed = url.trim();
+  if (!trimmed) {
+    return "Webhook URL is required";
+  }
+  try {
+    const parsed = new URL(trimmed);
+    const isLocalhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "0.0.0.0";
+    if (isLocalhost && parsed.protocol === "http:") {
+      return "Local bots must use HTTPS. Use https:// instead of http://";
+    }
+    if (isLocalhost && !parsed.port) {
+      return "Localhost URL is missing a port. Example: https://localhost:3000";
+    }
+    return true;
+  } catch {
+    return "Invalid URL format. Example: https://localhost:3000/webhook";
+  }
+}
 async function promptWebhookUrl() {
   const { value } = await (0, import_prompts5.default)({
     type: "text",
     name: "value",
     message: "Webhook URL",
-    validate: (v) => v.trim() ? true : "Webhook URL is required"
+    validate: validateWebhookUrl
   });
   return value;
 }
@@ -981,7 +957,7 @@ async function promptNotify() {
 }
 
 // src/index.ts
-var import_sdk4 = require("@towns-labs/sdk");
+var import_sdk5 = require("@towns-labs/sdk");
 
 // src/parser.ts
 var import_minimist = __toESM(require("minimist"));
@@ -1100,20 +1076,31 @@ async function main() {
     showHelp();
     return;
   }
-  if (args.env) {
-    process.env.RIVER_ENV = args.env;
-  }
-  if (!process.env.RIVER_ENV) {
-    console.error(
-      (0, import_picocolors8.red)("Environment is required. Use --env <local_dev|stage|prod> or set RIVER_ENV.")
-    );
-    process.exit(1);
-  }
-  try {
-    (0, import_sdk4.townsEnv)().makeTownsConfig();
-  } catch {
-    console.error((0, import_picocolors8.red)(`Invalid environment: ${process.env.RIVER_ENV}`));
-    process.exit(1);
+  const requiresEnv = ["create", "setup", "metadata"].includes(command);
+  if (requiresEnv) {
+    if (args.env) {
+      process.env.RIVER_ENV = args.env;
+    }
+    if (!process.env.RIVER_ENV) {
+      const resolvedEnv = resolveRiverEnv();
+      if (resolvedEnv) {
+        process.env.RIVER_ENV = resolvedEnv;
+      }
+    }
+    if (!process.env.RIVER_ENV) {
+      console.error(
+        (0, import_picocolors8.red)(
+          "Environment is required. Use --env <local_dev|stage|prod>, set RIVER_ENV, or set APP_PRIVATE_DATA in .env."
+        )
+      );
+      process.exit(1);
+    }
+    try {
+      (0, import_sdk5.townsEnv)().makeTownsConfig();
+    } catch {
+      console.error((0, import_picocolors8.red)(`Invalid environment: ${process.env.RIVER_ENV}`));
+      process.exit(1);
+    }
   }
   try {
     switch (command) {
@@ -1167,8 +1154,8 @@ ${(0, import_picocolors8.yellow)("Usage:")}
 ${(0, import_picocolors8.yellow)("Commands:")}
   ${(0, import_picocolors8.green)("init")} [project-name]     Create a new agent project
   ${(0, import_picocolors8.green)("create")}                  Create a new bot/app account interactively
-  ${(0, import_picocolors8.green)("setup")} <appAddress>      Register webhook and notification settings
-  ${(0, import_picocolors8.green)("metadata")} <view|update>  View or update app metadata
+  ${(0, import_picocolors8.green)("setup")} [appAddress]       Register webhook and notification settings
+  ${(0, import_picocolors8.green)("metadata")} <view|update> [appAddress]  View or update app metadata
   ${(0, import_picocolors8.green)("update")}                  Update @towns-labs dependencies and skills
   ${(0, import_picocolors8.green)("install-skill")}           Install Towns Agent Skills to current project
 
@@ -1188,8 +1175,10 @@ ${(0, import_picocolors8.yellow)("Update Commands Options:")}
   -e, --envFile <path>       Path to .env file (default: .env)
   --skip-agents-md           Skip updating AGENTS.md file
 
-${(0, import_picocolors8.yellow)("Global Options:")}
+${(0, import_picocolors8.yellow)("Environment Options (create, setup, metadata):")}
   --env <name>             Environment to use: local_dev, stage, prod
+
+${(0, import_picocolors8.yellow)("Global Options:")}
   -h, --help               Show this help message
 
 ${(0, import_picocolors8.yellow)("Examples:")}