@lidianai/cli 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# Lidian CLI
+
+Bun CLI for Lidian core REST endpoints.
+
+## Install
+
+```bash
+npm install -g @lidian/cli
+# or
+bunx @lidian/cli --help
+```
+
+## Commands
+
+```bash
+lidian query --q "<term>" [--page 1] [--pageSize 1..3] [--api-key <key>] [--json]
+lidian act --endpoint-id <uuid> --params '<json>' [--payment-rail prepaid_credits|x402] [--network base|ethereum] [--api-key <key>] [--json]
+lidian account [--api-key <key>] [--json]
+lidian login [--key ld_...] [--json]
+lidian --help
+```
+
+`query` returns API matches (`items[]`) from `/v1/query` with metadata and confidence fields (`matchScore`, `matchPercent`).
+
+## Auth
+
+- Store key locally: `lidian login --key ld_...` (writes `~/.lidian/config.json`)
+- Or run `lidian login` and paste your key after browser auth flow.
+- Resolution order: `--api-key` -> `LIDIAN_API_KEY` -> `~/.lidian/config.json`.
+- Optional: set `LIDIAN_API_BASE` (default `https://api.lidian.ai`).
+
+## x402
+
+When `--payment-rail x402` is used, CLI performs:
+1. `POST /v1/payments/requirements`
+2. `POST /v1/payments/verify`
+3. `POST /v1/act`
+
+## Dev
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run build
+```

package/biome.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+  "files": {
+    "includes": ["src/**", "README.md", "package.json", "tsconfig.json"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true
+  }
+}

package/dist/index.js

@@ -0,0 +1,405 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/commands/account.ts
+var runAccountCommand = async (http, apiKey) => {
+  return http.get("/v1/account", apiKey);
+};
+
+// src/lib/errors.ts
+class CliError extends Error {
+  code;
+  constructor(message, code = 1) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+  }
+}
+
+// src/lib/x402.ts
+var requestPaymentRequirements = async (http, apiKey, endpointId, network) => {
+  return http.post("/v1/payments/requirements", { endpointId, ...network ? { network } : {} }, apiKey);
+};
+var verifyPaymentAddress = async (http, apiKey, payTo) => {
+  return http.post("/v1/payments/verify", { payTo }, apiKey);
+};
+
+// src/commands/act.ts
+var runActCommand = async (http, apiKey, input) => {
+  if (!isUuid(input.endpointId)) {
+    throw new CliError("endpointId must be a valid UUID.");
+  }
+  if (input.paymentRail === "x402") {
+    const requirements = await requestPaymentRequirements(http, apiKey, input.endpointId, input.network);
+    const verification = await verifyPaymentAddress(http, apiKey, requirements.payTo);
+    const execution2 = await http.post("/v1/act", input, apiKey);
+    return {
+      execution: execution2,
+      payment: {
+        requirements,
+        verified: verification.valid
+      }
+    };
+  }
+  const execution = await http.post("/v1/act", input, apiKey);
+  return { execution };
+};
+var isUuid = (value) => {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+};
+
+// src/commands/login.ts
+import { stdin, stdout } from "process";
+import { createInterface } from "readline/promises";
+
+// src/lib/config.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var CONFIG_PATH = join(homedir(), ".lidian", "config.json");
+var getConfigPath = () => CONFIG_PATH;
+var readConfig = async () => {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const apiKey = "apiKey" in parsed && typeof parsed.apiKey === "string" ? parsed.apiKey : undefined;
+    return { apiKey };
+  } catch {
+    return {};
+  }
+};
+var writeConfig = async (config) => {
+  await mkdir(dirname(CONFIG_PATH), { recursive: true });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+};
+
+// src/lib/output.ts
+var print = (message) => {
+  process.stdout.write(`${message}
+`);
+};
+var printError = (message) => {
+  process.stderr.write(`${message}
+`);
+};
+var printResult = (result, asJson) => {
+  if (asJson) {
+    print(JSON.stringify(result, null, 2));
+    return;
+  }
+  print(formatForHuman(result));
+};
+var printQueryResult = (result, asJson) => {
+  if (asJson) {
+    printResult(result, true);
+    return;
+  }
+  if (result.items.length === 0) {
+    print("No APIs found.");
+    return;
+  }
+  print(`Found ${result.items.length} of ${result.total} APIs (page ${result.page}).`);
+  for (const item of result.items) {
+    const confidence = item.matchPercent ? ` confidence=${item.matchPercent.toFixed(1)}%` : "";
+    print(`- ${item.name} (${item.id}) auth=${item.authType} cost=${item.defaultCostPerUse}c${confidence}`);
+  }
+};
+var printActResult = (result, asJson) => {
+  if (asJson) {
+    printResult(result.execution, true);
+    return;
+  }
+  if (result.payment) {
+    print(`x402 preflight: payTo=${result.payment.requirements.payTo} amount=${result.payment.requirements.amountFormatted} verified=${String(result.payment.verified)}`);
+  }
+  printExecutionResult(result.execution);
+};
+var printAccountResult = (result, asJson) => {
+  if (asJson) {
+    printResult(result, true);
+    return;
+  }
+  print(`Account: ${result.user.id}`);
+  print(`Balance: ${result.balance.balance} credits`);
+};
+var printExecutionResult = (result) => {
+  print(`Execution succeeded. Spent=${result.credits.spent} balance=${result.credits.balance}`);
+  print(JSON.stringify(result.data, null, 2));
+};
+var formatForHuman = (value) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value, null, 2);
+};
+var fail = (error) => {
+  if (error instanceof CliError) {
+    printError(`Error: ${error.message}`);
+    process.exit(error.code);
+  }
+  if (error instanceof Error) {
+    printError(`Error: ${error.message}`);
+    process.exit(1);
+  }
+  printError("Error: Unknown failure");
+  process.exit(1);
+};
+
+// src/commands/login.ts
+var runLoginCommand = async (input) => {
+  const key = input.key ?? await promptForKeyViaBrowserFlow();
+  validateApiKey(key);
+  const current = await readConfig();
+  await writeConfig({
+    ...current,
+    apiKey: key
+  });
+  return { path: getConfigPath() };
+};
+var promptForKeyViaBrowserFlow = async () => {
+  const loginUrl = "https://app.lidian.ai/login?next=/user/api-keys";
+  openUrl(loginUrl);
+  print(`Open this URL to authenticate and create/copy an API key:
+${loginUrl}`);
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const entered = (await rl.question("Paste your API key (ld_...): ")).trim();
+    if (!entered) {
+      throw new CliError("No API key entered.");
+    }
+    return entered;
+  } finally {
+    rl.close();
+  }
+};
+var validateApiKey = (key) => {
+  if (!key.startsWith("ld_")) {
+    throw new CliError("Invalid API key format. Expected key starting with ld_.");
+  }
+};
+var openUrl = (url) => {
+  try {
+    if (process.platform === "darwin") {
+      Bun.spawn(["open", url], { stdout: "ignore", stderr: "ignore" });
+      return;
+    }
+    if (process.platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", "", url], {
+        stdout: "ignore",
+        stderr: "ignore"
+      });
+      return;
+    }
+    Bun.spawn(["xdg-open", url], { stdout: "ignore", stderr: "ignore" });
+  } catch {}
+};
+
+// src/commands/query.ts
+var runQueryCommand = async (http, apiKey, input) => {
+  if (input.pageSize < 1 || input.pageSize > 3) {
+    throw new CliError("pageSize must be between 1 and 3.");
+  }
+  const params = new URLSearchParams({
+    q: input.q,
+    page: String(input.page),
+    pageSize: String(input.pageSize)
+  });
+  return http.get(`/v1/query?${params.toString()}`, apiKey);
+};
+
+// src/lib/auth.ts
+var resolveApiKey = async (argsApiKey) => {
+  const config = await readConfig();
+  const key = argsApiKey ?? process.env.LIDIAN_API_KEY ?? config.apiKey;
+  if (!key) {
+    throw new CliError("Missing API key. Use `lidian login --key ld_...`, pass --api-key, or set LIDIAN_API_KEY.");
+  }
+  return key;
+};
+
+// src/lib/http.ts
+var createHttpClient = (baseUrl) => {
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+  return {
+    async get(path, apiKey) {
+      const response = await fetch(`${normalizedBaseUrl}${path}`, {
+        method: "GET",
+        headers: authHeaders(apiKey)
+      });
+      return handleResponse(response);
+    },
+    async post(path, body, apiKey) {
+      const response = await fetch(`${normalizedBaseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          ...authHeaders(apiKey),
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      return handleResponse(response);
+    }
+  };
+};
+var authHeaders = (apiKey) => ({
+  Authorization: `Bearer ${apiKey}`
+});
+var handleResponse = async (response) => {
+  const json = await response.json().catch(() => null);
+  if (!response.ok) {
+    if (json && "success" in json && json.success === false) {
+      throw new CliError(`${json.error.code}: ${json.error.message}`, 1);
+    }
+    throw new CliError(`Request failed with status ${response.status}`, 1);
+  }
+  if (!json || !("success" in json) || json.success !== true) {
+    throw new CliError("Unexpected API response format", 1);
+  }
+  return json.data;
+};
+
+// src/index.ts
+var DEFAULT_API_BASE = "https://api.lidian.ai";
+var GLOBAL_OPTIONS = new Set(["api-key", "api-base", "json", "help"]);
+var COMMAND_OPTIONS = {
+  query: new Set(["q", "page", "pageSize"]),
+  act: new Set(["endpoint-id", "params", "payment-rail", "network"]),
+  account: new Set([]),
+  login: new Set(["key"])
+};
+var main = async () => {
+  if (process.argv.length <= 2 || process.argv.includes("--help")) {
+    printUsage();
+    return;
+  }
+  const parsed = parseArgs(process.argv.slice(2));
+  const apiBase = String(parsed.options["api-base"] ?? process.env.LIDIAN_API_BASE ?? DEFAULT_API_BASE);
+  const asJson = Boolean(parsed.options.json);
+  const http = createHttpClient(apiBase);
+  switch (parsed.command) {
+    case "login": {
+      const key = asString(parsed.options.key);
+      const result = await runLoginCommand({ key });
+      if (asJson) {
+        print(JSON.stringify({ success: true, data: result }, null, 2));
+      } else {
+        print(`Saved API key to ${result.path}`);
+      }
+      return;
+    }
+    case "query": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const qValue = asString(parsed.options.q);
+      if (!qValue) {
+        throw new CliError("Missing --q for query command.");
+      }
+      const page = toInt(asString(parsed.options.page), 1);
+      const pageSize = toInt(asString(parsed.options.pageSize), 1);
+      const result = await runQueryCommand(http, apiKey, {
+        q: qValue,
+        page,
+        pageSize
+      });
+      printQueryResult(result, asJson);
+      return;
+    }
+    case "act": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const endpointIdValue = asString(parsed.options["endpoint-id"]);
+      if (!endpointIdValue) {
+        throw new CliError("Missing --endpoint-id for act command.");
+      }
+      const paramsRaw = asString(parsed.options.params) ?? "{}";
+      const params = parseJsonObject(paramsRaw, "--params");
+      const paymentRail = asPaymentRail(asString(parsed.options["payment-rail"]) ?? "prepaid_credits");
+      const network = asString(parsed.options.network);
+      const result = await runActCommand(http, apiKey, {
+        endpointId: endpointIdValue,
+        params,
+        paymentRail,
+        ...network ? { network } : {}
+      });
+      printActResult(result, asJson);
+      return;
+    }
+    case "account": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const result = await runAccountCommand(http, apiKey);
+      printAccountResult(result, asJson);
+      return;
+    }
+    default:
+      throw new CliError("Unknown command.", 1);
+  }
+};
+var parseArgs = (argv) => {
+  const command = argv[0];
+  if (command !== "query" && command !== "act" && command !== "account" && command !== "login") {
+    printUsage();
+    throw new CliError("Invalid command. Use one of: login, query, act, account.", 1);
+  }
+  const options = {};
+  let index = 1;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (!token || !token.startsWith("--")) {
+      throw new CliError(`Unexpected argument: ${token ?? "<empty>"}`);
+    }
+    const key = token.slice(2);
+    const allowedForCommand = COMMAND_OPTIONS[command];
+    if (!GLOBAL_OPTIONS.has(key) && !allowedForCommand.has(key)) {
+      throw new CliError(`Unknown option for ${command}: --${key}`);
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      options[key] = true;
+      index += 1;
+      continue;
+    }
+    options[key] = next;
+    index += 2;
+  }
+  return {
+    command,
+    options
+  };
+};
+var printUsage = () => {
+  print("Usage:");
+  print("  lidian login [--key ld_...] [--json]");
+  print('  lidian query --q "<term>" [--page 1] [--pageSize 1..3] [--api-key <key>] [--json]');
+  print("  lidian act --endpoint-id <uuid> --params '<json>' [--payment-rail prepaid_credits|x402] [--api-key <key>] [--json]");
+  print("             [--network base|ethereum]");
+  print("  lidian account [--api-key <key>] [--json]");
+};
+var asString = (value) => {
+  if (typeof value === "string")
+    return value;
+  return;
+};
+var toInt = (value, fallback) => {
+  if (!value)
+    return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new CliError(`Invalid integer value: ${value}`);
+  }
+  return parsed;
+};
+var parseJsonObject = (value, flagName) => {
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${flagName} must be a JSON object.`);
+  }
+  return parsed;
+};
+var asPaymentRail = (value) => {
+  if (value === "prepaid_credits" || value === "x402")
+    return value;
+  throw new CliError("Invalid --payment-rail. Use prepaid_credits or x402.");
+};
+main().catch(fail);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lidianai/cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "lidian": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
+  }
+}

package/src/commands/account.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from "@/lib/http";
+
+export interface AccountApiResponse {
+  user: {
+    id: string;
+    email: string;
+    name: string | null;
+    role: string;
+    createdAt: string;
+  };
+  balance: {
+    balance: number;
+    createdAt: string;
+    updatedAt: string;
+  };
+}
+
+export const runAccountCommand = async (
+  http: HttpClient,
+  apiKey: string,
+): Promise<AccountApiResponse> => {
+  return http.get<AccountApiResponse>("/v1/account", apiKey);
+};

package/src/commands/act.ts

@@ -0,0 +1,83 @@
+import { CliError } from "@/lib/errors";
+import type { HttpClient } from "@/lib/http";
+import {
+  type PaymentRequirementsResponse,
+  requestPaymentRequirements,
+  verifyPaymentAddress,
+} from "@/lib/x402";
+
+export type PaymentRail = "prepaid_credits" | "x402";
+
+export interface ActCommandInput {
+  endpointId: string;
+  params: Record<string, unknown>;
+  paymentRail: PaymentRail;
+  network?: string;
+}
+
+export interface ActApiResponse {
+  data: unknown;
+  credits: {
+    spent: number;
+    balance: number;
+  };
+}
+
+export interface ActCommandResult {
+  execution: ActApiResponse;
+  payment?: {
+    requirements: PaymentRequirementsResponse;
+    verified: boolean;
+  };
+}
+
+export const runActCommand = async (
+  http: HttpClient,
+  apiKey: string,
+  input: ActCommandInput,
+): Promise<ActCommandResult> => {
+  if (!isUuid(input.endpointId)) {
+    throw new CliError("endpointId must be a valid UUID.");
+  }
+
+  if (input.paymentRail === "x402") {
+    const requirements = await requestPaymentRequirements(
+      http,
+      apiKey,
+      input.endpointId,
+      input.network,
+    );
+    const verification = await verifyPaymentAddress(
+      http,
+      apiKey,
+      requirements.payTo,
+    );
+
+    const execution = await http.post<ActApiResponse, ActCommandInput>(
+      "/v1/act",
+      input,
+      apiKey,
+    );
+
+    return {
+      execution,
+      payment: {
+        requirements,
+        verified: verification.valid,
+      },
+    };
+  }
+
+  const execution = await http.post<ActApiResponse, ActCommandInput>(
+    "/v1/act",
+    input,
+    apiKey,
+  );
+  return { execution };
+};
+
+const isUuid = (value: string): boolean => {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    value,
+  );
+};

package/src/commands/login.ts

@@ -0,0 +1,70 @@
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { getConfigPath, readConfig, writeConfig } from "@/lib/config";
+import { CliError } from "@/lib/errors";
+import { print } from "@/lib/output";
+
+export interface LoginCommandInput {
+  key?: string;
+}
+
+export const runLoginCommand = async (
+  input: LoginCommandInput,
+): Promise<{ path: string }> => {
+  const key = input.key ?? (await promptForKeyViaBrowserFlow());
+  validateApiKey(key);
+
+  const current = await readConfig();
+  await writeConfig({
+    ...current,
+    apiKey: key,
+  });
+
+  return { path: getConfigPath() };
+};
+
+const promptForKeyViaBrowserFlow = async (): Promise<string> => {
+  const loginUrl = "https://app.lidian.ai/login?next=/user/api-keys";
+  openUrl(loginUrl);
+  print(
+    `Open this URL to authenticate and create/copy an API key:\n${loginUrl}`,
+  );
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const entered = (await rl.question("Paste your API key (ld_...): ")).trim();
+    if (!entered) {
+      throw new CliError("No API key entered.");
+    }
+    return entered;
+  } finally {
+    rl.close();
+  }
+};
+
+const validateApiKey = (key: string): void => {
+  if (!key.startsWith("ld_")) {
+    throw new CliError(
+      "Invalid API key format. Expected key starting with ld_.",
+    );
+  }
+};
+
+const openUrl = (url: string): void => {
+  try {
+    if (process.platform === "darwin") {
+      Bun.spawn(["open", url], { stdout: "ignore", stderr: "ignore" });
+      return;
+    }
+    if (process.platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", "", url], {
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      return;
+    }
+    Bun.spawn(["xdg-open", url], { stdout: "ignore", stderr: "ignore" });
+  } catch {
+    // URL is still printed for manual opening.
+  }
+};

package/src/commands/query.ts

@@ -0,0 +1,45 @@
+import { CliError } from "@/lib/errors";
+import type { HttpClient } from "@/lib/http";
+
+export interface QueryCommandInput {
+  q: string;
+  page: number;
+  pageSize: number;
+}
+
+export interface QueryApiResponse {
+  items: Array<{
+    id: string;
+    merchantId: string | null;
+    name: string;
+    description: string | null;
+    endpointBase: string;
+    authType: "none" | "api_key" | "bearer" | "basic" | "oauth2" | "custom";
+    defaultCostPerUse: number;
+    isActive: boolean;
+    openapiSpecUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+    matchScore?: number;
+    matchPercent?: number;
+  }>;
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export const runQueryCommand = async (
+  http: HttpClient,
+  apiKey: string,
+  input: QueryCommandInput,
+): Promise<QueryApiResponse> => {
+  if (input.pageSize < 1 || input.pageSize > 3) {
+    throw new CliError("pageSize must be between 1 and 3.");
+  }
+  const params = new URLSearchParams({
+    q: input.q,
+    page: String(input.page),
+    pageSize: String(input.pageSize),
+  });
+  return http.get<QueryApiResponse>(`/v1/query?${params.toString()}`, apiKey);
+};

package/src/index.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env bun
+
+import { runAccountCommand } from "@/commands/account";
+import { type PaymentRail, runActCommand } from "@/commands/act";
+import { runLoginCommand } from "@/commands/login";
+import { runQueryCommand } from "@/commands/query";
+import { resolveApiKey } from "@/lib/auth";
+import { CliError } from "@/lib/errors";
+import { createHttpClient } from "@/lib/http";
+import {
+  fail,
+  print,
+  printAccountResult,
+  printActResult,
+  printQueryResult,
+} from "@/lib/output";
+
+interface ParsedArgs {
+  command: "query" | "act" | "account" | "login";
+  options: Record<string, string | boolean>;
+}
+
+const DEFAULT_API_BASE = "https://api.lidian.ai";
+const GLOBAL_OPTIONS = new Set(["api-key", "api-base", "json", "help"]);
+const COMMAND_OPTIONS: Record<ParsedArgs["command"], Set<string>> = {
+  query: new Set(["q", "page", "pageSize"]),
+  act: new Set(["endpoint-id", "params", "payment-rail", "network"]),
+  account: new Set([]),
+  login: new Set(["key"]),
+};
+
+const main = async (): Promise<void> => {
+  if (process.argv.length <= 2 || process.argv.includes("--help")) {
+    printUsage();
+    return;
+  }
+  const parsed = parseArgs(process.argv.slice(2));
+  const apiBase = String(
+    parsed.options["api-base"] ??
+      process.env.LIDIAN_API_BASE ??
+      DEFAULT_API_BASE,
+  );
+  const asJson = Boolean(parsed.options.json);
+  const http = createHttpClient(apiBase);
+
+  switch (parsed.command) {
+    case "login": {
+      const key = asString(parsed.options.key);
+      const result = await runLoginCommand({ key });
+      if (asJson) {
+        print(JSON.stringify({ success: true, data: result }, null, 2));
+      } else {
+        print(`Saved API key to ${result.path}`);
+      }
+      return;
+    }
+    case "query": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const qValue = asString(parsed.options.q);
+      if (!qValue) {
+        throw new CliError("Missing --q for query command.");
+      }
+      const page = toInt(asString(parsed.options.page), 1);
+      const pageSize = toInt(asString(parsed.options.pageSize), 1);
+      const result = await runQueryCommand(http, apiKey, {
+        q: qValue,
+        page,
+        pageSize,
+      });
+      printQueryResult(result, asJson);
+      return;
+    }
+    case "act": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const endpointIdValue = asString(parsed.options["endpoint-id"]);
+      if (!endpointIdValue) {
+        throw new CliError("Missing --endpoint-id for act command.");
+      }
+      const paramsRaw = asString(parsed.options.params) ?? "{}";
+      const params = parseJsonObject(paramsRaw, "--params");
+      const paymentRail = asPaymentRail(
+        asString(parsed.options["payment-rail"]) ?? "prepaid_credits",
+      );
+      const network = asString(parsed.options.network);
+      const result = await runActCommand(http, apiKey, {
+        endpointId: endpointIdValue,
+        params,
+        paymentRail,
+        ...(network ? { network } : {}),
+      });
+      printActResult(result, asJson);
+      return;
+    }
+    case "account": {
+      const apiKey = await resolveApiKey(asString(parsed.options["api-key"]));
+      const result = await runAccountCommand(http, apiKey);
+      printAccountResult(result, asJson);
+      return;
+    }
+    default:
+      throw new CliError("Unknown command.", 1);
+  }
+};
+
+const parseArgs = (argv: string[]): ParsedArgs => {
+  const command = argv[0];
+  if (
+    command !== "query" &&
+    command !== "act" &&
+    command !== "account" &&
+    command !== "login"
+  ) {
+    printUsage();
+    throw new CliError(
+      "Invalid command. Use one of: login, query, act, account.",
+      1,
+    );
+  }
+
+  const options: Record<string, string | boolean> = {};
+  let index = 1;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (!token || !token.startsWith("--")) {
+      throw new CliError(`Unexpected argument: ${token ?? "<empty>"}`);
+    }
+
+    const key = token.slice(2);
+    const allowedForCommand = COMMAND_OPTIONS[command];
+    if (!GLOBAL_OPTIONS.has(key) && !allowedForCommand.has(key)) {
+      throw new CliError(`Unknown option for ${command}: --${key}`);
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      options[key] = true;
+      index += 1;
+      continue;
+    }
+
+    options[key] = next;
+    index += 2;
+  }
+
+  return {
+    command,
+    options,
+  };
+};
+
+const printUsage = (): void => {
+  print("Usage:");
+  print("  lidian login [--key ld_...] [--json]");
+  print(
+    '  lidian query --q "<term>" [--page 1] [--pageSize 1..3] [--api-key <key>] [--json]',
+  );
+  print(
+    "  lidian act --endpoint-id <uuid> --params '<json>' [--payment-rail prepaid_credits|x402] [--api-key <key>] [--json]",
+  );
+  print("             [--network base|ethereum]");
+  print("  lidian account [--api-key <key>] [--json]");
+};
+
+const asString = (value: string | boolean | undefined): string | undefined => {
+  if (typeof value === "string") return value;
+  return undefined;
+};
+
+const toInt = (value: string | undefined, fallback: number): number => {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new CliError(`Invalid integer value: ${value}`);
+  }
+  return parsed;
+};
+
+const parseJsonObject = (
+  value: string,
+  flagName: string,
+): Record<string, unknown> => {
+  const parsed = JSON.parse(value) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${flagName} must be a JSON object.`);
+  }
+  return parsed as Record<string, unknown>;
+};
+
+const asPaymentRail = (value: string): PaymentRail => {
+  if (value === "prepaid_credits" || value === "x402") return value;
+  throw new CliError("Invalid --payment-rail. Use prepaid_credits or x402.");
+};
+
+main().catch(fail);

