@bankofai/x402-cli 1.0.0-beta.0 → 1.0.0-beta.1

package/README.md

@@ -29,6 +29,18 @@ Run the compiled CLI:
 node dist/cli.js <command> [options]
 ```
 
+Common CLI options:
+
+```bash
+x402-cli --help
+x402-cli --version
+x402-cli pay --help
+```
+
+Output is human-readable by default. Add `--json` to commands such as `pay`,
+`serve`, `gateway check`, and `catalog search` for a stable machine-readable
+envelope with `ok`, `command`, `result`, or structured `error` fields.
+
 ## Commands
 
 ### Serve
@@ -96,10 +108,10 @@ Aliases accepted:
 
 ## Facilitator
 
-Set a facilitator URL when needed:
+Pass a facilitator URL when needed:
 
 ```bash
-FACILITATOR_URL=https://facilitator.bankofai.io
+x402-cli serve --facilitator-url https://facilitator.bankofai.io ...
 ```
 
 CLI payment challenges and payload selection always emit `scheme: "exact"` for

package/dist/cli.js

@@ -2,24 +2,58 @@
 import http from "node:http";
 import { setTimeout as delay } from "node:timers/promises";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { createPaymentPayload, decodeRequired, decodeResponse, encodeRequired, encodeResponse, encodeSignature, headers } from "./x402.js";
-import { getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
+import { findTokenByAddress, getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
+const BOOLEAN_FLAGS = new Set(["daemon", "dry-run", "help", "human", "include-blocked", "json", "version"]);
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const positional = [];
     const options = {};
     for (let i = 0; i < rest.length; i += 1) {
         const item = rest[i];
+        if (item === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (item === "-V") {
+            options.version = true;
+            continue;
+        }
+        if (item === "-d") {
+            options.daemon = true;
+            continue;
+        }
+        if (item === "-n") {
+            const next = rest[i + 1];
+            if (!next || next.startsWith("-")) {
+                options.limit = true;
+            }
+            else {
+                options.limit = next;
+                i += 1;
+            }
+            continue;
+        }
         if (!item.startsWith("--")) {
             positional.push(item);
             continue;
         }
-        const key = item.slice(2);
+        const eq = item.indexOf("=");
+        const key = eq > 2 ? item.slice(2, eq) : item.slice(2);
+        const inline = eq > 2 ? item.slice(eq + 1) : undefined;
         const next = rest[i + 1];
-        if (!next || next.startsWith("--")) {
+        if (inline !== undefined) {
+            options[key] = inline;
+        }
+        else if (BOOLEAN_FLAGS.has(key)) {
+            options[key] = true;
+        }
+        else if (!next || next.startsWith("-")) {
             options[key] = true;
         }
         else {
@@ -35,10 +69,25 @@ function parseArgs(argv) {
     }
     return { command, positional, options };
 }
+function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 function opt(options, key, fallback) {
     const value = options[key];
     return typeof value === "string" ? value : fallback;
 }
+function hasFlag(options, key) {
+    return options[key] === true;
+}
+function outputMode(options) {
+    return hasFlag(options, "json") ? "json" : "human";
+}
 function optAll(options, key) {
     const value = options[key];
     if (Array.isArray(value))
@@ -48,6 +97,247 @@ function optAll(options, key) {
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function emit(args) {
+    const mode = args.mode ?? "human";
+    if (mode === "json") {
+        const envelope = {
+            ok: !args.error,
+            command: args.command,
+        };
+        if (args.network)
+            envelope.network = args.network;
+        if (args.scheme)
+            envelope.scheme = args.scheme;
+        if (args.error)
+            envelope.error = args.error;
+        else
+            envelope.result = args.result ?? null;
+        printJson(envelope);
+        return;
+    }
+    if (args.error) {
+        process.stderr.write(`ERROR ${args.command}: ${args.error.code}\n`);
+        process.stderr.write(`  ${args.error.message}\n`);
+        if (args.error.hint)
+            process.stderr.write(`  hint: ${args.error.hint}\n`);
+        return;
+    }
+    const suffix = [args.network, args.scheme].filter(Boolean).join(" ");
+    process.stdout.write(`OK ${args.command}${suffix ? ` (${suffix})` : ""}\n`);
+    if (args.result && typeof args.result === "object" && !Array.isArray(args.result)) {
+        for (const [key, value] of Object.entries(args.result)) {
+            if (value === undefined)
+                continue;
+            if (value && typeof value === "object") {
+                process.stdout.write(`  ${key}: ${JSON.stringify(value)}\n`);
+            }
+            else {
+                process.stdout.write(`  ${key}: ${value}\n`);
+            }
+        }
+    }
+    else if (args.result !== undefined) {
+        process.stdout.write(`  ${args.result}\n`);
+    }
+}
+function classify(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes("missing private key") || lower.includes("could not find a wallet")) {
+        return {
+            code: "WALLET_NOT_CONFIGURED",
+            message,
+            hint: "Set PRIVATE_KEY, TRON_PRIVATE_KEY, EVM_PRIVATE_KEY, or configure agent-wallet with a payer wallet.",
+        };
+    }
+    if (lower.includes("wallets_config") || lower.includes("wallet config")) {
+        return {
+            code: "WALLET_CONFIG_CORRUPT",
+            message,
+            hint: "Check ~/.agent-wallet/wallets_config.json or recreate the local agent-wallet configuration.",
+        };
+    }
+    if (lower.includes("does not exist") && lower.includes("account [t")) {
+        return {
+            code: "TRON_ACCOUNT_NOT_ACTIVATED",
+            message,
+            hint: "Activate the TRON address by sending it a small amount of TRX before signing contract calls.",
+        };
+    }
+    if (lower.includes("permit2_insufficient_balance") || lower.includes("insufficient") && lower.includes("balance")) {
+        return {
+            code: "INSUFFICIENT_TOKEN_BALANCE",
+            message,
+            hint: "Fund the payer address with the exact token and network advertised by the provider, then retry.",
+        };
+    }
+    if (lower.includes("transfer_from_failed") || lower.includes("transferfrom failed")) {
+        return {
+            code: "TOKEN_TRANSFER_FAILED",
+            message,
+            hint: "Check token balance, token contract, payer address, and that the selected x402 route matches the provider requirement.",
+        };
+    }
+    if (lower.includes("insufficient funds for gas") || lower.includes("insufficient gas") || lower.includes("energy")) {
+        return {
+            code: "INSUFFICIENT_GAS",
+            message,
+            hint: "Fund the payer address with the native gas token for this network.",
+        };
+    }
+    if (lower.includes("deadline") || lower.includes("expired")) {
+        return {
+            code: "DEADLINE_OR_CLOCK_SKEW",
+            message,
+            hint: "Check local clock sync and retry with a fresh payment requirement.",
+        };
+    }
+    if (lower.includes("permittransferfrom") || lower.includes("invalid signature") || lower.includes("permit reverted")) {
+        return {
+            code: "PERMIT_REVERTED",
+            message,
+            hint: "The token or Permit2 contract rejected the signature; retry with a fresh requirement and verify token/network support.",
+        };
+    }
+    if (lower.includes("tokenregistry") && lower.includes("import")) {
+        return {
+            code: "SDK_API_DRIFT",
+            message,
+            hint: "Installed x402 SDK packages do not match this CLI; reinstall @bankofai/x402-cli and SDK dependencies.",
+        };
+    }
+    if (lower.includes("429") || lower.includes("too many requests") || lower.includes("rate limit")) {
+        return {
+            code: "RATE_LIMITED",
+            message,
+            hint: "Wait briefly and retry; the upstream service or RPC is rate limiting requests.",
+        };
+    }
+    if (lower.includes("402 response missing")) {
+        return {
+            code: "INVALID_X402_RESPONSE",
+            message,
+            hint: "The endpoint returned HTTP 402 without a PAYMENT-REQUIRED header.",
+        };
+    }
+    if (lower.includes("no matching payment requirement")) {
+        return {
+            code: "NO_MATCHING_PAYMENT_REQUIREMENT",
+            message,
+            hint: "Relax --network, --token, or --scheme, or use values offered by the provider.",
+        };
+    }
+    if (lower.includes("exceeds --max")) {
+        return {
+            code: "PAYMENT_AMOUNT_TOO_HIGH",
+            message,
+            hint: "Increase the max amount flag only if this provider price is expected.",
+        };
+    }
+    if (lower.includes("failed to fetch") || lower.includes("fetch failed") || lower.includes("econnrefused")) {
+        return {
+            code: "NETWORK_ERROR",
+            message,
+            hint: "Check the URL, local server, proxy, and network connectivity.",
+        };
+    }
+    return {
+        code: "IO_ERROR",
+        message,
+        hint: "Run with --json for structured output, and check the provider/gateway logs for details.",
+    };
+}
+function helpText(topic = "root") {
+    const sections = {
+        root: `x402-cli ${getVersion()}
+
+Usage:
+  x402-cli <command> [options]
+
+Commands:
+  pay <url>                 Pay an x402-protected URL
+  serve                     Run a local x402 paywall endpoint
+  roundtrip                 Start serve, pay it, then exit
+  gateway <command>         Manage local gateway provider files
+  catalog <command>         Search, cache, and export provider catalog assets
+
+Global options:
+  -h, --help                Show help
+  -V, --version             Show version
+  --json                    Print machine-readable JSON envelope
+  --human                   Print human-readable output (default)
+`,
+        pay: `Usage:
+  x402-cli pay <url> [options]
+
+Options:
+  --method <method>         HTTP method (default: GET)
+  --header "Name: Value"    Request header, repeatable
+  --body <body>             Request body for non-GET methods
+  --network <caip2>         Require a specific network
+  --token <symbol>          Require a specific token
+  --scheme <scheme>         Require a specific x402 scheme
+  --max-amount <amount>     Maximum human-readable payment amount
+  --max-rawAmount <amount>  Maximum smallest-unit payment amount
+  --dry-run                 Read requirements but do not sign or pay
+  --private-key <hex>       Explicit payer private key
+  --rpc-url <url>           Explicit network RPC URL
+  --json                    Print JSON envelope
+`,
+        serve: `Usage:
+  x402-cli serve --pay-to <address> [options]
+
+Options:
+  --pay-to <address>        Recipient wallet address
+  --amount <amount>         Human-readable token amount
+  --rawAmount <amount>      Smallest-unit amount
+  --network <caip2>         Payment network (default: tron:nile)
+  --token <symbol>          Token symbol (default: USDT)
+  --asset <address>         Explicit token address
+  --decimals <count>        Token decimals for unregistered --asset
+  --host <host>             Bind host (default: 127.0.0.1)
+  --port <port>             Bind port (default: 4020)
+  --resource-url <url>      URL advertised in payment requirements
+  --facilitator-url <url>   Facilitator base URL
+  --daemon                  Run in background and print the child pid
+  --json                    Print JSON envelope
+`,
+        roundtrip: `Usage:
+  x402-cli roundtrip --pay-to <address> [serve/pay options]
+`,
+        gateway: `Usage:
+  x402-cli gateway <search|start|check|scaffold|catalog> [options]
+
+Commands:
+  search <query>            Search a gateway/catalog artifact
+  start                     Start a local x402 gateway process
+  check <providers>         Validate provider.yml files
+  scaffold <name>           Write a starter provider.yml
+  catalog <command>         Build/check/search gateway catalog assets
+`,
+        catalog: `Usage:
+  x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build> [options]
+
+Commands:
+  update                    Cache hosted/local catalog assets under ~/.cache
+  search <query>            Search providers
+  show <provider>           Show provider detail JSON
+  endpoints <provider>      List provider endpoints
+  pay-json <provider>       Print provider pay JSON
+  export-gateway <url>      Export catalog.json and pay.md from a gateway
+  build <providers>         Build catalog from provider.yml files
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  --provider <fqn>          Provider FQN for export-gateway
+  --output-dir <dir>        Output directory for generated files
+  -n, --limit <count>       Search result limit
+  --include-blocked         Include blocked providers in search
+  --json                    Print JSON envelope where supported
+`,
+    };
+    return sections[topic] ?? sections.root;
+}
 function readYaml(file) {
     return YAML.parse(fs.readFileSync(file, "utf8"));
 }
@@ -145,6 +435,67 @@ function providerCatalog(provider) {
         })),
     };
 }
+const FIELD_WEIGHTS = {
+    fqn: 12,
+    title: 10,
+    tags: 8,
+    chain_kinds: 8,
+    chains: 8,
+    category: 6,
+    category_meta: 6,
+    endpoints: 6,
+    i18n: 5,
+    description: 4,
+    use_case: 4,
+    service_url: 2,
+};
+function stringList(value) {
+    return Array.isArray(value) ? value.filter(item => item != null).map(String) : [];
+}
+function dictValues(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const out = [];
+    for (const child of Object.values(value)) {
+        if (child && typeof child === "object" && !Array.isArray(child))
+            out.push(...dictValues(child));
+        else if (Array.isArray(child))
+            out.push(...child.filter(item => item != null).map(String));
+        else if (child != null)
+            out.push(String(child));
+    }
+    return out;
+}
+function chainMetaValues(chainsMeta) {
+    return chainsMeta.flatMap(dictValues);
+}
+function endpointFields(endpoints) {
+    const values = [];
+    for (const endpoint of endpoints) {
+        values.push(String(endpoint.method ?? ""), String(endpoint.path ?? ""), String(endpoint.probe_status ?? ""));
+        const paid = endpoint.paid;
+        if (paid && typeof paid === "object") {
+            values.push(String(paid.network ?? ""), String(paid.currency ?? ""), String(paid.amount_raw ?? ""));
+        }
+        values.push(String(endpoint.title ?? ""), String(endpoint.description ?? ""), String(endpoint.use_case ?? endpoint.useCase ?? ""));
+    }
+    return values;
+}
+function scoreFields(terms, fields) {
+    let score = 0;
+    const matchedFields = [];
+    for (const [field, values] of Object.entries(fields)) {
+        const haystack = values.filter(Boolean).join(" ").toLowerCase();
+        if (!haystack)
+            continue;
+        const count = terms.reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
+        if (count) {
+            score += (FIELD_WEIGHTS[field] ?? 1) * count;
+            matchedFields.push(field);
+        }
+    }
+    return { score, matchedFields };
+}
 async function readCatalog(source) {
     const text = await readText(source);
     const parsed = JSON.parse(text);
@@ -156,6 +507,13 @@ async function readCatalog(source) {
         return parsed.items;
     return [];
 }
+async function readCatalogObject(source) {
+    const parsed = JSON.parse(await readText(source));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`expected JSON object from ${source}`);
+    }
+    return parsed;
+}
 async function readText(source) {
     if (!source.startsWith("http://") && !source.startsWith("https://")) {
         return fs.readFileSync(source, "utf8");
@@ -168,6 +526,55 @@ async function readText(source) {
 async function readJson(source) {
     return JSON.parse(await readText(source));
 }
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+async function responsePayload(response) {
+    const text = await response.text();
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.toLowerCase().includes("json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function cacheDir() {
+    return path.join(os.homedir(), ".cache", "x402-cli", "catalog");
+}
+function cachedCatalogPath() {
+    return path.join(cacheDir(), "catalog.json");
+}
+function providerFilename(fqn) {
+    return `${fqn.replace(/\//g, "__")}.json`;
+}
+function defaultCatalogSource() {
+    return fs.existsSync(cachedCatalogPath())
+        ? cachedCatalogPath()
+        : "https://x402-catelog.bankofai.io/api/catalog.json";
+}
+function remoteBaseFromCatalogPayload(payload) {
+    const base = payload.base_url ?? payload.baseUrl;
+    return typeof base === "string" && /^https?:\/\//.test(base) ? `${base.replace(/\/+$/, "")}/` : undefined;
+}
+async function remoteBaseFromSource(source, payload) {
+    const fromPayload = payload ? remoteBaseFromCatalogPayload(payload) : undefined;
+    if (fromPayload)
+        return fromPayload;
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        return `${source.slice(0, source.lastIndexOf("/") + 1)}`;
+    }
+    try {
+        return remoteBaseFromCatalogPayload(await readCatalogObject(source));
+    }
+    catch {
+        return undefined;
+    }
+}
 function catalogDetailSource(source, section, name) {
     if (source.startsWith("http://") || source.startsWith("https://")) {
         const base = new URL(source);
@@ -183,7 +590,10 @@ function catalogDetailSource(source, section, name) {
     }
     const stat = fs.existsSync(source) ? fs.statSync(source) : undefined;
     const root = stat?.isDirectory() ? source : path.dirname(source);
-    return path.join(root, section, `${name}.json`);
+    const direct = path.join(root, section, `${name}.json`);
+    if (fs.existsSync(direct))
+        return direct;
+    return path.join(root, section, providerFilename(name));
 }
 async function readCatalogProvider(source, name) {
     const providers = await readCatalog(source);
@@ -213,19 +623,168 @@ async function readCatalogPayProvider(source, name) {
         throw new Error(`provider not found: ${name}`);
     }
 }
+async function cacheProviderAssets(source, catalogPayload) {
+    const base = await remoteBaseFromSource(source, catalogPayload);
+    if (!base)
+        return { detailCount: 0, payCount: 0 };
+    let detailCount = 0;
+    let payCount = 0;
+    for (const provider of catalogPayload.providers ?? []) {
+        const fqn = provider?.fqn ?? provider?.name;
+        if (typeof fqn !== "string" || !fqn)
+            continue;
+        const filename = providerFilename(fqn);
+        try {
+            const detail = await readJson(new URL(`providers/${filename}`, base).toString());
+            writeJson(path.join(cacheDir(), "providers", filename), detail);
+            detailCount += 1;
+        }
+        catch {
+            // A partial cache is still useful.
+        }
+        try {
+            const pay = await readJson(new URL(`pay/${filename}`, base).toString());
+            writeJson(path.join(cacheDir(), "pay", filename), pay);
+            payCount += 1;
+        }
+        catch {
+            // A partial cache is still useful.
+        }
+    }
+    return { detailCount, payCount };
+}
+async function catalogUpdate(source, options) {
+    const payload = await readCatalogObject(source);
+    writeJson(cachedCatalogPath(), payload);
+    const cached = await cacheProviderAssets(source, payload);
+    const result = {
+        source,
+        path: cachedCatalogPath(),
+        providerCount: payload.provider_count ?? payload.providerCount ?? (payload.providers ?? []).length,
+        detailCount: cached.detailCount,
+        payCount: cached.payCount,
+    };
+    emit({ command: "catalog update", mode: outputMode(options), result });
+}
+function zhCopy(title, subtitle, description, useCase) {
+    return { title, subtitle, description, useCase };
+}
+function submissionCatalog(detail) {
+    const title = String(detail.title ?? detail.fqn);
+    const subtitle = String(detail.subtitle ?? detail.use_case ?? title);
+    const description = String(detail.description ?? subtitle);
+    const useCase = String(detail.use_case ?? detail.useCase ?? description);
+    return {
+        version: 1,
+        fqn: detail.fqn,
+        title,
+        subtitle,
+        description,
+        useCase,
+        i18n: detail.i18n ?? { "zh-CN": zhCopy(title, subtitle, description, useCase) },
+        logo: detail.logo ?? "https://x402-catelog.bankofai.io/assets/providers/default.png",
+        category: detail.category ?? "other",
+        chains: detail.chains ?? [],
+        isFirstParty: Boolean(detail.is_first_party ?? detail.isFirstParty),
+        isFeatured: Boolean(detail.is_featured ?? detail.isFeatured),
+        featuredTags: detail.featured_tags ?? detail.featuredTags ?? [],
+        serviceUrl: detail.service_url ?? detail.serviceUrl,
+        endpoints: (detail.endpoints ?? []).map((endpoint) => {
+            const endpointTitle = endpoint.title ?? endpoint.path;
+            const endpointSubtitle = endpoint.subtitle ?? endpoint.path;
+            const endpointDescription = endpoint.description ?? description;
+            const endpointUseCase = endpoint.use_case ?? endpoint.useCase ?? useCase;
+            return {
+                method: endpoint.method,
+                path: endpoint.path,
+                url: endpoint.url,
+                title: endpointTitle,
+                subtitle: endpointSubtitle,
+                description: endpointDescription,
+                useCase: endpointUseCase,
+                i18n: endpoint.i18n ?? { "zh-CN": zhCopy(endpointTitle, endpointSubtitle, endpointDescription, endpointUseCase) },
+                metered: Boolean(endpoint.metered),
+                minPriceUsd: endpoint.min_price_usd ?? endpoint.minPriceUsd ?? 0,
+                maxPriceUsd: endpoint.max_price_usd ?? endpoint.maxPriceUsd ?? 0,
+            };
+        }),
+        status: detail.status ?? {
+            catalog: "draft",
+            gateway: "unknown",
+            payment: "unknown",
+            upstream: "unknown",
+        },
+    };
+}
+function payMarkdownFromDetail(detail) {
+    const lines = [
+        `# ${detail.title ?? detail.fqn}`,
+        "",
+        "## Service",
+        "",
+        `- FQN: \`${detail.fqn}\``,
+        `- Service URL: \`${detail.service_url ?? detail.serviceUrl ?? ""}\``,
+        `- Category: \`${detail.category ?? ""}\``,
+        `- Chains: \`${(detail.chains ?? []).join(", ")}\``,
+        "",
+        "## Endpoints",
+        "",
+    ];
+    for (const endpoint of detail.endpoints ?? []) {
+        const metered = Boolean(endpoint.metered);
+        const price = endpoint.min_price_usd ?? endpoint.minPriceUsd ?? 0;
+        lines.push(`### ${endpoint.method} ${endpoint.path}`, "", endpoint.description ?? "", "", `- URL: \`${endpoint.url ?? ""}\``, `- Metered: \`${String(metered)}\``, `- Price: \`$${price}\``, "");
+        if (metered) {
+            lines.push("```bash", `x402-cli pay '${endpoint.url ?? ""}'`, "```", "");
+        }
+        else {
+            lines.push("No payment required.", "");
+        }
+    }
+    lines.push("## Notes", "", "This file is public. Do not include upstream API keys, bearer tokens, provider.yml, `.env`, passwords, or private infrastructure URLs.", "");
+    return lines.join("\n");
+}
+async function catalogExportGateway(gatewayUrl, options) {
+    const providerFqn = opt(options, "provider");
+    if (!providerFqn)
+        throw new Error("--provider is required");
+    const base = gatewayUrl.replace(/\/+$/, "");
+    const detail = await readJson(`${base}/__402/catalog/providers/${providerFqn}.json`);
+    const target = opt(options, "output-dir", path.join("providers", providerFqn));
+    fs.mkdirSync(target, { recursive: true });
+    const catalogPath = path.join(target, "catalog.json");
+    const payMdPath = path.join(target, "pay.md");
+    writeJson(catalogPath, submissionCatalog(detail));
+    fs.writeFileSync(payMdPath, payMarkdownFromDetail(detail));
+    emit({ command: "catalog export-gateway", mode: outputMode(options), result: { provider: providerFqn, catalog: catalogPath, payMd: payMdPath } });
+}
 function buildRequirement(options) {
     const network = normalizeNetwork(opt(options, "network", "tron:nile"));
     const tokenSymbol = opt(options, "token", "USDT");
-    const token = getToken(network, tokenSymbol);
-    const amount = opt(options, "rawAmount") ?? toSmallestUnit(opt(options, "amount", "0.0001"), token.decimals);
+    const explicitAsset = opt(options, "asset");
+    const registryToken = explicitAsset
+        ? findTokenByAddress(network, explicitAsset)
+        : getToken(network, tokenSymbol);
+    const decimalsOption = opt(options, "decimals");
+    if (explicitAsset && !registryToken && decimalsOption === undefined) {
+        throw new Error("When --asset is set without a registry match, --decimals must be provided");
+    }
+    if (!explicitAsset && !registryToken)
+        throw new Error(`unknown token ${tokenSymbol} on ${network}`);
+    const decimals = decimalsOption !== undefined ? Number(decimalsOption) : registryToken.decimals;
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new Error("--decimals must be a non-negative integer");
+    const amount = opt(options, "rawAmount") ?? toSmallestUnit(opt(options, "amount", "0.0001"), decimals);
+    const assetAddress = explicitAsset ?? registryToken.address;
+    const assetTransferMethod = registryToken?.assetTransferMethod ?? "permit2";
     return {
         scheme: "exact",
         network,
         amount,
-        asset: opt(options, "asset") ?? token.address,
+        asset: assetAddress,
         payTo: opt(options, "pay-to") ?? opt(options, "payTo") ?? "",
         maxTimeoutSeconds: Number(opt(options, "valid-for-seconds", "300")),
-        extra: token.assetTransferMethod ? { assetTransferMethod: token.assetTransferMethod } : {},
+        extra: assetTransferMethod ? { assetTransferMethod } : {},
     };
 }
 async function facilitatorPost(baseUrl, path, body) {
@@ -250,6 +809,34 @@ function requestHeaders(options) {
     }
     return headersOut;
 }
+function stripFlag(argv, flag) {
+    return argv.filter(item => item !== flag);
+}
+function serveDaemon(argv, options) {
+    const daemonArgs = stripFlag(stripFlag(argv, "--daemon"), "-d");
+    const script = fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [script, ...daemonArgs], {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+    });
+    child.unref();
+    const host = opt(options, "host", "127.0.0.1");
+    const port = Number(opt(options, "port", "4020"));
+    const resourceUrl = opt(options, "resource-url", `http://${host}:${port}/pay`);
+    emit({
+        command: "server",
+        mode: outputMode(options),
+        network: normalizeNetwork(opt(options, "network", "tron:nile")),
+        scheme: "exact",
+        result: {
+            pid: child.pid,
+            pay_url: resourceUrl,
+            resource_url: resourceUrl,
+            daemon: true,
+        },
+    });
+}
 function validateAmountLimits(selected, options) {
     const maxRaw = opt(options, "max-rawAmount") ?? opt(options, "max-raw-amount");
     const maxAmount = opt(options, "max-amount");
@@ -257,8 +844,15 @@ function validateAmountLimits(selected, options) {
         throw new Error(`payment raw amount ${selected.amount} exceeds --max-rawAmount ${maxRaw}`);
     }
     if (maxAmount) {
-        const token = getToken(selected.network, opt(options, "token", "USDT"));
-        if (BigInt(selected.amount) > BigInt(toSmallestUnit(maxAmount, token.decimals))) {
+        const token = findTokenByAddress(selected.network, selected.asset);
+        const decimalsOption = opt(options, "decimals");
+        if (!token && decimalsOption === undefined) {
+            throw new Error("cannot evaluate --max-amount for an unknown asset; pass --max-rawAmount or --decimals");
+        }
+        const decimals = decimalsOption !== undefined ? Number(decimalsOption) : token.decimals;
+        if (!Number.isInteger(decimals) || decimals < 0)
+            throw new Error("--decimals must be a non-negative integer");
+        if (BigInt(selected.amount) > BigInt(toSmallestUnit(maxAmount, decimals))) {
             throw new Error(`payment amount exceeds --max-amount ${maxAmount}`);
         }
     }
@@ -266,7 +860,7 @@ function validateAmountLimits(selected, options) {
 async function serve(options) {
     const host = opt(options, "host", "127.0.0.1");
     const port = Number(opt(options, "port", "4020"));
-    const facilitatorUrl = opt(options, "facilitator-url", process.env.FACILITATOR_URL ?? "https://facilitator.bankofai.io");
+    const facilitatorUrl = opt(options, "facilitator-url", "https://facilitator.bankofai.io");
     const requirement = buildRequirement(options);
     if (!requirement.payTo)
         throw new Error("--pay-to is required");
@@ -330,7 +924,13 @@ async function serve(options) {
         }
     });
     server.listen(port, host, () => {
-        printJson({ ok: true, command: "server", network: requirement.network, scheme: "exact", result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo } });
+        emit({
+            command: "server",
+            network: requirement.network,
+            scheme: "exact",
+            mode: outputMode(options),
+            result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo },
+        });
     });
 }
 function selectRequirement(accepts, options) {
@@ -354,6 +954,8 @@ function selectRequirement(accepts, options) {
     return selected;
 }
 async function pay(url, options) {
+    if (!url)
+        throw new Error("URL is required");
     const method = opt(options, "method", "GET");
     const baseHeaders = requestHeaders(options);
     const probe = await fetch(url, {
@@ -362,7 +964,16 @@ async function pay(url, options) {
         body: ["GET", "HEAD"].includes(method.toUpperCase()) ? undefined : opt(options, "body"),
     });
     if (probe.status !== 402) {
-        printJson({ ok: true, command: "client", result: { status: probe.status, body: await probe.text() } });
+        emit({
+            command: "client",
+            mode: outputMode(options),
+            result: {
+                url,
+                status: probe.status,
+                message: "Not a payment-required endpoint",
+                response: await responsePayload(probe),
+            },
+        });
         return;
     }
     const header = probe.headers.get(headers.required);
@@ -372,11 +983,11 @@ async function pay(url, options) {
     const selected = selectRequirement(required.accepts ?? [], options);
     validateAmountLimits(selected, options);
     if (options["dry-run"]) {
-        printJson({
-            ok: true,
+        emit({
             command: "client",
             network: selected.network,
             scheme: "exact",
+            mode: outputMode(options),
             result: {
                 url,
                 resource: required.resource?.url ?? url,
@@ -400,18 +1011,24 @@ async function pay(url, options) {
         headers: retryHeaders,
         body: opt(options, "body"),
     });
-    const text = await paid.text();
+    const body = await responsePayload(paid);
     const paymentResponse = paid.headers.get(headers.response);
-    printJson({
-        ok: paid.ok,
+    const result = {
+        url,
+        status: paid.status,
+        paid: paid.ok,
+        response: body,
+        ...(paymentResponse ? { paymentResponse: decodeResponse(paymentResponse) } : {}),
+    };
+    if (!paid.ok) {
+        throw new Error(`HTTP ${paid.status} from ${url}: ${typeof body === "string" ? body.slice(0, 500) : JSON.stringify(body).slice(0, 500)}`);
+    }
+    emit({
         command: "client",
         network: selected.network,
         scheme: "exact",
-        result: {
-            status: paid.status,
-            body: text,
-            ...(paymentResponse ? { paymentResponse: decodeResponse(paymentResponse) } : {}),
-        },
+        mode: outputMode(options),
+        result,
     });
 }
 async function roundtrip(options) {
@@ -421,12 +1038,46 @@ async function roundtrip(options) {
     await pay(`http://127.0.0.1:${port}/pay`, options);
     process.exit(0);
 }
-function gatewayBinary() {
-    return process.env.X402_GATEWAY_BIN ||
-        path.resolve(process.cwd(), "../x402-gateway/dist/cli.js");
+function executableInPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Try the next PATH entry.
+        }
+    }
+    return undefined;
+}
+function gatewayCommand(options) {
+    const explicit = opt(options, "gateway-bin");
+    const candidates = [
+        explicit ? { file: explicit, source: "--gateway-bin" } : undefined,
+        { file: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "gateway", "cli.js"), source: "bundled gateway runtime" },
+        executableInPath("x402-gateway") ? { file: executableInPath("x402-gateway"), source: "PATH x402-gateway" } : undefined,
+        { file: path.resolve(process.cwd(), "../x402-gateway/dist/cli.js"), source: "sibling ../x402-gateway" },
+    ].filter(Boolean);
+    for (const candidate of candidates) {
+        try {
+            fs.accessSync(candidate.file, fs.constants.R_OK);
+            if (candidate.file.endsWith(".js")) {
+                return { command: process.execPath, argsPrefix: [candidate.file], source: candidate.source };
+            }
+            return { command: candidate.file, argsPrefix: [], source: candidate.source };
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    throw new Error("x402-gateway runtime not found. Install/publish a x402-gateway npm binary, run from a checkout with ../x402-gateway/dist/cli.js, or pass --gateway-bin <path>.");
 }
-async function gatewayStart(args) {
-    const child = spawn(process.execPath, [gatewayBinary(), ...args], {
+async function gatewayStart(args, options) {
+    const gateway = gatewayCommand(options);
+    const child = spawn(gateway.command, [...gateway.argsPrefix, ...args], {
         stdio: "inherit",
         env: process.env,
     });
@@ -435,7 +1086,7 @@ async function gatewayStart(args) {
         child.on("error", reject);
     });
 }
-function gatewayCheck(target) {
+function gatewayCheck(target, options) {
     const files = providerFiles(target);
     const providers = files.map(loadProviderFile);
     const names = new Set();
@@ -444,7 +1095,11 @@ function gatewayCheck(target) {
             throw new Error(`duplicate provider name: ${provider.name}`);
         names.add(provider.name);
     }
-    printJson({ ok: true, providers: providers.map(p => p.name), count: providers.length });
+    emit({
+        command: "gateway check",
+        mode: outputMode(options),
+        result: { providers: providers.map(p => p.name), count: providers.length },
+    });
 }
 function gatewayScaffold(name, options) {
     const outputDir = opt(options, "output-dir", path.join("providers", name));
@@ -465,12 +1120,12 @@ operator:
   network: tron-nile
   currencies:
     usd: ["USDT"]
-  recipient: \${X402_PROVIDER_RECIPIENT_TRON}
+  recipient: <provider-recipient-address>
   scheme: exact
   protocol: exact
   asset_transfer_method: permit2
-  facilitator_url: \${X402_FACILITATOR_URL}
-  facilitator_api_key: \${X402_FACILITATOR_API_KEY}
+  facilitator_url: https://facilitator.bankofai.io
+  facilitator_api_key: <facilitator-api-key>
   valid_for_seconds: 300
 
 endpoints:
@@ -480,9 +1135,13 @@ endpoints:
       dimensions:
         - tiers:
             - price_usd: 0.0001
-`;
+  `;
     fs.writeFileSync(path.join(outputDir, "provider.yml"), body);
-    printJson({ ok: true, file: path.join(outputDir, "provider.yml") });
+    emit({
+        command: "gateway scaffold",
+        mode: outputMode(options),
+        result: { file: path.join(outputDir, "provider.yml") },
+    });
 }
 function catalogBuild(target, options) {
     const providers = providerFiles(target).map(loadProviderFile).map(providerCatalog);
@@ -491,13 +1150,17 @@ function catalogBuild(target, options) {
     if (output) {
         fs.mkdirSync(path.dirname(output), { recursive: true });
         fs.writeFileSync(output, JSON.stringify(catalog, null, 2));
-        printJson({ ok: true, output, count: providers.length });
+        emit({
+            command: "catalog build",
+            mode: outputMode(options),
+            result: { output, count: providers.length },
+        });
     }
     else {
         printJson(catalog);
     }
 }
-function catalogPayAssets(target) {
+function catalogPayAssets(target, options) {
     const rows = providerFiles(target).map(loadProviderFile).flatMap(provider => (provider.endpoints ?? []).map((endpoint) => ({
         provider: provider.name,
         method: endpoint.method,
@@ -508,41 +1171,172 @@ function catalogPayAssets(target) {
         scheme: "exact",
         assetTransferMethod: providerAssetTransferMethod(provider),
     })));
-    printJson({ assets: rows, count: rows.length });
+    if (outputMode(options) === "json") {
+        printJson({ assets: rows, count: rows.length });
+    }
+    else {
+        emit({
+            command: "gateway catalog pay-assets",
+            mode: "human",
+            result: { count: rows.length, assets: rows },
+        });
+    }
 }
-async function catalogSearch(source, query, options) {
+async function readProviderDetailForSearch(source, fqn) {
+    try {
+        return await readJson(catalogDetailSource(source, "providers", fqn));
+    }
+    catch {
+        return {};
+    }
+}
+async function searchCatalog(source, query, options) {
     const providers = await readCatalog(source);
-    const q = query.toLowerCase();
-    const hits = providers
-        .map((provider) => {
-        const haystack = [
-            provider.fqn,
-            provider.name,
-            provider.title,
-            provider.main_title,
-            provider.mainTitle,
-            provider.description,
-            provider.category,
-            ...(provider.chains ?? []),
-            ...(provider.featured_tags ?? []),
-            ...(provider.featuredTags ?? []),
-            ...(provider.tags ?? []),
-            ...(provider.endpoints ?? []).map((e) => `${e.method} ${e.path} ${e.description ?? ""}`),
-        ].join(" ").toLowerCase();
-        const score = q.split(/\s+/).filter(Boolean).reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
-        return { provider, score };
-    })
-        .filter(item => item.score > 0)
-        .sort((a, b) => b.score - a.score)
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (!terms.length)
+        return [];
+    const includeBlocked = hasFlag(options, "include-blocked");
+    const hits = [];
+    for (const provider of providers) {
+        if (provider.block && !includeBlocked)
+            continue;
+        const fqn = String(provider.fqn ?? provider.name ?? "");
+        if (!fqn)
+            continue;
+        const detail = await readProviderDetailForSearch(source, fqn);
+        const tags = stringList(detail.featured_tags ?? provider.featured_tags ?? detail.tags ?? provider.tags);
+        const endpoints = Array.isArray(detail.endpoints) ? detail.endpoints : Array.isArray(provider.endpoints) ? provider.endpoints : [];
+        const categoryMeta = detail.category_meta ?? provider.category_meta;
+        const chains = stringList(detail.chains ?? provider.chains);
+        const chainKinds = stringList(detail.chain_kinds ?? provider.chain_kinds);
+        const chainsMetaRaw = detail.chains_meta ?? provider.chains_meta ?? [];
+        const chainsMeta = Array.isArray(chainsMetaRaw) ? chainsMetaRaw.filter(item => item && typeof item === "object") : [];
+        const titleZh = String(detail.title_zh ?? provider.title_zh ?? "");
+        const mainTitle = String(detail.main_title ?? provider.main_title ?? detail.mainTitle ?? provider.mainTitle ?? "");
+        const subTitle = String(detail.sub_title ?? provider.sub_title ?? detail.subTitle ?? provider.subTitle ?? "");
+        const fields = {
+            fqn: [fqn],
+            title: [String(detail.title ?? provider.title ?? ""), mainTitle],
+            i18n: [titleZh, subTitle, ...dictValues(detail.i18n ?? provider.i18n)],
+            category: [String(detail.category ?? provider.category ?? "")],
+            category_meta: dictValues(categoryMeta),
+            chains: [...chains, ...chainMetaValues(chainsMeta)],
+            chain_kinds: chainKinds,
+            service_url: [String(detail.service_url ?? provider.service_url ?? detail.serviceUrl ?? provider.serviceUrl ?? "")],
+            description: [String(detail.description ?? provider.description ?? "")],
+            use_case: [String(detail.use_case ?? provider.use_case ?? detail.useCase ?? provider.useCase ?? "")],
+            tags,
+            endpoints: endpointFields(endpoints),
+        };
+        const scored = scoreFields(terms, fields);
+        if (scored.score === 0)
+            continue;
+        hits.push({
+            provider,
+            detail,
+            fqn,
+            title: fields.title[0],
+            category: fields.category[0],
+            serviceUrl: fields.service_url[0],
+            description: fields.description[0] || undefined,
+            useCase: fields.use_case[0] || undefined,
+            titleZh: titleZh || undefined,
+            mainTitle: mainTitle || undefined,
+            subTitle: subTitle || undefined,
+            categoryMeta: categoryMeta && typeof categoryMeta === "object" ? categoryMeta : undefined,
+            chains,
+            chainKinds,
+            chainsMeta,
+            tags,
+            endpoints,
+            score: scored.score,
+            matchedFields: scored.matchedFields,
+        });
+    }
+    return hits
+        .sort((a, b) => b.score - a.score || a.fqn.localeCompare(b.fqn))
         .slice(0, Number(opt(options, "limit", "10")));
-    printJson({ query, count: hits.length, results: hits.map(item => item.provider) });
 }
-async function catalogShow(source, name) {
-    printJson(await readCatalogProvider(source, name));
+function searchHitToJson(hit) {
+    return {
+        fqn: hit.fqn,
+        title: hit.title,
+        category: hit.category,
+        serviceUrl: hit.serviceUrl,
+        description: hit.description,
+        useCase: hit.useCase,
+        title_zh: hit.titleZh,
+        main_title: hit.mainTitle,
+        sub_title: hit.subTitle,
+        category_meta: hit.categoryMeta,
+        chains: hit.chains,
+        chain_kinds: hit.chainKinds,
+        chains_meta: hit.chainsMeta,
+        tags: hit.tags,
+        score: hit.score,
+        matchedFields: hit.matchedFields,
+        endpoints: hit.endpoints,
+    };
+}
+async function catalogSearch(source, query, options) {
+    const hits = await searchCatalog(source, query, options);
+    const results = hits.map(searchHitToJson);
+    if (outputMode(options) === "json") {
+        printJson({ ok: true, command: "catalog search", query, catalog: source, count: hits.length, results });
+        return;
+    }
+    if (!hits.length) {
+        process.stdout.write("no matches\n");
+        return;
+    }
+    for (const hit of hits) {
+        const tags = hit.tags.length ? hit.tags.join(",") : "-";
+        process.stdout.write(`${hit.fqn.padEnd(32)}  score=${String(hit.score).padEnd(3)}  category=${hit.category.padEnd(12)}  tags=${tags}\n`);
+        if (hit.title)
+            process.stdout.write(`  ${hit.title}\n`);
+        if (hit.description)
+            process.stdout.write(`  ${hit.description.split("\n")[0]}\n`);
+        if (hit.serviceUrl)
+            process.stdout.write(`  service: ${hit.serviceUrl}\n`);
+        for (const endpoint of hit.endpoints.slice(0, 3)) {
+            const method = String(endpoint.method ?? "");
+            const pathText = String(endpoint.path ?? endpoint.url ?? "");
+            const paid = endpoint.paid;
+            let suffix = "";
+            if (paid && typeof paid === "object") {
+                suffix = `  ${paid.network ?? ""} ${paid.currency ?? ""} ${paid.amount_raw ?? ""}`.trimEnd();
+            }
+            process.stdout.write(`  ${method.padEnd(6)} ${pathText}${suffix ? `  ${suffix}` : ""}\n`);
+        }
+        process.stdout.write("\n");
+    }
+}
+async function catalogShow(source, name, options) {
+    const provider = await readCatalogProvider(source, name);
+    if (outputMode(options) === "json") {
+        printJson({ ok: true, command: "catalog show", result: provider });
+        return;
+    }
+    process.stdout.write(`${provider.fqn ?? provider.name} - ${provider.title ?? provider.main_title ?? provider.name}\n`);
+    if (provider.description)
+        process.stdout.write(`${String(provider.description).split("\n")[0]}\n`);
+    if (provider.category)
+        process.stdout.write(`category: ${provider.category}\n`);
+    if (provider.chains)
+        process.stdout.write(`chains: ${provider.chains.join(", ")}\n`);
 }
-async function catalogEndpoints(source, name) {
+async function catalogEndpoints(source, name, options) {
     const provider = await readCatalogProvider(source, name);
-    printJson({ provider: provider.fqn ?? provider.name, endpoints: provider.endpoints ?? [] });
+    const endpoints = provider.endpoints ?? [];
+    if (outputMode(options) === "json") {
+        printJson({ ok: true, command: "catalog endpoints", provider: provider.fqn ?? provider.name, endpoints });
+        return;
+    }
+    for (const endpoint of endpoints) {
+        process.stdout.write(`${String(endpoint.method ?? "").padEnd(6)} ${endpoint.path ?? endpoint.url ?? ""}\n`);
+        if (endpoint.description)
+            process.stdout.write(`  ${String(endpoint.description).split("\n")[0]}\n`);
+    }
 }
 async function catalogPayJson(source, name) {
     const provider = await readCatalogPayProvider(source, name);
@@ -560,16 +1354,22 @@ async function catalogPayJson(source, name) {
 }
 async function handleGateway(args) {
     const { command, positional, options } = parseArgs(args);
-    if (command === "start")
-        await gatewayStart(["--providers", opt(options, "providers", opt(options, "providers-dir", positional[0] ?? "providers")), "--host", opt(options, "host", "127.0.0.1"), "--port", opt(options, "port", "4020")]);
+    if (hasFlag(options, "help") || command === "help") {
+        process.stdout.write(helpText("gateway"));
+        return;
+    }
+    if (command === "search")
+        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), positional.join(" "), options);
+    else if (command === "start")
+        await gatewayStart(["--providers", opt(options, "providers", opt(options, "providers-dir", positional[0] ?? "providers")), "--host", opt(options, "host", "127.0.0.1"), "--port", opt(options, "port", "4020")], options);
     else if (command === "check")
-        gatewayCheck(positional[0] ?? opt(options, "providers", "providers"));
+        gatewayCheck(positional[0] ?? opt(options, "providers", "providers"), options);
     else if (command === "scaffold")
         gatewayScaffold(positional[0] ?? "example-provider", options);
     else if (command === "catalog")
         await handleGatewayCatalog(positional, options);
     else
-        throw new Error("Usage: x402-cli gateway <start|check|scaffold|catalog>");
+        throw new Error("Usage: x402-cli gateway <search|start|check|scaffold|catalog>");
 }
 async function handleGatewayCatalog(positional, options) {
     const sub = positional[0] ?? "build";
@@ -577,35 +1377,56 @@ async function handleGatewayCatalog(positional, options) {
     if (sub === "build")
         catalogBuild(target, options);
     else if (sub === "check")
-        gatewayCheck(target);
+        gatewayCheck(target, options);
     else if (sub === "pay-assets")
-        catalogPayAssets(target);
+        catalogPayAssets(target, options);
     else if (sub === "search")
-        await catalogSearch(opt(options, "catalog", target), positional.slice(2).join(" ") || opt(options, "query", ""), options);
+        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), positional.slice(2).join(" ") || opt(options, "query", ""), options);
     else
         throw new Error("Usage: x402-cli gateway catalog <build|check|pay-assets|search>");
 }
 async function handleCatalog(args) {
     const { command, positional, options } = parseArgs(args);
-    const source = opt(options, "catalog", process.env.X402_CATALOG || "dist/catalog.json");
-    if (command === "search")
+    if (hasFlag(options, "help") || command === "help") {
+        process.stdout.write(helpText("catalog"));
+        return;
+    }
+    const source = opt(options, "catalog", defaultCatalogSource());
+    if (command === "update")
+        await catalogUpdate(source, options);
+    else if (command === "search")
         await catalogSearch(source, positional.join(" "), options);
     else if (command === "show")
-        await catalogShow(source, positional[0]);
+        await catalogShow(source, positional[0], options);
     else if (command === "endpoints")
-        await catalogEndpoints(source, positional[0]);
+        await catalogEndpoints(source, positional[0], options);
     else if (command === "pay-json")
         await catalogPayJson(source, positional[0]);
+    else if (command === "export-gateway")
+        await catalogExportGateway(positional[0], options);
     else if (command === "build")
         catalogBuild(positional[0] ?? "providers", options);
     else
-        throw new Error("Usage: x402-cli catalog <search|show|endpoints|pay-json|build>");
+        throw new Error("Usage: x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build>");
 }
 async function main() {
     const argv = process.argv.slice(2);
     const { command, positional, options } = parseArgs(argv);
-    if (command === "serve")
-        await serve(options);
+    if (command === "--help" || command === "-h" || command === "help" || hasFlag(options, "help")) {
+        const topic = command === "help" ? positional[0] : command.startsWith("-") ? undefined : command;
+        process.stdout.write(helpText(topic));
+        return;
+    }
+    if (command === "--version" || command === "-V" || hasFlag(options, "version")) {
+        process.stdout.write(`${getVersion()}\n`);
+        return;
+    }
+    if (command === "serve") {
+        if (hasFlag(options, "daemon"))
+            serveDaemon(argv, options);
+        else
+            await serve(options);
+    }
     else if (command === "pay")
         await pay(positional[0], options);
     else if (command === "roundtrip")
@@ -615,10 +1436,14 @@ async function main() {
     else if (command === "catalog")
         await handleCatalog(argv.slice(1));
     else {
-        process.stdout.write("Usage: x402-cli <serve|pay|roundtrip|gateway|catalog> [options]\n");
+        process.stdout.write(helpText());
     }
 }
 main().catch(error => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    emit({
+        command: process.argv[2] ?? "x402-cli",
+        mode: process.argv.includes("--json") ? "json" : "human",
+        error: classify(error),
+    });
     process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "files": [
     "dist"
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts"
   },