feat(fmodata): add fmodata CLI binary

apps/docs/content/docs/fmodata/meta.json

@@ -20,6 +20,8 @@
     "entity-ids",
     "extra-properties",
     "custom-fetch-handlers",
+    "---CLI---",
+    "cli",
     "---Reference---",
     "errors",
     "methods"

packages/fmodata/package.json

@@ -9,6 +9,9 @@
   "type": "module",
   "main": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
+  "bin": {
+    "fmodata": "dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "import": {
@@ -19,7 +22,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc && vite build && publint --strict",
+    "build": "tsc && vite build && tsdown && publint --strict",
     "build:watch": "tsc && vite build --watch",
     "lint": "biome check . --write",
     "lint:summary": "biome check . --reporter=summary",
@@ -31,13 +34,16 @@
     "test:build": "pnpm build && TEST_BUILD=true vitest run --typecheck",
     "test:watch:build": "TEST_BUILD=true vitest --typecheck",
     "test:e2e": "doppler run -- vitest run tests/e2e",
+    "test:cli:e2e": "doppler run -- vitest run tests/cli/e2e",
     "capture": "doppler run -- tsx scripts/capture-responses.ts",
     "knip": "knip",
     "pub:alpha": "bun run scripts/publish-alpha.ts",
     "global:link": "pnpm link --global"
   },
   "dependencies": {
     "@fetchkit/ffetch": "^4.2.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
     "dotenv": "^16.6.1",
     "es-toolkit": "^1.43.0",
     "neverthrow": "^8.2.0",
@@ -58,6 +64,7 @@
     "@types/node": "^22.19.5",
     "fast-xml-parser": "^5.3.3",
     "publint": "^0.3.16",
+    "tsdown": "^0.14.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^6.4.1",

packages/fmodata/src/cli/commands/metadata.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import type { ConnectionOptions } from "../utils/connection";
+import { buildConnection } from "../utils/connection";
+import { handleCliError } from "../utils/errors";
+import { printResult } from "../utils/output";
+
+export function makeMetadataCommand(): Command {
+  const metadata = new Command("metadata").description("FileMaker OData metadata operations");
+
+  metadata
+    .command("get")
+    .description("Get OData metadata for the database")
+    .option("--format <format>", "Output format: json or xml", "json")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        let result: unknown;
+        if (opts.format === "xml") {
+          result = await db.getMetadata({ format: "xml" });
+        } else {
+          result = await db.getMetadata({ format: "json" });
+        }
+        printResult(result, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  metadata
+    .command("tables")
+    .description("List all table names in the database")
+    .action(async (_opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        const tables = await db.listTableNames();
+        printResult(tables, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  return metadata;
+}

packages/fmodata/src/cli/commands/query.ts

@@ -0,0 +1,155 @@
+import { Command } from "commander";
+import type { ConnectionOptions } from "../utils/connection";
+import { buildConnection } from "../utils/connection";
+import { handleCliError } from "../utils/errors";
+import { printResult } from "../utils/output";
+
+function buildQueryString(params: {
+  top?: number;
+  skip?: number;
+  select?: string;
+  where?: string;
+  orderBy?: string;
+}): string {
+  const parts: string[] = [];
+  if (params.top !== undefined) {
+    parts.push(`$top=${encodeURIComponent(String(params.top))}`);
+  }
+  if (params.skip !== undefined) {
+    parts.push(`$skip=${encodeURIComponent(String(params.skip))}`);
+  }
+  if (params.select) {
+    parts.push(`$select=${encodeURIComponent(params.select)}`);
+  }
+  if (params.where) {
+    parts.push(`$filter=${encodeURIComponent(params.where)}`);
+  }
+  if (params.orderBy) {
+    // Accept "field:asc" or "field:desc" or plain "field"
+    const orderStr = params.orderBy
+      .split(",")
+      .map((part) => {
+        const [field, dir] = part.trim().split(":");
+        return dir ? `${field} ${dir}` : field;
+      })
+      .join(",");
+    parts.push(`$orderby=${encodeURIComponent(orderStr)}`);
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+
+export function makeRecordsCommand(): Command {
+  const query = new Command("records").description("FileMaker record operations (list, insert, update, delete)");
+
+  query
+    .command("list")
+    .description("List records from a table")
+    .requiredOption("--table <name>", "Table name")
+    .option("--top <n>", "Max records to return", Number)
+    .option("--skip <n>", "Records to skip", Number)
+    .option("--select <fields>", "Comma-separated field names")
+    .option("--where <expr>", "OData filter expression")
+    .option("--order-by <field>", "Order by field (format: field:asc|desc, or comma-separated)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        const qs = buildQueryString({
+          top: opts.top as number | undefined,
+          skip: opts.skip as number | undefined,
+          select: opts.select as string | undefined,
+          where: opts.where as string | undefined,
+          orderBy: opts.orderBy as string | undefined,
+        });
+        const result = await db._makeRequest<{ value: unknown[] }>(`/${opts.table}${qs}`);
+        if (result.error) {
+          throw result.error;
+        }
+        printResult(result.data.value ?? result.data, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  query
+    .command("insert")
+    .description("Insert a record into a table")
+    .requiredOption("--table <name>", "Table name")
+    .requiredOption("--data <json>", "Record data as JSON object")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        let data: Record<string, unknown>;
+        try {
+          data = JSON.parse(opts.data) as Record<string, unknown>;
+        } catch {
+          throw new Error("--data must be a valid JSON object");
+        }
+        const result = await db._makeRequest<unknown>(`/${opts.table}`, {
+          method: "POST",
+          body: JSON.stringify(data),
+        });
+        if (result.error) {
+          throw result.error;
+        }
+        printResult(result.data, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  query
+    .command("update")
+    .description("Update records in a table")
+    .requiredOption("--table <name>", "Table name")
+    .requiredOption("--data <json>", "Update data as JSON object")
+    .option("--where <expr>", "OData filter expression")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        let data: Record<string, unknown>;
+        try {
+          data = JSON.parse(opts.data) as Record<string, unknown>;
+        } catch {
+          throw new Error("--data must be a valid JSON object");
+        }
+        const qs = buildQueryString({ where: opts.where as string | undefined });
+        const result = await db._makeRequest<unknown>(`/${opts.table}${qs}`, {
+          method: "PATCH",
+          body: JSON.stringify(data),
+        });
+        if (result.error) {
+          throw result.error;
+        }
+        printResult(result.data, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  query
+    .command("delete")
+    .description("Delete records from a table")
+    .requiredOption("--table <name>", "Table name")
+    .option("--where <expr>", "OData filter expression")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        const qs = buildQueryString({ where: opts.where as string | undefined });
+        const result = await db._makeRequest<unknown>(`/${opts.table}${qs}`, {
+          method: "DELETE",
+        });
+        if (result.error) {
+          throw result.error;
+        }
+        printResult(result.data, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  return query;
+}

packages/fmodata/src/cli/commands/schema.ts

@@ -0,0 +1,86 @@
+import { Command } from "commander";
+import type { Field } from "../../client/schema-manager";
+import type { ConnectionOptions } from "../utils/connection";
+import { buildConnection } from "../utils/connection";
+import { handleCliError } from "../utils/errors";
+import { printResult } from "../utils/output";
+
+export function makeSchemaCommand(): Command {
+  const schema = new Command("schema").description("FileMaker schema modification operations");
+
+  schema
+    .command("list-tables")
+    .description("List all tables in the database")
+    .action(async (_opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        const tables = await db.listTableNames();
+        printResult(tables, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  schema
+    .command("create-table")
+    .description("Create a new table (requires --confirm to execute; dry-run by default)")
+    .requiredOption("--name <name>", "Table name")
+    .requiredOption("--fields <json>", "Fields definition as JSON array")
+    .option("--confirm", "Execute the operation (without this flag, shows what would be created)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        let fields: Field[];
+        try {
+          fields = JSON.parse(opts.fields) as Field[];
+        } catch {
+          throw new Error("--fields must be a valid JSON array");
+        }
+
+        if (!opts.confirm) {
+          console.log("[dry-run] Would create table:");
+          printResult({ tableName: opts.name, fields }, { pretty: globalOpts.pretty ?? false });
+          return;
+        }
+
+        const { db } = buildConnection(globalOpts);
+        const result = await db.schema.createTable(opts.name as string, fields);
+        printResult(result, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  schema
+    .command("add-fields")
+    .description("Add fields to an existing table (requires --confirm to execute; dry-run by default)")
+    .requiredOption("--table <name>", "Table name")
+    .requiredOption("--fields <json>", "Fields to add as JSON array")
+    .option("--confirm", "Execute the operation (without this flag, shows what would be added)")
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        let fields: Field[];
+        try {
+          fields = JSON.parse(opts.fields) as Field[];
+        } catch {
+          throw new Error("--fields must be a valid JSON array");
+        }
+
+        if (!opts.confirm) {
+          console.log("[dry-run] Would add fields to table:");
+          printResult({ tableName: opts.table, fields }, { pretty: globalOpts.pretty ?? false });
+          return;
+        }
+
+        const { db } = buildConnection(globalOpts);
+        const result = await db.schema.addFields(opts.table as string, fields);
+        printResult(result, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  return schema;
+}

packages/fmodata/src/cli/commands/script.ts

@@ -0,0 +1,34 @@
+import { Command } from "commander";
+import type { ConnectionOptions } from "../utils/connection";
+import { buildConnection } from "../utils/connection";
+import { handleCliError } from "../utils/errors";
+import { printResult } from "../utils/output";
+
+export function makeScriptCommand(): Command {
+  const script = new Command("script").description("FileMaker script operations");
+
+  script
+    .command("run <scriptName>")
+    .description("Run a FileMaker script")
+    .option("--param <json>", "Script parameter as JSON string or plain value")
+    .action(async (scriptName: string, opts, cmd) => {
+      const globalOpts = cmd.parent?.parent?.opts() as ConnectionOptions & { pretty: boolean };
+      try {
+        const { db } = buildConnection(globalOpts);
+        let scriptParam: string | number | Record<string, unknown> | undefined;
+        if (opts.param !== undefined) {
+          try {
+            scriptParam = JSON.parse(opts.param) as Record<string, unknown>;
+          } catch {
+            scriptParam = opts.param as string;
+          }
+        }
+        const result = await db.runScript(scriptName, { scriptParam });
+        printResult(result, { pretty: globalOpts.pretty ?? false });
+      } catch (err) {
+        handleCliError(err);
+      }
+    });
+
+  return script;
+}