@aixyz/cli 0.9.0 → 0.11.0

package/bin.ts

@@ -1,200 +1,23 @@
 #!/usr/bin/env bun
-import { program } from "commander";
-import { build } from "./build";
-import { dev } from "./dev";
-import { register } from "./register/register";
-import { update } from "./register/update";
+import { Command } from "commander";
+import { devCommand } from "./dev";
+import { buildCommand } from "./build";
+import { erc8004Command } from "./register";
 import pkg from "./package.json";
 
-function handleAction(
-  action: (options: Record<string, unknown>) => Promise<void>,
-): (options: Record<string, unknown>) => Promise<void> {
-  return async (options) => {
-    try {
-      await action(options);
-    } catch (error) {
-      if (error instanceof Error && error.name === "ExitPromptError") {
-        process.exit(130);
-      }
-      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
-    }
-  };
+const cli = new Command();
+cli.name("aixyz").description("CLI for building and deploying aixyz agents").version(pkg.version);
+
+cli.addCommand(devCommand);
+cli.addCommand(buildCommand);
+cli.addCommand(erc8004Command);
+
+try {
+  await cli.parseAsync();
+} catch (error) {
+  if (error instanceof Error && error.name === "ExitPromptError") {
+    process.exit(130);
+  }
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
 }
-
-program.name("aixyz").description("CLI for building and deploying aixyz agents").version(pkg.version);
-
-program
-  .command("dev")
-  .description("Start a local development server")
-  .option("-p, --port <port>", "Port to listen on", "3000")
-  .action(handleAction(dev));
-
-program
-  .command("build")
-  .description("Build the aixyz agent")
-  .option("--output <type>", "Output format: 'standalone' or 'vercel'")
-  .addHelpText(
-    "after",
-    `
-Details:
-  Bundles your aixyz agent for deployment.
-
-  Default behavior (auto-detected):
-    Bundles into a single executable file for Standalone at ./.aixyz/output/server.js
-
-  With --output vercel or VERCEL=1 env:
-    Generates Vercel Build Output API v3 structure at .vercel/output/
-    (Automatically detected when deploying to Vercel)
-
-  The build process:
-    1. Loads aixyz.config.ts from the current directory
-    2. Detects entrypoint (app/server.ts or auto-generates from app/agent.ts + app/tools/)
-    3. Bundles the application
-    4. Copies static assets from public/ (if present)
-
-Prerequisites:
-  - An aixyz.config.ts with a default export
-  - An entrypoint at app/server.ts, or app/agent.ts + app/tools/ for auto-generation
-
-Examples:
-  $ aixyz build                         # Build standalone (default)
-  $ aixyz build --output standalone     # Build standalone explicitly
-  $ aixyz build --output vercel         # Build for Vercel deployment
-  $ VERCEL=1 aixyz build                # Auto-detected Vercel build`,
-  )
-  .action(handleAction(build));
-
-const erc8004 = program.command("erc-8004").description("ERC-8004 IdentityRegistry operations");
-
-erc8004
-  .command("register")
-  .description("Register a new agent to the ERC-8004 IdentityRegistry")
-  .option("--url <url>", "Agent deployment URL (e.g., https://my-agent.example.com)")
-  .option("--chain <chain>", "Target chain (mainnet, sepolia, base-sepolia, localhost)")
-  .option("--rpc-url <url>", "Custom RPC URL (uses default if not provided)")
-  .option("--registry <address>", "Contract address of the IdentityRegistry (required for localhost)")
-  .option("--keystore <path>", "Path to Ethereum keystore (V3) JSON file for local signing")
-  .option("--browser", "Use browser extension wallet (any extension)")
-  .option("--broadcast", "Sign and broadcast the transaction (default: dry-run)")
-  .option("--out-dir <path>", "Write deployment result as JSON to the given directory")
-  .addHelpText(
-    "after",
-    `
-Option Details:
-  --url <url>
-      Agent deployment URL (e.g., https://my-agent.example.com).
-      The registration URI will be derived as <url>/_aixyz/erc-8004.json.
-      If omitted, you will be prompted to enter the URL interactively.
-
-  --chain <chain>
-      Target chain for registration. Supported values:
-        mainnet       Ethereum mainnet (chain ID 1)
-        sepolia       Ethereum Sepolia testnet (chain ID 11155111)
-        base-sepolia  Base Sepolia testnet (chain ID 84532)
-        localhost     Local Foundry/Anvil node (chain ID 31337)
-      If omitted, you will be prompted to select a chain interactively.
-
-  --rpc-url <url>
-      Custom RPC endpoint URL. Overrides the default RPC for the selected
-      chain. Cannot be used with --browser since the browser wallet manages
-      its own RPC connection.
-
-  --registry <address>
-      Contract address of the ERC-8004 IdentityRegistry. Only required for
-      localhost, where there is no default deployment.
-
-  --keystore <path>
-      Path to an Ethereum keystore (V3) JSON file. You will be prompted for
-      the keystore password to decrypt the private key for signing.
-
-  --browser
-      Opens a local page in your default browser for signing with any
-      EIP-6963 compatible wallet extension (MetaMask, Rabby, etc.).
-
-  --broadcast
-      Sign and broadcast the transaction on-chain. Without this flag the
-      command performs a dry-run.
-
-  --out-dir <path>
-      Directory to write the deployment result as a JSON file.
-
-Behavior:
-  If app/erc-8004.ts does not exist, you will be prompted to create it
-  (selecting supported trust mechanisms). After a successful on-chain
-  registration, the new registration entry is written back to app/erc-8004.ts.
-
-Environment Variables:
-  PRIVATE_KEY    Private key (hex, with or without 0x prefix) used for signing.
-
-Examples:
-  # Dry-run (default)
-  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain sepolia
-
-  # Sign and broadcast
-  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain sepolia --keystore ~/.foundry/keystores/default --broadcast
-  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain sepolia --browser --broadcast`,
-  )
-  .action(handleAction(register));
-
-erc8004
-  .command("update")
-  .description("Update the metadata URI of a registered agent")
-  .option("--url <url>", "New agent deployment URL (e.g., https://my-agent.example.com)")
-  .option("--rpc-url <url>", "Custom RPC URL (uses default if not provided)")
-  .option("--registry <address>", "Contract address of the IdentityRegistry (required for localhost)")
-  .option("--keystore <path>", "Path to Ethereum keystore (V3) JSON file for local signing")
-  .option("--browser", "Use browser extension wallet (any extension)")
-  .option("--broadcast", "Sign and broadcast the transaction (default: dry-run)")
-  .option("--out-dir <path>", "Write result as JSON to the given directory")
-  .addHelpText(
-    "after",
-    `
-Option Details:
-  --url <url>
-      New agent deployment URL (e.g., https://my-agent.example.com).
-      The URI will be derived as <url>/_aixyz/erc-8004.json.
-      If omitted, you will be prompted to enter the URL interactively.
-
-  --rpc-url <url>
-      Custom RPC endpoint URL. Overrides the default RPC for the selected
-      chain. Cannot be used with --browser.
-
-  --registry <address>
-      Contract address of the ERC-8004 IdentityRegistry. Only required for
-      localhost, where there is no default deployment.
-
-  --keystore <path>
-      Path to an Ethereum keystore (V3) JSON file.
-
-  --browser
-      Opens a local page in your default browser for signing with any
-      EIP-6963 compatible wallet extension (MetaMask, Rabby, etc.).
-
-  --broadcast
-      Sign and broadcast the transaction on-chain. Without this flag the
-      command performs a dry-run.
-
-  --out-dir <path>
-      Directory to write the result as a JSON file.
-
-Behavior:
-  Reads existing registrations from app/erc-8004.ts. If there is one
-  registration, confirms it. If multiple, prompts you to select which
-  one to update. The chain and registry address are derived from the
-  selected registration's agentRegistry field.
-
-Environment Variables:
-  PRIVATE_KEY    Private key (hex, with or without 0x prefix) used for signing.
-
-Examples:
-  # Dry-run (default)
-  $ aixyz erc-8004 update --url "https://new-domain.example.com"
-
-  # Sign and broadcast
-  $ aixyz erc-8004 update --url "https://new-domain.example.com" --keystore ~/.foundry/keystores/default --broadcast
-  $ aixyz erc-8004 update --url "https://new-domain.example.com" --browser --broadcast`,
-  )
-  .action(handleAction(update));
-
-program.parse();

package/build/index.ts

@@ -1,5 +1,6 @@
 import { resolve } from "path";
 import { existsSync, mkdirSync, cpSync, rmSync } from "fs";
+import { Command } from "commander";
 import { AixyzConfigPlugin } from "./AixyzConfigPlugin";
 import { AixyzServerPlugin, getEntrypointMayGenerate } from "./AixyzServerPlugin";
 import { findIconFile, copyAgentIcon, generateFavicon } from "./icons";
@@ -11,9 +12,45 @@ interface BuildOptions {
   output?: string;
 }
 
-export async function build(options: BuildOptions = {}): Promise<void> {
+export const buildCommand = new Command("build")
+  .description("Build the aixyz agent")
+  .option("--output <type>", "Output format: 'standalone' or 'vercel'")
+  .addHelpText(
+    "after",
+    `
+Details:
+  Bundles your aixyz agent for deployment.
+
+  Default behavior (auto-detected):
+    Bundles into a single executable file for Standalone at ./.aixyz/output/server.js
+
+  With --output vercel or VERCEL=1 env:
+    Generates Vercel Build Output API v3 structure at .vercel/output/
+    (Automatically detected when deploying to Vercel)
+
+  The build process:
+    1. Loads aixyz.config.ts from the current directory
+    2. Detects entrypoint (app/server.ts or auto-generates from app/agent.ts + app/tools/)
+    3. Bundles the application
+    4. Copies static assets from public/ (if present)
+
+Prerequisites:
+  - An aixyz.config.ts with a default export
+  - An entrypoint at app/server.ts, or app/agent.ts + app/tools/ for auto-generation
+
+Examples:
+  $ aixyz build                         # Build standalone (default)
+  $ aixyz build --output standalone     # Build standalone explicitly
+  $ aixyz build --output vercel         # Build for Vercel deployment
+  $ VERCEL=1 aixyz build                # Auto-detected Vercel build`,
+  )
+  .action(action);
+
+async function action(options: BuildOptions = {}): Promise<void> {
   const cwd = process.cwd();
   loadEnvConfig(cwd, false);
+  process.env.NODE_ENV = "production";
+  process.env.AIXYZ_ENV = "production";
   const entrypoint = getEntrypointMayGenerate(cwd, "build");
 
   // Determine output target: explicit CLI flag takes precedence, then config file, then auto-detect VERCEL env
@@ -44,6 +81,10 @@ async function buildBun(entrypoint: string): Promise<void> {
     target: "bun",
     format: "esm",
     sourcemap: "linked",
+    define: {
+      "process.env.NODE_ENV": JSON.stringify("production"),
+      "process.env.AIXYZ_ENV": JSON.stringify("production"),
+    },
     plugins: [AixyzConfigPlugin(), AixyzServerPlugin(entrypoint, "standalone")],
   });
 
@@ -101,6 +142,10 @@ async function buildVercel(entrypoint: string): Promise<void> {
     target: "bun",
     format: "esm",
     sourcemap: "linked",
+    define: {
+      "process.env.NODE_ENV": JSON.stringify("production"),
+      "process.env.AIXYZ_ENV": JSON.stringify("production"),
+    },
     plugins: [AixyzConfigPlugin(), AixyzServerPlugin(entrypoint, "vercel")],
   });
 

package/dev/index.ts

@@ -1,14 +1,22 @@
 import { resolve, relative } from "path";
 import { existsSync, watch } from "fs";
 import { loadEnvConfig } from "@next/env";
+import { Command } from "commander";
 import { getEntrypointMayGenerate } from "../build/AixyzServerPlugin";
 import pkg from "../package.json";
 
-export async function dev(options: { port?: string }): Promise<void> {
+export const devCommand = new Command("dev")
+  .description("Start a local development server")
+  .option("-p, --port <port>", "Port to listen on", "3000")
+  .action(action);
+
+async function action(options: { port?: string }): Promise<void> {
   const cwd = process.cwd();
 
   // Load environment config
   const { loadedEnvFiles } = loadEnvConfig(cwd, true);
+  process.env.NODE_ENV = "development";
+  process.env.AIXYZ_ENV = "development";
   const envFileNames = loadedEnvFiles.map((f) => relative(cwd, f.path));
 
   const port = options.port || process.env.PORT || "3000";
@@ -35,7 +43,7 @@ export async function dev(options: { port?: string }): Promise<void> {
       cwd,
       stdout: "inherit",
       stderr: "inherit",
-      env: process.env,
+      env: { ...process.env, NODE_ENV: "development", AIXYZ_ENV: "development" },
     });
     child.exited.then((code) => {
       if (!restarting && code !== 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixyz/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Payment-native SDK for AI Agent",
   "keywords": [
     "ai",
@@ -27,8 +27,8 @@
     "bin.ts"
   ],
   "dependencies": {
-    "@aixyz/config": "0.9.0",
-    "@aixyz/erc-8004": "0.9.0",
+    "@aixyz/config": "0.11.0",
+    "@aixyz/erc-8004": "0.11.0",
     "@inquirer/prompts": "^8.3.0",
     "@next/env": "^16.1.6",
     "boxen": "^8.0.1",

package/register/index.ts

@@ -1,8 +1,146 @@
+import { Command } from "commander";
+import { register } from "./register";
+import { update } from "./update";
 import type { WalletOptions } from "./wallet";
 
 export interface BaseOptions extends WalletOptions {
-  chain?: string;
   rpcUrl?: string;
   registry?: string;
   outDir?: string;
 }
+
+export const erc8004Command = new Command("erc-8004").description("ERC-8004 IdentityRegistry operations");
+
+erc8004Command
+  .command("register")
+  .description("Register a new agent to the ERC-8004 IdentityRegistry")
+  .option("--url <url>", "Agent deployment URL (e.g., https://my-agent.example.com)")
+  .option("--chain-id <chainId>", "Target chain by numeric chain ID", parseInt)
+  .option("--rpc-url <url>", "Custom RPC URL (uses default if not provided)")
+  .option("--registry <address>", "Contract address of the IdentityRegistry (required for localhost and custom chains)")
+  .option("--keystore <path>", "Path to Ethereum keystore (V3) JSON file for local signing")
+  .option("--browser", "Use browser extension wallet (any extension)")
+  .option("--broadcast", "Sign and broadcast the transaction (default: dry-run)")
+  .option("--out-dir <path>", "Write deployment result as JSON to the given directory")
+  .addHelpText(
+    "after",
+    `
+Option Details:
+  --url <url>
+      Agent deployment URL (e.g., https://my-agent.example.com).
+      The registration URI will be derived as <url>/_aixyz/erc-8004.json.
+      If omitted, you will be prompted to enter the URL interactively.
+
+  --chain-id <chainId>
+      Target chain by numeric chain ID. Supported chain IDs include:
+        1 (mainnet), 8453 (base), 42161 (arbitrum), 10 (optimism),
+        137 (polygon), 56 (bsc), 43114 (avalanche), 11155111 (sepolia),
+        84532 (base-sepolia), and more (see @aixyz/erc-8004).
+      If omitted, you will be prompted to select a chain interactively.
+      Use any custom EVM chain ID with --rpc-url for BYO chains.
+
+  --rpc-url <url>
+      Custom RPC endpoint URL. Overrides the default RPC for the selected
+      chain. Required when using a custom chain ID with no default deployment.
+      Cannot be used with --browser since the browser wallet manages
+      its own RPC connection.
+
+  --registry <address>
+      Contract address of the ERC-8004 IdentityRegistry. Required for
+      localhost and custom chains, where there is no default deployment.
+
+  --keystore <path>
+      Path to an Ethereum keystore (V3) JSON file. You will be prompted for
+      the keystore password to decrypt the private key for signing.
+
+  --browser
+      Opens a local page in your default browser for signing with any
+      EIP-6963 compatible wallet extension (MetaMask, Rabby, etc.).
+
+  --broadcast
+      Sign and broadcast the transaction on-chain. Without this flag the
+      command performs a dry-run.
+
+  --out-dir <path>
+      Directory to write the deployment result as a JSON file.
+
+Behavior:
+  If app/erc-8004.ts does not exist, you will be prompted to create it
+  (selecting supported trust mechanisms). After a successful on-chain
+  registration, the new registration entry is written back to app/erc-8004.ts.
+
+Environment Variables:
+  PRIVATE_KEY    Private key (hex, with or without 0x prefix) used for signing.
+
+Examples:
+  # Dry-run (default)
+  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain-id 11155111
+
+  # Sign and broadcast (known chain)
+  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain-id 84532 --keystore ~/.foundry/keystores/default --broadcast
+  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain-id 84532 --browser --broadcast
+
+  # BYO: register on any custom EVM chain
+  $ aixyz erc-8004 register --url "https://my-agent.example.com" --chain-id 999999 --rpc-url https://my-rpc.example.com --registry 0xABCD... --broadcast`,
+  )
+  .action(register);
+
+erc8004Command
+  .command("update")
+  .description("Update the metadata URI of a registered agent")
+  .option("--url <url>", "New agent deployment URL (e.g., https://my-agent.example.com)")
+  .option("--rpc-url <url>", "Custom RPC URL (uses default if not provided)")
+  .option("--registry <address>", "Contract address of the IdentityRegistry (required for localhost)")
+  .option("--keystore <path>", "Path to Ethereum keystore (V3) JSON file for local signing")
+  .option("--browser", "Use browser extension wallet (any extension)")
+  .option("--broadcast", "Sign and broadcast the transaction (default: dry-run)")
+  .option("--out-dir <path>", "Write result as JSON to the given directory")
+  .addHelpText(
+    "after",
+    `
+Option Details:
+  --url <url>
+      New agent deployment URL (e.g., https://my-agent.example.com).
+      The URI will be derived as <url>/_aixyz/erc-8004.json.
+      If omitted, you will be prompted to enter the URL interactively.
+
+  --rpc-url <url>
+      Custom RPC endpoint URL. Overrides the default RPC for the selected
+      chain. Cannot be used with --browser.
+
+  --registry <address>
+      Contract address of the ERC-8004 IdentityRegistry. Only required for
+      localhost, where there is no default deployment.
+
+  --keystore <path>
+      Path to an Ethereum keystore (V3) JSON file.
+
+  --browser
+      Opens a local page in your default browser for signing with any
+      EIP-6963 compatible wallet extension (MetaMask, Rabby, etc.).
+
+  --broadcast
+      Sign and broadcast the transaction on-chain. Without this flag the
+      command performs a dry-run.
+
+  --out-dir <path>
+      Directory to write the result as a JSON file.
+
+Behavior:
+  Reads existing registrations from app/erc-8004.ts. If there is one
+  registration, confirms it. If multiple, prompts you to select which
+  one to update. The chain and registry address are derived from the
+  selected registration's agentRegistry field.
+
+Environment Variables:
+  PRIVATE_KEY    Private key (hex, with or without 0x prefix) used for signing.
+
+Examples:
+  # Dry-run (default)
+  $ aixyz erc-8004 update --url "https://new-domain.example.com"
+
+  # Sign and broadcast
+  $ aixyz erc-8004 update --url "https://new-domain.example.com" --keystore ~/.foundry/keystores/default --broadcast
+  $ aixyz erc-8004 update --url "https://new-domain.example.com" --browser --broadcast`,
+  )
+  .action(update);

package/register/register.ts

@@ -1,17 +1,18 @@
 import { encodeFunctionData, formatEther, parseEventLogs, type Chain, type Log } from "viem";
 import { IdentityRegistryAbi } from "@aixyz/erc-8004";
-import { selectWalletMethod, type WalletOptions } from "./wallet";
+import { selectWalletMethod } from "./wallet";
 import { signTransaction } from "./wallet/sign";
 import {
-  resolveChainConfig,
+  resolveChainConfigById,
   selectChain,
   resolveRegistryAddress,
   validateBrowserRpcConflict,
   getExplorerUrl,
+  CHAINS,
 } from "./utils/chain";
 import { writeResultJson } from "./utils/result";
 import { label, truncateUri, broadcastAndConfirm, logSignResult } from "./utils/transaction";
-import { promptAgentUrl, promptSupportedTrust, deriveAgentUri } from "./utils/prompt";
+import { promptAgentUrl, promptSupportedTrust, promptRegistryAddress, deriveAgentUri } from "./utils/prompt";
 import { hasErc8004File, createErc8004File, writeRegistrationEntry } from "./utils/erc8004-file";
 import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
@@ -20,7 +21,7 @@ import type { BaseOptions } from "./index";
 
 export interface RegisterOptions extends BaseOptions {
   url?: string;
-  chain?: string;
+  chainId?: number;
 }
 
 export async function register(options: RegisterOptions): Promise<void> {
@@ -47,9 +48,10 @@ export async function register(options: RegisterOptions): Promise<void> {
   }
 
   // Step 3: Select chain
-  const chainName = options.chain ?? (await selectChain());
-  const chainConfig = resolveChainConfig(chainName);
-  const registryAddress = resolveRegistryAddress(chainName, chainConfig.chainId, options.registry);
+  const chainId = options.chainId ?? (await selectChain());
+  const chainConfig = resolveChainConfigById(chainId, options.rpcUrl);
+  const chainName = Object.entries(CHAINS).find(([, c]) => c.chainId === chainId)?.[0] ?? `chain-${chainId}`;
+  const registryAddress = resolveRegistryAddress(chainId, options.registry) ?? (await promptRegistryAddress());
 
   // Step 4: Encode transaction
   const data = encodeFunctionData({

package/register/update.ts

@@ -2,13 +2,7 @@ import { encodeFunctionData, formatEther, parseEventLogs, type Chain, type Log }
 import { IdentityRegistryAbi } from "@aixyz/erc-8004";
 import { selectWalletMethod } from "./wallet";
 import { signTransaction } from "./wallet/sign";
-import {
-  resolveChainConfig,
-  resolveRegistryAddress,
-  validateBrowserRpcConflict,
-  getExplorerUrl,
-  CHAINS,
-} from "./utils/chain";
+import { resolveChainConfigById, validateBrowserRpcConflict, getExplorerUrl, CHAINS } from "./utils/chain";
 import { writeResultJson } from "./utils/result";
 import { label, truncateUri, broadcastAndConfirm, logSignResult } from "./utils/transaction";
 import { promptAgentUrl, promptSelectRegistration, deriveAgentUri } from "./utils/prompt";
@@ -42,7 +36,7 @@ export async function update(options: UpdateOptions): Promise<void> {
   const chainId = Number(parts[1]);
   const registryAddress = parts.slice(2).join(":") as `0x${string}`;
   const chainName = Object.entries(CHAINS).find(([, config]) => config.chainId === chainId)?.[0] ?? `chain-${chainId}`;
-  const chainConfig = resolveChainConfig(chainName);
+  const chainConfig = resolveChainConfigById(chainId, options.rpcUrl);
 
   // Step 4: Get new agent URL and derive URI
   const agentUrl = options.url ?? (await promptAgentUrl());

package/register/utils/chain.ts

@@ -1,20 +1,128 @@
-import { isAddress, type Chain } from "viem";
-import { mainnet, sepolia, baseSepolia, foundry } from "viem/chains";
+import { isAddress, defineChain, type Chain } from "viem";
+import {
+  abstract,
+  abstractTestnet,
+  arbitrum,
+  arbitrumSepolia,
+  avalanche,
+  avalancheFuji,
+  base,
+  baseSepolia,
+  bsc,
+  bscTestnet,
+  celo,
+  celoSepolia,
+  foundry,
+  gnosis,
+  linea,
+  lineaSepolia,
+  mainnet,
+  mantle,
+  mantleSepoliaTestnet,
+  megaeth,
+  monad,
+  monadTestnet,
+  optimism,
+  optimismSepolia,
+  polygon,
+  polygonAmoy,
+  scroll,
+  scrollSepolia,
+  sepolia,
+  taiko,
+} from "viem/chains";
 import { CHAIN_ID, getIdentityRegistryAddress } from "@aixyz/erc-8004";
-import { select } from "@inquirer/prompts";
+import { input, select } from "@inquirer/prompts";
 
 export interface ChainConfig {
   chain: Chain;
   chainId: number;
 }
 
+// Maps supported chain IDs to viem Chain objects (derived from @aixyz/erc-8004 CHAIN_ID)
+const VIEM_CHAIN_BY_ID: Record<number, Chain> = {
+  [CHAIN_ID.ABSTRACT]: abstract,
+  [CHAIN_ID.ARBITRUM]: arbitrum,
+  [CHAIN_ID.AVALANCHE]: avalanche,
+  [CHAIN_ID.BASE]: base,
+  [CHAIN_ID.BSC]: bsc,
+  [CHAIN_ID.CELO]: celo,
+  [CHAIN_ID.GNOSIS]: gnosis,
+  [CHAIN_ID.LINEA]: linea,
+  [CHAIN_ID.MAINNET]: mainnet,
+  [CHAIN_ID.MANTLE]: mantle,
+  [CHAIN_ID.MEGAETH]: megaeth,
+  [CHAIN_ID.MONAD]: monad,
+  [CHAIN_ID.OPTIMISM]: optimism,
+  [CHAIN_ID.POLYGON]: polygon,
+  [CHAIN_ID.SCROLL]: scroll,
+  [CHAIN_ID.TAIKO]: taiko,
+  [CHAIN_ID.ABSTRACT_TESTNET]: abstractTestnet,
+  [CHAIN_ID.ARBITRUM_SEPOLIA]: arbitrumSepolia,
+  [CHAIN_ID.AVALANCHE_FUJI]: avalancheFuji,
+  [CHAIN_ID.BASE_SEPOLIA]: baseSepolia,
+  [CHAIN_ID.BSC_TESTNET]: bscTestnet,
+  [CHAIN_ID.CELO_SEPOLIA]: celoSepolia,
+  [CHAIN_ID.LINEA_SEPOLIA]: lineaSepolia,
+  [CHAIN_ID.MANTLE_SEPOLIA]: mantleSepoliaTestnet,
+  [CHAIN_ID.MONAD_TESTNET]: monadTestnet,
+  [CHAIN_ID.OPTIMISM_SEPOLIA]: optimismSepolia,
+  [CHAIN_ID.POLYGON_AMOY]: polygonAmoy,
+  [CHAIN_ID.SCROLL_SEPOLIA]: scrollSepolia,
+  [CHAIN_ID.SEPOLIA]: sepolia,
+  31337: foundry,
+};
+
+// Build CHAINS from CHAIN_ID as the single source of truth from @aixyz/erc-8004.
+// Chain names are derived from CHAIN_ID keys: lowercase with underscores replaced by hyphens.
 export const CHAINS: Record<string, ChainConfig> = {
-  mainnet: { chain: mainnet, chainId: CHAIN_ID.MAINNET },
-  sepolia: { chain: sepolia, chainId: CHAIN_ID.SEPOLIA },
-  "base-sepolia": { chain: baseSepolia, chainId: CHAIN_ID.BASE_SEPOLIA },
+  ...Object.fromEntries(
+    (Object.entries(CHAIN_ID) as [string, number][])
+      .filter(([, id]) => id in VIEM_CHAIN_BY_ID)
+      .map(([key, id]) => [key.toLowerCase().replace(/_/g, "-"), { chain: VIEM_CHAIN_BY_ID[id]!, chainId: id }]),
+  ),
   localhost: { chain: foundry, chainId: 31337 },
 };
 
+// Priority-ordered chain IDs for interactive selection — most popular first.
+const CHAIN_SELECTION_ORDER: number[] = [
+  // Popular mainnets
+  CHAIN_ID.MAINNET,
+  CHAIN_ID.BASE,
+  CHAIN_ID.ARBITRUM,
+  CHAIN_ID.OPTIMISM,
+  CHAIN_ID.POLYGON,
+  CHAIN_ID.BSC,
+  CHAIN_ID.AVALANCHE,
+  CHAIN_ID.SCROLL,
+  CHAIN_ID.LINEA,
+  CHAIN_ID.CELO,
+  CHAIN_ID.GNOSIS,
+  CHAIN_ID.TAIKO,
+  CHAIN_ID.MANTLE,
+  CHAIN_ID.MONAD,
+  CHAIN_ID.MEGAETH,
+  CHAIN_ID.ABSTRACT,
+  // Popular testnets
+  CHAIN_ID.SEPOLIA,
+  CHAIN_ID.BASE_SEPOLIA,
+  CHAIN_ID.ARBITRUM_SEPOLIA,
+  CHAIN_ID.OPTIMISM_SEPOLIA,
+  CHAIN_ID.POLYGON_AMOY,
+  CHAIN_ID.AVALANCHE_FUJI,
+  CHAIN_ID.BSC_TESTNET,
+  CHAIN_ID.SCROLL_SEPOLIA,
+  CHAIN_ID.LINEA_SEPOLIA,
+  CHAIN_ID.CELO_SEPOLIA,
+  CHAIN_ID.MANTLE_SEPOLIA,
+  CHAIN_ID.MONAD_TESTNET,
+  CHAIN_ID.ABSTRACT_TESTNET,
+  // Special
+  31337,
+];
+
+const OTHER_CHAIN_ID = -1;
+
 export function resolveChainConfig(chainName: string): ChainConfig {
   const config = CHAINS[chainName];
   if (!config) {
@@ -23,24 +131,73 @@ export function resolveChainConfig(chainName: string): ChainConfig {
   return config;
 }
 
-export async function selectChain(): Promise<string> {
-  return select({
-    message: "Select target chain:",
-    choices: Object.keys(CHAINS).map((name) => ({ name, value: name })),
-  });
+// Resolve chain config by numeric chain ID, supporting BYO chains via rpcUrl.
+// For known chain IDs the viem chain object is used directly.
+// For unknown chain IDs, a minimal chain is constructed using defineChain (requires rpcUrl).
+export function resolveChainConfigById(chainId: number, rpcUrl?: string): ChainConfig {
+  const chain = VIEM_CHAIN_BY_ID[chainId];
+  if (chain) {
+    return { chain, chainId };
+  }
+  if (!rpcUrl) {
+    throw new Error(`Unknown chain ID ${chainId}. Provide --rpc-url to register on a custom chain.`);
+  }
+  return {
+    chain: defineChain({
+      id: chainId,
+      name: `chain-${chainId}`,
+      nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+      rpcUrls: { default: { http: [rpcUrl] } },
+    }),
+    chainId,
+  };
+}
+
+// Prompt user to select a chain interactively, returning the numeric chain ID.
+// Chains are sorted by popularity. "Other" allows entering any custom chain ID.
+export async function selectChain(): Promise<number> {
+  const chainById = new Map(Object.values(CHAINS).map((c) => [c.chainId, c]));
+  const nameById = new Map(Object.entries(CHAINS).map(([name, c]) => [c.chainId, name]));
+
+  const choices = CHAIN_SELECTION_ORDER.filter((id) => chainById.has(id)).map((id) => ({
+    name: `${nameById.get(id) ?? `chain-${id}`} (${id})`,
+    value: id,
+  }));
+  choices.push({ name: "Other (enter chain ID)", value: OTHER_CHAIN_ID });
+
+  const selected = await select({ message: "Select target chain:", choices });
+
+  if (selected === OTHER_CHAIN_ID) {
+    const raw = await input({
+      message: "Enter chain ID:",
+      validate: (v) => {
+        const n = parseInt(v, 10);
+        return Number.isInteger(n) && n > 0 ? true : "Must be a positive integer";
+      },
+    });
+    return parseInt(raw, 10);
+  }
+
+  return selected;
 }
 
-export function resolveRegistryAddress(chainName: string, chainId: number, registry?: string): `0x${string}` {
+// Returns the registry address if known, or null if no default exists for the chain (requires interactive prompt).
+// Throws only for an explicitly invalid registry address.
+export function resolveRegistryAddress(chainId: number, registry?: string): `0x${string}` | null {
   if (registry) {
     if (!isAddress(registry)) {
       throw new Error(`Invalid registry address: ${registry}`);
     }
     return registry as `0x${string}`;
   }
-  if (chainName === "localhost") {
-    throw new Error("--registry is required for localhost (no default contract deployment)");
+  if (chainId === 31337) {
+    return null;
+  }
+  try {
+    return getIdentityRegistryAddress(chainId) as `0x${string}`;
+  } catch {
+    return null;
   }
-  return getIdentityRegistryAddress(chainId) as `0x${string}`;
 }
 
 export function validateBrowserRpcConflict(browser: boolean | undefined, rpcUrl: string | undefined): void {

package/register/utils/prompt.ts

@@ -1,23 +1,7 @@
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
+import { isAddress } from "viem";
 import type { RegistrationEntry } from "@aixyz/erc-8004/schemas/registration";
 
-export async function promptAgentId(): Promise<string> {
-  return input({
-    message: "Agent ID (token ID) to update:",
-    validate: (value) => {
-      const n = Number(value);
-      if (value.trim() === "" || !Number.isInteger(n) || n < 0) return "Must be a non-negative integer";
-      return true;
-    },
-  });
-}
-
-export async function promptUri(): Promise<string> {
-  return input({
-    message: "New agent metadata URI or path to .json file (leave empty to clear):",
-  });
-}
-
 export async function promptAgentUrl(): Promise<string> {
   return input({
     message: "Agent deployment URL (e.g., https://my-agent.example.com):",
@@ -71,6 +55,14 @@ export async function promptSelectRegistration(registrations: RegistrationEntry[
   });
 }
 
+export async function promptRegistryAddress(): Promise<`0x${string}`> {
+  const value = await input({
+    message: "IdentityRegistry contract address (no default for this chain):",
+    validate: (v) => (isAddress(v) ? true : "Must be a valid Ethereum address (0x…)"),
+  });
+  return value as `0x${string}`;
+}
+
 export function deriveAgentUri(url: string): string {
   // Ensure no trailing slash before appending path
   const base = url.replace(/\/+$/, "");

package/register/utils.test.ts

@@ -1,81 +0,0 @@
-import { describe, expect, test, afterAll, beforeAll } from "bun:test";
-import { rmSync } from "fs";
-import { mkdir } from "node:fs/promises";
-import { resolveUri } from "./utils";
-import { join } from "path";
-
-describe("resolveUri", () => {
-  const testDir = join(import.meta.dir, "__test_fixtures__");
-  const testJsonPath = join(testDir, "test-metadata.json");
-  const testMetadata = { name: "Test Agent", description: "A test agent" };
-
-  beforeAll(() => {
-    // ensure test directory exists
-    mkdir(testDir, { recursive: true });
-  });
-
-  afterAll(() => {
-    // clean up test directory
-    rmSync(testDir, { recursive: true, force: true });
-  });
-
-  test("returns ipfs:// URIs unchanged", () => {
-    const uri = "ipfs://QmTest123";
-    expect(resolveUri(uri)).toStrictEqual(uri);
-  });
-
-  test("returns https:// URIs unchanged", () => {
-    const uri = "https://example.com/metadata.json";
-    expect(resolveUri(uri)).toStrictEqual(uri);
-  });
-
-  test("returns http:// URIs unchanged", () => {
-    const uri = "http://example.com/metadata.json";
-    expect(resolveUri(uri)).toStrictEqual(uri);
-  });
-
-  test("converts .json file to base64 data URI", async () => {
-    await Bun.write(testJsonPath, JSON.stringify(testMetadata));
-
-    try {
-      const result = resolveUri(testJsonPath);
-      expect(result.startsWith("data:application/json;base64,")).toStrictEqual(true);
-
-      // Decode and verify content
-      const base64 = result.replace("data:application/json;base64,", "");
-      const decoded = JSON.parse(Buffer.from(base64, "base64").toString("utf-8"));
-      expect(decoded).toStrictEqual(testMetadata);
-    } finally {
-      await Bun.file(testJsonPath).unlink();
-    }
-  });
-
-  test("throws for directory path", async () => {
-    await mkdir(testDir, { recursive: true });
-    const dirWithJsonSuffix = join(testDir, "not-a-file.json");
-    await mkdir(dirWithJsonSuffix, { recursive: true });
-
-    try {
-      expect(() => resolveUri(dirWithJsonSuffix)).toThrow(Error);
-      expect(() => resolveUri(dirWithJsonSuffix)).toThrow("Not a file");
-    } finally {
-      rmSync(dirWithJsonSuffix, { recursive: true, force: true });
-    }
-  });
-
-  test("throws for non-existent .json file", () => {
-    expect(() => resolveUri("./non-existent.json")).toThrow(Error);
-    expect(() => resolveUri("./non-existent.json")).toThrow("File not found");
-  });
-
-  test("throws for invalid JSON content", async () => {
-    await Bun.write(testJsonPath, "not valid json {{{");
-
-    try {
-      expect(() => resolveUri(testJsonPath)).toThrow(Error);
-      expect(() => resolveUri(testJsonPath)).toThrow("Invalid JSON");
-    } finally {
-      await Bun.file(testJsonPath).unlink();
-    }
-  });
-});

package/register/utils.ts

@@ -1,38 +0,0 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
-
-export function resolveUri(uri: string): string {
-  // Return as-is for URLs (ipfs://, https://, data:, etc.)
-  if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("ipfs://") || uri.startsWith("data:")) {
-    return uri;
-  }
-
-  // Check if it's a file path (ends with .json or exists as a file)
-  if (uri.endsWith(".json") || existsSync(uri)) {
-    const filePath = resolve(uri);
-
-    if (!existsSync(filePath)) {
-      throw new Error(`File not found: ${filePath}`);
-    }
-
-    if (!statSync(filePath).isFile()) {
-      throw new Error(`Not a file: ${filePath}`);
-    }
-
-    const content = readFileSync(filePath, "utf-8");
-
-    // Validate it's valid JSON
-    try {
-      JSON.parse(content);
-    } catch {
-      throw new Error(`Invalid JSON in file: ${filePath}`);
-    }
-
-    // Convert to base64 data URI
-    const base64 = Buffer.from(content).toString("base64");
-    return `data:application/json;base64,${base64}`;
-  }
-
-  // Return as-is for other URIs
-  return uri;
-}