@dench.com/cli 0.3.6 → 0.3.8

package/crm.ts

@@ -29,8 +29,10 @@
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import {
+  assertNoUnknownFlags as assertNoUnknownFlagsRaw,
   CliArgError,
   getFlag,
+  getFlagWithAliases,
   hasFlag,
   parseJson as parseJsonRaw,
   shift as shiftRaw,
@@ -77,6 +79,24 @@ function parseJson(value: string | undefined): unknown {
   }
 }
 
+function assertNoUnknownFlags(args: readonly string[], command: string): void {
+  try {
+    assertNoUnknownFlagsRaw(args, command);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    throw error;
+  }
+}
+
+// Pull `--data <JSON>` from args, accepting `--fields` as an alias because
+// the entries.list output exposes the data envelope under `fields` and the
+// rest of the surface uses `crm fields` to manage column schemas — both
+// priors push callers toward `--fields`. We accept either; everywhere
+// downstream still calls the parameter `data` to match the server-side API.
+function getDataFlag(args: string[]): string | undefined {
+  return getFlagWithAliases(args, "--data", ["--fields"]);
+}
+
 async function callQuery(
   ctx: CrmCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -121,26 +141,18 @@ function out(ctx: CrmCliContext, value: unknown): void {
 
 const api = {
   transaction: {
-    begin: makeFunctionReference<"mutation">(
-      "functions/crm/transaction:begin",
-    ),
-    addOp: makeFunctionReference<"mutation">(
-      "functions/crm/transaction:addOp",
-    ),
+    begin: makeFunctionReference<"mutation">("functions/crm/transaction:begin"),
+    addOp: makeFunctionReference<"mutation">("functions/crm/transaction:addOp"),
     commit: makeFunctionReference<"mutation">(
       "functions/crm/transaction:commit",
     ),
-    abort: makeFunctionReference<"mutation">(
-      "functions/crm/transaction:abort",
-    ),
+    abort: makeFunctionReference<"mutation">("functions/crm/transaction:abort"),
     inspect: makeFunctionReference<"query">(
       "functions/crm/transaction:inspect",
     ),
   },
   reports: {
-    generate: makeFunctionReference<"query">(
-      "functions/crm/reports:generate",
-    ),
+    generate: makeFunctionReference<"query">("functions/crm/reports:generate"),
   },
   enrich: {
     requestCellEnrichment: makeFunctionReference<"mutation">(
@@ -163,22 +175,14 @@ const api = {
     create: makeFunctionReference<"mutation">("functions/crm/fields:create"),
     update: makeFunctionReference<"mutation">("functions/crm/fields:update"),
     remove: makeFunctionReference<"mutation">("functions/crm/fields:remove"),
-    reorder: makeFunctionReference<"mutation">(
-      "functions/crm/fields:reorder",
-    ),
+    reorder: makeFunctionReference<"mutation">("functions/crm/fields:reorder"),
   },
   entries: {
     list: makeFunctionReference<"query">("functions/crm/entries:list"),
     get: makeFunctionReference<"query">("functions/crm/entries:get"),
-    create: makeFunctionReference<"mutation">(
-      "functions/crm/entries:create",
-    ),
-    update: makeFunctionReference<"mutation">(
-      "functions/crm/entries:update",
-    ),
-    remove: makeFunctionReference<"mutation">(
-      "functions/crm/entries:remove",
-    ),
+    create: makeFunctionReference<"mutation">("functions/crm/entries:create"),
+    update: makeFunctionReference<"mutation">("functions/crm/entries:update"),
+    remove: makeFunctionReference<"mutation">("functions/crm/entries:remove"),
     bulkDelete: makeFunctionReference<"mutation">(
       "functions/crm/entries:bulkDelete",
     ),
@@ -186,9 +190,7 @@ const api = {
   cells: {
     get: makeFunctionReference<"query">("functions/crm/cells:get"),
     set: makeFunctionReference<"mutation">("functions/crm/cells:set"),
-    append: makeFunctionReference<"mutation">(
-      "functions/crm/cells:append",
-    ),
+    append: makeFunctionReference<"mutation">("functions/crm/cells:append"),
   },
   query: {
     queryEntries: makeFunctionReference<"query">(
@@ -208,9 +210,7 @@ const api = {
   },
   documents: {
     list: makeFunctionReference<"query">("functions/crm/documents:list"),
-    create: makeFunctionReference<"mutation">(
-      "functions/crm/documents:create",
-    ),
+    create: makeFunctionReference<"mutation">("functions/crm/documents:create"),
     link: makeFunctionReference<"mutation">("functions/crm/documents:link"),
   },
   actions: {
@@ -288,11 +288,13 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "list": {
+      assertNoUnknownFlags(ctx.args, "crm objects list");
       out(ctx, await callQuery(ctx, api.objects.list, {}));
       return;
     }
     case "get": {
       const name = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, "crm objects get");
       out(ctx, await callQuery(ctx, api.objects.get, { name }));
       return;
     }
@@ -301,6 +303,7 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
       const description = getFlag(ctx.args, "--description");
       const defaultView = getFlag(ctx.args, "--default-view") as any;
       const icon = getFlag(ctx.args, "--icon");
+      assertNoUnknownFlags(ctx.args, "crm objects create");
       out(
         ctx,
         await callMutation(ctx, api.objects.create, {
@@ -317,6 +320,7 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
       const description = getFlag(ctx.args, "--description");
       const defaultView = getFlag(ctx.args, "--default-view") as any;
       const icon = getFlag(ctx.args, "--icon");
+      assertNoUnknownFlags(ctx.args, "crm objects update");
       out(
         ctx,
         await callMutation(ctx, api.objects.update, {
@@ -331,12 +335,14 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
     case "rename": {
       const from = shift(ctx.args, "current name");
       const to = shift(ctx.args, "new name");
+      assertNoUnknownFlags(ctx.args, "crm objects rename");
       out(ctx, await callMutation(ctx, api.objects.rename, { from, to }));
       return;
     }
     case "delete":
     case "remove": {
       const name = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, "crm objects delete");
       out(ctx, await callMutation(ctx, api.objects.remove, { name }));
       return;
     }
@@ -350,6 +356,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, "crm fields list");
       out(ctx, await callQuery(ctx, api.fields.list, { objectName }));
       return;
     }
@@ -373,6 +380,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
         : hasFlag(ctx.args, "--no-indexed")
           ? false
           : undefined;
+      assertNoUnknownFlags(ctx.args, "crm fields create");
       out(
         ctx,
         await callMutation(ctx, api.fields.create, {
@@ -404,6 +412,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
         : hasFlag(ctx.args, "--no-indexed")
           ? false
           : undefined;
+      assertNoUnknownFlags(ctx.args, "crm fields update");
       out(
         ctx,
         await callMutation(ctx, api.fields.update, {
@@ -421,6 +430,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
     case "remove": {
       const objectName = shift(ctx.args, "object name");
       const fieldName = shift(ctx.args, "field name");
+      assertNoUnknownFlags(ctx.args, "crm fields delete");
       out(
         ctx,
         await callMutation(ctx, api.fields.remove, {
@@ -432,7 +442,10 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "reorder": {
       const objectName = shift(ctx.args, "object name");
-      const orderedFieldNames = ctx.args.filter((arg) => !arg.startsWith("--"));
+      // Assert before consuming the rest as positional field names so a
+      // typo'd flag fails loudly rather than getting silently filtered.
+      assertNoUnknownFlags(ctx.args, "crm fields reorder");
+      const orderedFieldNames = [...ctx.args];
       out(
         ctx,
         await callMutation(ctx, api.fields.reorder, {
@@ -453,15 +466,14 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "list": {
       const objectName = shift(ctx.args, "object name");
       const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
-      out(
-        ctx,
-        await callQuery(ctx, api.entries.list, { objectName, limit }),
-      );
+      assertNoUnknownFlags(ctx.args, "crm entries list");
+      out(ctx, await callQuery(ctx, api.entries.list, { objectName, limit }));
       return;
     }
     case "get": {
       const objectName = shift(ctx.args, "object name");
       const entryId = shift(ctx.args, "entry id");
+      assertNoUnknownFlags(ctx.args, "crm entries get");
       out(
         ctx,
         await callQuery(ctx, api.entries.get, {
@@ -473,9 +485,24 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "create": {
       const objectName = shift(ctx.args, "object name");
-      const data =
-        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
-        {};
+      const dataRaw = getDataFlag(ctx.args);
+      assertNoUnknownFlags(ctx.args, "crm entries create");
+      // Refuse silent blank-row creation. The agent that triggered this
+      // refactor passed `--fields` (which used to be silently dropped),
+      // got an empty data object, and only realized after creating 15
+      // blank rows. Be explicit: callers must pass --data (or --fields)
+      // with at least one key.
+      if (dataRaw === undefined) {
+        throw new CrmCliError(
+          'dench crm entries create requires --data \'{"Field":"Value",...}\' (alias: --fields)',
+        );
+      }
+      const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
+      if (!data || Object.keys(data).length === 0) {
+        throw new CrmCliError(
+          'dench crm entries create: --data must include at least one field. Pass --data \'{"Name":"…"}\' or use cells set after creation.',
+        );
+      }
       out(
         ctx,
         await callMutation(ctx, api.entries.create, { objectName, data }),
@@ -485,9 +512,19 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "update": {
       const objectName = shift(ctx.args, "object name");
       const entryId = shift(ctx.args, "entry id");
-      const data =
-        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
-        {};
+      const dataRaw = getDataFlag(ctx.args);
+      assertNoUnknownFlags(ctx.args, "crm entries update");
+      if (dataRaw === undefined) {
+        throw new CrmCliError(
+          'dench crm entries update requires --data \'{"Field":"Value",...}\' (alias: --fields)',
+        );
+      }
+      const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
+      if (!data || Object.keys(data).length === 0) {
+        throw new CrmCliError(
+          'dench crm entries update: --data must include at least one field to change. Pass --data \'{"Field":"…"}\'.',
+        );
+      }
       out(
         ctx,
         await callMutation(ctx, api.entries.update, {
@@ -502,6 +539,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "remove": {
       const _objectName = shift(ctx.args, "object name");
       const entryId = shift(ctx.args, "entry id");
+      assertNoUnknownFlags(ctx.args, "crm entries delete");
       out(
         ctx,
         await callMutation(ctx, api.entries.remove, {
@@ -514,6 +552,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "bulkDelete": {
       const _objectName = shift(ctx.args, "object name");
       const idsCsv = getFlag(ctx.args, "--ids") ?? "";
+      assertNoUnknownFlags(ctx.args, "crm entries bulk-delete");
       const entryIds = idsCsv.split(",").filter(Boolean);
       out(
         ctx,
@@ -535,6 +574,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
   const fieldName = shift(ctx.args, "field name");
   switch (verb) {
     case "get": {
+      assertNoUnknownFlags(ctx.args, "crm cells get");
       out(
         ctx,
         await callQuery(ctx, api.cells.get, {
@@ -547,6 +587,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "set": {
       const value = parseJson(ctx.args.shift()) ?? null;
+      assertNoUnknownFlags(ctx.args, "crm cells set");
       out(
         ctx,
         await callMutation(ctx, api.cells.set, {
@@ -560,6 +601,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "append": {
       const value = parseJson(ctx.args.shift()) ?? null;
+      assertNoUnknownFlags(ctx.args, "crm cells append");
       out(
         ctx,
         await callMutation(ctx, api.cells.append, {
@@ -584,6 +626,7 @@ async function runQueryCommand(ctx: CrmCliContext): Promise<void> {
   const select = getFlag(ctx.args, "--select")?.split(",").filter(Boolean);
   const sort = getFlag(ctx.args, "--sort");
   const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
+  assertNoUnknownFlags(ctx.args, "crm query");
   // Convex's wire serializer rejects $-prefixed object keys, so we
   // route the DSL through the dslJson string field whenever the filter
   // has any operator-shaped clause.
@@ -591,7 +634,8 @@ async function runQueryCommand(ctx: CrmCliContext): Promise<void> {
   const hasDollarKey = filter ? containsDollarKey(filter) : false;
   out(
     ctx,
-    await callQuery(ctx, 
+    await callQuery(
+      ctx,
       api.query.queryEntries,
       hasDollarKey
         ? { objectName, dslJson: JSON.stringify(dsl) }
@@ -616,6 +660,7 @@ async function runAggregateCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = shift(ctx.args, "object name");
   const fieldName = getFlag(ctx.args, "--field");
   if (!fieldName) throw new CrmCliError("--field is required");
+  assertNoUnknownFlags(ctx.args, "crm aggregate");
   out(
     ctx,
     await callQuery(ctx, api.query.aggregate, { objectName, fieldName }),
@@ -624,13 +669,14 @@ async function runAggregateCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runSearchCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = getFlag(ctx.args, "--object");
+  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "50", 10);
+  // Drain known flags before joining the rest into the search text so a
+  // typo like `--objct` surfaces instead of being concatenated into the
+  // query string.
+  assertNoUnknownFlags(ctx.args, "crm search");
   const text = ctx.args.join(" ").trim();
   if (!text) throw new CrmCliError("Search text required");
-  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "50", 10);
-  out(
-    ctx,
-    await callQuery(ctx, api.query.search, { text, objectName, limit }),
-  );
+  out(ctx, await callQuery(ctx, api.query.search, { text, objectName, limit }));
 }
 
 async function runStatusesCommand(ctx: CrmCliContext): Promise<void> {
@@ -638,12 +684,14 @@ async function runStatusesCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, "crm statuses list");
       out(ctx, await callQuery(ctx, api.statuses.list, { objectName }));
       return;
     }
     case "set": {
       const objectName = shift(ctx.args, "object name");
       const statuses = parseJson(getFlag(ctx.args, "--statuses")) as any[];
+      assertNoUnknownFlags(ctx.args, "crm statuses set");
       if (!Array.isArray(statuses)) {
         throw new CrmCliError("--statuses (JSON array) is required");
       }
@@ -663,6 +711,10 @@ async function runStatusesCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runBatchCommand(ctx: CrmCliContext): Promise<void> {
   const filePath = getFlag(ctx.args, "--file");
+  // The help text advertises --idempotency-key; thread it through so the
+  // doc and the implementation agree.
+  const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+  assertNoUnknownFlags(ctx.args, "crm batch");
   if (!filePath) {
     throw new CrmCliError(
       "dench crm batch requires --file <ops.jsonl> (one op per line)",
@@ -683,7 +735,8 @@ async function runBatchCommand(ctx: CrmCliContext): Promise<void> {
     ctx,
     await callMutation(ctx, api.batch.apply, {
       ops: ops as any,
-    }),
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+    } as any),
   );
 }
 
@@ -691,6 +744,7 @@ async function runDocsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "list": {
+      assertNoUnknownFlags(ctx.args, "crm docs list");
       out(ctx, await callQuery(ctx, api.documents.list, {}));
       return;
     }
@@ -699,6 +753,7 @@ async function runDocsCommand(ctx: CrmCliContext): Promise<void> {
       const title = getFlag(ctx.args, "--title") ?? filePath.split("/").pop()!;
       const icon = getFlag(ctx.args, "--icon");
       const linkEntryId = getFlag(ctx.args, "--link-entry");
+      assertNoUnknownFlags(ctx.args, "crm docs create");
       out(
         ctx,
         await callMutation(ctx, api.documents.create, {
@@ -714,6 +769,7 @@ async function runDocsCommand(ctx: CrmCliContext): Promise<void> {
       const filePath = shift(ctx.args, "file path");
       const objectName = getFlag(ctx.args, "--object");
       const entryId = getFlag(ctx.args, "--entry");
+      assertNoUnknownFlags(ctx.args, "crm docs link");
       out(
         ctx,
         await callMutation(ctx, api.documents.link, {
@@ -734,6 +790,7 @@ async function runActionsCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const entryId = shift(ctx.args, "entry id");
+      assertNoUnknownFlags(ctx.args, "crm actions list");
       out(
         ctx,
         await callQuery(ctx, api.actions.list, {
@@ -750,6 +807,7 @@ async function runActionsCommand(ctx: CrmCliContext): Promise<void> {
       const entryId = getFlag(ctx.args, "--entry-id");
       const goal = getFlag(ctx.args, "--goal") ?? "";
       const wait = hasFlag(ctx.args, "--wait");
+      assertNoUnknownFlags(ctx.args, "crm actions run");
       if (!fieldId || !entryId) {
         throw new CrmCliError(
           "dench crm actions run requires --field-id and --entry-id",
@@ -804,35 +862,50 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "begin": {
+      assertNoUnknownFlags(ctx.args, "crm transaction begin");
       out(ctx, await callMutation(ctx, api.transaction.begin, {}));
       return;
     }
     case "add": {
       const txnId = shift(ctx.args, "txn id");
       const opType = shift(ctx.args, "op type (entries.create|update|delete)");
-      const objectName = ctx.args[0];
       let op: any;
       if (opType === "entries.create") {
-        op = {
-          type: "entries.create",
-          objectName: shift(ctx.args, "object name"),
-          data:
-            (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
-            {},
-        };
+        const opObjectName = shift(ctx.args, "object name");
+        const dataRaw = getDataFlag(ctx.args);
+        if (dataRaw === undefined) {
+          throw new CrmCliError(
+            "dench crm transaction add <txn> entries.create requires --data '{...}' (alias: --fields)",
+          );
+        }
+        const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
+        if (!data || Object.keys(data).length === 0) {
+          throw new CrmCliError(
+            "dench crm transaction add entries.create: --data must include at least one field.",
+          );
+        }
+        op = { type: "entries.create", objectName: opObjectName, data };
       } else if (opType === "entries.update") {
-        op = {
-          type: "entries.update",
-          entryId: shift(ctx.args, "entry id"),
-          data:
-            (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
-            {},
-        };
+        const opEntryId = shift(ctx.args, "entry id");
+        const dataRaw = getDataFlag(ctx.args);
+        if (dataRaw === undefined) {
+          throw new CrmCliError(
+            "dench crm transaction add <txn> entries.update requires --data '{...}' (alias: --fields)",
+          );
+        }
+        const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
+        if (!data || Object.keys(data).length === 0) {
+          throw new CrmCliError(
+            "dench crm transaction add entries.update: --data must include at least one field.",
+          );
+        }
+        op = { type: "entries.update", entryId: opEntryId, data };
       } else if (opType === "entries.delete") {
         op = { type: "entries.delete", entryId: shift(ctx.args, "entry id") };
       } else {
         throw new CrmCliError(`Unknown txn op type: ${opType}`);
       }
+      assertNoUnknownFlags(ctx.args, "crm transaction add");
       out(
         ctx,
         await callMutation(ctx, api.transaction.addOp, {
@@ -844,6 +917,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "commit": {
       const txnId = shift(ctx.args, "txn id");
+      assertNoUnknownFlags(ctx.args, "crm transaction commit");
       out(
         ctx,
         await callMutation(ctx, api.transaction.commit, {
@@ -854,6 +928,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "abort": {
       const txnId = shift(ctx.args, "txn id");
+      assertNoUnknownFlags(ctx.args, "crm transaction abort");
       out(
         ctx,
         await callMutation(ctx, api.transaction.abort, {
@@ -864,6 +939,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "inspect": {
       const txnId = shift(ctx.args, "txn id");
+      assertNoUnknownFlags(ctx.args, "crm transaction inspect");
       out(
         ctx,
         await callQuery(ctx, api.transaction.inspect, {
@@ -878,6 +954,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
       ctx.args.unshift(verb ?? "");
       const filePath = getFlag(ctx.args, "--file");
       const commit = hasFlag(ctx.args, "--commit");
+      assertNoUnknownFlags(ctx.args, "crm transaction --file");
       if (!filePath) {
         throw new CrmCliError(
           "dench crm transaction --file <ops.json> [--commit]",
@@ -886,10 +963,9 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
       const fs = await import("node:fs/promises");
       const text = await fs.readFile(filePath, "utf-8");
       const ops = JSON.parse(text) as unknown[];
-      const begun = (await callMutation(ctx, 
-        api.transaction.begin,
-        {},
-      )) as { txnId: string };
+      const begun = (await callMutation(ctx, api.transaction.begin, {})) as {
+        txnId: string;
+      };
       for (const op of ops) {
         await callMutation(ctx, api.transaction.addOp, {
           txnId: begun.txnId as any,
@@ -924,6 +1000,7 @@ async function runImportCommand(ctx: CrmCliContext): Promise<void> {
     | "skip"
     | "update"
     | "error";
+  assertNoUnknownFlags(ctx.args, "crm import");
   if (!csvPath && !jsonlPath) {
     throw new CrmCliError(
       "dench crm import <object> requires --csv <path> or --jsonl <path>",
@@ -965,10 +1042,9 @@ async function runImportCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runExportCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = shift(ctx.args, "object name");
-  const format = (getFlag(ctx.args, "--format") ?? "jsonl") as
-    | "csv"
-    | "jsonl";
+  const format = (getFlag(ctx.args, "--format") ?? "jsonl") as "csv" | "jsonl";
   const limit = parseInt(getFlag(ctx.args, "--limit") ?? "10000", 10);
+  assertNoUnknownFlags(ctx.args, "crm export");
   // Page through entries.list in 1000-row chunks.
   const all: any[] = [];
   let cursor = 0;
@@ -1012,9 +1088,7 @@ export function parseCsv(
   const rows: Record<string, unknown>[] = [];
   const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
   if (lines.length === 0) return rows;
-  const header = parseCsvLine(lines[0]).map(
-    (col) => colMap[col] ?? col,
-  );
+  const header = parseCsvLine(lines[0]).map((col) => colMap[col] ?? col);
   for (let i = 1; i < lines.length; i++) {
     const cols = parseCsvLine(lines[i]);
     const row: Record<string, unknown> = {};
@@ -1109,7 +1183,10 @@ async function runSqlCommand(ctx: CrmCliContext): Promise<void> {
         .split(",")
         .map((s) => {
           const desc = /\s+DESC\s*$/i.test(s);
-          return `${desc ? "-" : ""}${s.replace(/\s+(asc|desc)\s*$/i, "").trim().replace(/"/g, "")}`;
+          return `${desc ? "-" : ""}${s
+            .replace(/\s+(asc|desc)\s*$/i, "")
+            .trim()
+            .replace(/"/g, "")}`;
         })
         .join(",")
     : undefined;
@@ -1131,6 +1208,7 @@ async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "search": {
+      assertNoUnknownFlags(ctx.args, "crm people search");
       const text = ctx.args.join(" ").trim();
       if (!text) throw new CrmCliError("Search text required");
       out(
@@ -1144,9 +1222,19 @@ async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
       return;
     }
     case "upsert": {
-      const data =
-        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
-        {};
+      const dataRaw = getDataFlag(ctx.args);
+      assertNoUnknownFlags(ctx.args, "crm people upsert");
+      if (dataRaw === undefined) {
+        throw new CrmCliError(
+          'dench crm people upsert requires --data \'{"Email Address":"…",...}\' (alias: --fields)',
+        );
+      }
+      const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
+      if (!data || Object.keys(data).length === 0) {
+        throw new CrmCliError(
+          "dench crm people upsert: --data must include at least one field.",
+        );
+      }
       out(
         ctx,
         await callMutation(ctx, api.entries.create, {
@@ -1159,11 +1247,13 @@ async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
     case "enrich": {
       const entryId = shift(ctx.args, "person entry id");
       const provider = getFlag(ctx.args, "--provider");
+      const fieldName = getFlag(ctx.args, "--field") ?? "Email Address";
+      assertNoUnknownFlags(ctx.args, "crm people enrich");
       out(
         ctx,
         await callMutation(ctx, api.enrich.requestObjectEnrichment, {
           objectName: "people",
-          fieldName: getFlag(ctx.args, "--field") ?? "Email Address",
+          fieldName,
           provider,
         }),
       );
@@ -1182,6 +1272,7 @@ async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "search": {
+      assertNoUnknownFlags(ctx.args, "crm companies search");
       const text = ctx.args.join(" ").trim();
       if (!text) throw new CrmCliError("Search text required");
       out(
@@ -1197,9 +1288,15 @@ async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
     case "upsert": {
       const domain = getFlag(ctx.args, "--domain");
       const name = getFlag(ctx.args, "--name");
+      assertNoUnknownFlags(ctx.args, "crm companies upsert");
       const data: Record<string, unknown> = {};
       if (domain) data["Domain"] = domain;
       if (name) data["Name"] = name;
+      if (Object.keys(data).length === 0) {
+        throw new CrmCliError(
+          "dench crm companies upsert requires at least --domain or --name. For arbitrary fields, use `dench crm entries create company --data '{...}'`.",
+        );
+      }
       out(
         ctx,
         await callMutation(ctx, api.entries.create, {
@@ -1212,11 +1309,13 @@ async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
     case "enrich": {
       const entryId = shift(ctx.args, "company entry id");
       const provider = getFlag(ctx.args, "--provider");
+      const fieldName = getFlag(ctx.args, "--field") ?? "Domain";
+      assertNoUnknownFlags(ctx.args, "crm companies enrich");
       out(
         ctx,
         await callMutation(ctx, api.enrich.requestObjectEnrichment, {
           objectName: "company",
-          fieldName: getFlag(ctx.args, "--field") ?? "Domain",
+          fieldName,
           provider,
         }),
       );
@@ -1238,6 +1337,7 @@ async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
       const entryId = shift(ctx.args, "entry id");
       const fieldName = shift(ctx.args, "field name");
       const provider = getFlag(ctx.args, "--provider");
+      assertNoUnknownFlags(ctx.args, "crm enrich cell");
       out(
         ctx,
         await callMutation(ctx, api.enrich.requestCellEnrichment, {
@@ -1254,6 +1354,7 @@ async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
       const fieldName = getFlag(ctx.args, "--field");
       const missingOnly = !hasFlag(ctx.args, "--all");
       const provider = getFlag(ctx.args, "--provider");
+      assertNoUnknownFlags(ctx.args, "crm enrich object");
       if (!fieldName) {
         throw new CrmCliError(
           "dench crm enrich object <name> --field <field> [--provider ...] [--all]",
@@ -1286,11 +1387,7 @@ async function runReportsCommand(ctx: CrmCliContext): Promise<void> {
   }
   const _name = shift(ctx.args, "report name");
   const objectName = getFlag(ctx.args, "--object");
-  const type = getFlag(ctx.args, "--type") as
-    | "pie"
-    | "bar"
-    | "line"
-    | "table";
+  const type = getFlag(ctx.args, "--type") as "pie" | "bar" | "line" | "table";
   const groupBy = getFlag(ctx.args, "--group-by");
   const metric = getFlag(ctx.args, "--metric") as
     | "count"
@@ -1300,6 +1397,7 @@ async function runReportsCommand(ctx: CrmCliContext): Promise<void> {
     | "max"
     | undefined;
   const metricField = getFlag(ctx.args, "--metric-field");
+  assertNoUnknownFlags(ctx.args, "crm reports generate");
   if (!objectName || !type || !groupBy) {
     throw new CrmCliError(
       "dench crm reports generate requires --object, --type, --group-by",
@@ -1341,10 +1439,13 @@ Fields (columns):
 Entries (rows):
   dench crm entries list <object> [--limit N] [--json]
   dench crm entries get <object> <entryId>
-  dench crm entries create <object> --data '{"Field":"Value",...}'
-  dench crm entries update <object> <entryId> --data '{...}'
+  dench crm entries create <object> --data '{"Field":"Value",...}'    (alias: --fields)
+  dench crm entries update <object> <entryId> --data '{...}'           (alias: --fields)
   dench crm entries delete <object> <entryId>
   dench crm entries bulk-delete <object> --ids id1,id2,id3
+  Note: --data is REQUIRED on create/update and must include >=1 field.
+        An empty --data '{}' is rejected — use 'crm cells set' for
+        single-field tweaks instead of creating a placeholder blank row.
 
 Cells (single-field updates):
   dench crm cells get <object> <entryId> <field>
@@ -1385,7 +1486,7 @@ SQL escape hatch (subset; flat SELECTs only):
 
 People + companies shortcuts:
   dench crm people search '<query>'
-  dench crm people upsert --data '{"Email Address":"jane@example.com",...}'
+  dench crm people upsert --data '{"Email Address":"jane@example.com",...}'   (alias: --fields)
   dench crm people enrich <entryId> [--provider apollo]
   dench crm companies search '<query>'
   dench crm companies upsert --domain acme.com [--name Acme]