@aixyz/cli 0.9.0 → 0.10.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,7 +12,41 @@ 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);
   const entrypoint = getEntrypointMayGenerate(cwd, "build");

package/dev/index.ts

@@ -1,10 +1,16 @@
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixyz/cli",
-  "version": "0.9.0",
+  "version": "0.10.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.10.0",
+    "@aixyz/erc-8004": "0.10.0",
     "@inquirer/prompts": "^8.3.0",
     "@next/env": "^16.1.6",
     "boxen": "^8.0.1",

package/register/index.ts

@@ -1,3 +1,6 @@
+import { Command } from "commander";
+import { register } from "./register";
+import { update } from "./update";
 import type { WalletOptions } from "./wallet";
 
 export interface BaseOptions extends WalletOptions {
@@ -6,3 +9,135 @@ export interface BaseOptions extends WalletOptions {
   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 <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(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,6 +1,6 @@
 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,

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 { resolveChainConfig, 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";

package/register/utils/prompt.ts

@@ -1,23 +1,6 @@
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
 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):",

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;
-}