package/src/lib/auth.ts

@@ -0,0 +1,15 @@
+import { readConfig } from "@/lib/config";
+import { CliError } from "@/lib/errors";
+
+export const resolveApiKey = async (
+  argsApiKey: string | undefined,
+): Promise<string> => {
+  const config = await readConfig();
+  const key = argsApiKey ?? process.env.LIDIAN_API_KEY ?? config.apiKey;
+  if (!key) {
+    throw new CliError(
+      "Missing API key. Use `lidian login --key ld_...`, pass --api-key, or set LIDIAN_API_KEY.",
+    );
+  }
+  return key;
+};

package/src/lib/config.ts

@@ -0,0 +1,33 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface LidianConfig {
+  apiKey?: string;
+}
+
+const CONFIG_PATH = join(homedir(), ".lidian", "config.json");
+
+export const getConfigPath = (): string => CONFIG_PATH;
+
+export const readConfig = async (): Promise<LidianConfig> => {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const apiKey =
+      "apiKey" in parsed && typeof parsed.apiKey === "string"
+        ? parsed.apiKey
+        : undefined;
+    return { apiKey };
+  } catch {
+    return {};
+  }
+};
+
+export const writeConfig = async (config: LidianConfig): Promise<void> => {
+  await mkdir(dirname(CONFIG_PATH), { recursive: true });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+};

package/src/lib/errors.ts

@@ -0,0 +1,9 @@
+export class CliError extends Error {
+  code: number;
+
+  constructor(message: string, code = 1) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+  }
+}

package/src/lib/http.ts

@@ -0,0 +1,69 @@
+import { CliError } from "@/lib/errors";
+
+export interface ApiSuccess<T> {
+  success: true;
+  data: T;
+}
+
+export interface ApiFailure {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
+
+export interface HttpClient {
+  get<T>(path: string, apiKey: string): Promise<T>;
+  post<T, B>(path: string, body: B, apiKey: string): Promise<T>;
+}
+
+export const createHttpClient = (baseUrl: string): HttpClient => {
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  return {
+    async get<T>(path: string, apiKey: string): Promise<T> {
+      const response = await fetch(`${normalizedBaseUrl}${path}`, {
+        method: "GET",
+        headers: authHeaders(apiKey),
+      });
+      return handleResponse<T>(response);
+    },
+    async post<T, B>(path: string, body: B, apiKey: string): Promise<T> {
+      const response = await fetch(`${normalizedBaseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          ...authHeaders(apiKey),
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+      });
+      return handleResponse<T>(response);
+    },
+  };
+};
+
+const authHeaders = (apiKey: string): HeadersInit => ({
+  Authorization: `Bearer ${apiKey}`,
+});
+
+const handleResponse = async <T>(response: Response): Promise<T> => {
+  const json = (await response
+    .json()
+    .catch(() => null)) as ApiResponse<T> | null;
+
+  if (!response.ok) {
+    if (json && "success" in json && json.success === false) {
+      throw new CliError(`${json.error.code}: ${json.error.message}`, 1);
+    }
+    throw new CliError(`Request failed with status ${response.status}`, 1);
+  }
+
+  if (!json || !("success" in json) || json.success !== true) {
+    throw new CliError("Unexpected API response format", 1);
+  }
+
+  return json.data;
+};

package/src/lib/output.ts

@@ -0,0 +1,100 @@
+import type { AccountApiResponse } from "@/commands/account";
+import type { ActApiResponse, ActCommandResult } from "@/commands/act";
+import type { QueryApiResponse } from "@/commands/query";
+import { CliError } from "@/lib/errors";
+
+export const print = (message: string): void => {
+  process.stdout.write(`${message}\n`);
+};
+
+export const printError = (message: string): void => {
+  process.stderr.write(`${message}\n`);
+};
+
+export const printResult = (result: unknown, asJson: boolean): void => {
+  if (asJson) {
+    print(JSON.stringify(result, null, 2));
+    return;
+  }
+  print(formatForHuman(result));
+};
+
+export const printQueryResult = (
+  result: QueryApiResponse,
+  asJson: boolean,
+): void => {
+  if (asJson) {
+    printResult(result, true);
+    return;
+  }
+  if (result.items.length === 0) {
+    print("No APIs found.");
+    return;
+  }
+  print(
+    `Found ${result.items.length} of ${result.total} APIs (page ${result.page}).`,
+  );
+  for (const item of result.items) {
+    const confidence = item.matchPercent
+      ? ` confidence=${item.matchPercent.toFixed(1)}%`
+      : "";
+    print(
+      `- ${item.name} (${item.id}) auth=${item.authType} cost=${item.defaultCostPerUse}c${confidence}`,
+    );
+  }
+};
+
+export const printActResult = (
+  result: ActCommandResult,
+  asJson: boolean,
+): void => {
+  if (asJson) {
+    printResult(result.execution, true);
+    return;
+  }
+  if (result.payment) {
+    print(
+      `x402 preflight: payTo=${result.payment.requirements.payTo} amount=${result.payment.requirements.amountFormatted} verified=${String(result.payment.verified)}`,
+    );
+  }
+  printExecutionResult(result.execution);
+};
+
+export const printAccountResult = (
+  result: AccountApiResponse,
+  asJson: boolean,
+): void => {
+  if (asJson) {
+    printResult(result, true);
+    return;
+  }
+  print(`Account: ${result.user.id}`);
+  print(`Balance: ${result.balance.balance} credits`);
+};
+
+const printExecutionResult = (result: ActApiResponse): void => {
+  print(
+    `Execution succeeded. Spent=${result.credits.spent} balance=${result.credits.balance}`,
+  );
+  print(JSON.stringify(result.data, null, 2));
+};
+
+const formatForHuman = (value: unknown): string => {
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value, null, 2);
+};
+
+export const fail = (error: unknown): never => {
+  if (error instanceof CliError) {
+    printError(`Error: ${error.message}`);
+    process.exit(error.code);
+  }
+  if (error instanceof Error) {
+    printError(`Error: ${error.message}`);
+    process.exit(1);
+  }
+  printError("Error: Unknown failure");
+  process.exit(1);
+};

package/src/lib/x402.ts

@@ -0,0 +1,54 @@
+import type { HttpClient } from "@/lib/http";
+
+export interface PaymentRequirementsResponse {
+  paymentIntentId: string;
+  payTo: string;
+  amount: number;
+  amountFormatted: string;
+  network: string;
+  chainId: number;
+  asset: string;
+  expiresAt: string;
+  resource?: {
+    id: string;
+    name: string;
+    endpoint: {
+      id: string;
+      path: string;
+      method: string;
+    };
+  };
+}
+
+export interface PaymentVerifyResponse {
+  valid: boolean;
+  verifiedAt: string;
+}
+
+export const requestPaymentRequirements = async (
+  http: HttpClient,
+  apiKey: string,
+  endpointId: string,
+  network?: string,
+): Promise<PaymentRequirementsResponse> => {
+  return http.post<
+    PaymentRequirementsResponse,
+    { endpointId: string; network?: string }
+  >(
+    "/v1/payments/requirements",
+    { endpointId, ...(network ? { network } : {}) },
+    apiKey,
+  );
+};
+
+export const verifyPaymentAddress = async (
+  http: HttpClient,
+  apiKey: string,
+  payTo: string,
+): Promise<PaymentVerifyResponse> => {
+  return http.post<PaymentVerifyResponse, { payTo: string }>(
+    "/v1/payments/verify",
+    { payTo },
+    apiKey,
+  );
+};

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["bun-types"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"]
+}