zinkee 0.1.11 → 0.1.15

package/AGENTS.md

@@ -50,3 +50,45 @@ Use this order when reasoning about behavior:
 ## Testing
 
 Prefer focused command tests and parser/client unit tests.
+
+> **Unit tests use `fetchMock` and never hit the real API.** When changing the
+> shape of a payload (enum values, property names, structure), unit tests will
+> still pass even if the real API would reject the request with `400`. For
+> shape-sensitive changes — especially edits to strings in `src/utils/examples.ts`
+> — also run the resulting command against a real workspace and confirm the API
+> accepts it.
+
+## Contributing
+
+### Branches
+
+- `feature/eng-<ticket>-<slug>` for Linear-tracked work
+- `fix/<slug>` / `chore/<slug>` / `docs/<slug>` for untracked work
+- Never push to `main` directly; always open a PR
+
+### Commits
+
+- Conventional Commits format: `<type>(<scope>): <subject>` (e.g.
+  `fix(displays): correct chart-type values in widget examples`)
+- Subject in imperative mood, under ~72 chars, no trailing period
+- Body explains the *why*, not the *what* — the diff already shows what changed
+- Stage files explicitly (`git add <path>`); never `git add -A`
+- Don't add `Co-Authored-By:` trailers; existing history doesn't use them
+
+### Before committing
+
+1. `npm run typecheck` — must pass
+2. `npm test` — must pass
+3. For changes that affect runtime behaviour or `--example` output, also
+   exercise the affected commands against a live workspace (see Testing note
+   above).
+
+### Versioning
+
+- Versioning is patch-only today (`0.1.x`). Bump the patch number unless the
+  team decides to move to a different scheme.
+- Every PR that ships user-visible changes (new commands, fixed examples,
+  behaviour changes) bumps `package.json` version in the same PR — not in a
+  separate "release" PR.
+- Before bumping, fetch `origin/main` to make sure the version you pick isn't
+  already taken by another PR that merged ahead of yours.

package/README.md

@@ -273,10 +273,17 @@ zinkee records update projects <record-uuid> --set status=2
 
 # Delete
 zinkee records delete projects <record-uuid>
+
+# Clear all records from a schema (destructive — irreversible)
+zinkee records clear projects
 ```
 
 Option values are written as numbers (`--set status=1`) but returned as strings (`"1"`). Number values are stored and returned as strings.
 
+`records clear` removes every record from the schema's table. Heritage rules
+(`CASCADE` / `SET NULL`) propagate to child schemas asynchronously through the
+CDC pipeline, so related tables converge eventually. Blocked by `--read-only`.
+
 ---
 
 ## Files

package/dist/index.js

@@ -660,6 +660,13 @@ var commandRegistry = {
     supportsRaw: false,
     output: writeOutput
   },
+  "records clear": {
+    command: "records clear",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
   "comments list": {
     command: "comments list",
     accessLevel: "read",
@@ -732,6 +739,197 @@ var commandRegistry = {
   }
 };
 
+// src/utils/argv-rewrite.ts
+var HOISTABLE_GLOBAL_FLAGS = {
+  "--profile": "value",
+  "--base-url": "value",
+  "--api-key": "value",
+  "--read-only": "boolean",
+  "--json": "boolean"
+};
+function isHoistableFlag(flagName) {
+  return Object.hasOwn(HOISTABLE_GLOBAL_FLAGS, flagName);
+}
+function getCommandPath(command) {
+  const parts = [];
+  let cursor = command;
+  while (cursor && cursor.parent) {
+    parts.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return parts.join(" ");
+}
+function buildOptionMetadata(program) {
+  const valueFlags = /* @__PURE__ */ new Set();
+  const booleanFlags = /* @__PURE__ */ new Set();
+  const localOptionsByCommand = /* @__PURE__ */ new Map();
+  function visit(command, isRoot) {
+    const localFlags = /* @__PURE__ */ new Set();
+    for (const option of command.options) {
+      if (!option.long) continue;
+      if (option.required || option.optional) {
+        valueFlags.add(option.long);
+      } else {
+        booleanFlags.add(option.long);
+      }
+      if (!isRoot) {
+        localFlags.add(option.long);
+      }
+    }
+    if (!isRoot) {
+      localOptionsByCommand.set(getCommandPath(command), localFlags);
+    }
+    for (const sub of command.commands) {
+      visit(sub, false);
+    }
+  }
+  visit(program, true);
+  return { valueFlags, booleanFlags, localOptionsByCommand };
+}
+function createDefaultOptionMetadata() {
+  return {
+    valueFlags: /* @__PURE__ */ new Set([
+      "--profile",
+      "--base-url",
+      "--api-key",
+      "--install-completion",
+      "--show-completion"
+    ]),
+    booleanFlags: /* @__PURE__ */ new Set([
+      "--read-only",
+      "--json",
+      "--example",
+      "--help"
+    ]),
+    localOptionsByCommand: /* @__PURE__ */ new Map()
+  };
+}
+function isFlagToken(token) {
+  return token.length > 1 && token.startsWith("-");
+}
+function splitFlagToken(token) {
+  if (token.startsWith("--") && token.includes("=")) {
+    const eqIdx = token.indexOf("=");
+    return {
+      flagName: token.slice(0, eqIdx),
+      inlineValue: token.slice(eqIdx + 1)
+    };
+  }
+  return { flagName: token, inlineValue: void 0 };
+}
+function flagConsumesValue(flagName, optionMeta) {
+  if (optionMeta.valueFlags.has(flagName)) {
+    return true;
+  }
+  if (optionMeta.booleanFlags.has(flagName)) {
+    return false;
+  }
+  return true;
+}
+function collectOperandTokens(userArgs, optionMeta, options = {}) {
+  const operands = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i];
+    if (token === "--") {
+      break;
+    }
+    if (isFlagToken(token)) {
+      const { flagName, inlineValue } = splitFlagToken(token);
+      if (options.skipFlag !== void 0 && flagName === options.skipFlag) {
+        i += 1;
+        continue;
+      }
+      if (inlineValue !== void 0) {
+        i += 1;
+        continue;
+      }
+      const consumes = flagConsumesValue(flagName, optionMeta);
+      const next = userArgs[i + 1];
+      if (consumes && next !== void 0 && !isFlagToken(next)) {
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+    operands.push({ index: i, token });
+    i += 1;
+  }
+  return operands;
+}
+function findCommandPath(operands, registry) {
+  if (operands.length === 0) return null;
+  const commandsByLength = Object.keys(registry).sort(
+    (left, right) => right.split(" ").length - left.split(" ").length
+  );
+  for (let start = 0; start < operands.length; start += 1) {
+    for (const commandName of commandsByLength) {
+      const parts = commandName.split(" ");
+      if (start + parts.length > operands.length) continue;
+      let matches = true;
+      for (let j = 0; j < parts.length; j += 1) {
+        if (operands[start + j].token !== parts[j]) {
+          matches = false;
+          break;
+        }
+      }
+      if (matches) {
+        return {
+          commandName,
+          firstArgvIndex: operands[start].index,
+          lastArgvIndex: operands[start + parts.length - 1].index
+        };
+      }
+    }
+  }
+  return null;
+}
+function hoistGlobalOptions(argv, optionMeta, registry) {
+  if (argv.length < 3) return [...argv];
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta);
+  const cmdPath = findCommandPath(operands, registry);
+  if (!cmdPath) return [...argv];
+  const localOptions = optionMeta.localOptionsByCommand.get(cmdPath.commandName) ?? /* @__PURE__ */ new Set();
+  const hoisted = [];
+  const remaining = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i];
+    if (token === "--") {
+      remaining.push(...userArgs.slice(i));
+      break;
+    }
+    if (!isFlagToken(token)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+    const { flagName, inlineValue } = splitFlagToken(token);
+    if (!isHoistableFlag(flagName)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+    const isAfterCommandPath = i > cmdPath.lastArgvIndex;
+    const collidesWithLocal = localOptions.has(flagName);
+    const target = isAfterCommandPath && collidesWithLocal ? remaining : hoisted;
+    target.push(token);
+    const spec = HOISTABLE_GLOBAL_FLAGS[flagName];
+    if (spec === "value" && inlineValue === void 0) {
+      const next = userArgs[i + 1];
+      if (next !== void 0 && !isFlagToken(next)) {
+        target.push(next);
+        i += 2;
+        continue;
+      }
+    }
+    i += 1;
+  }
+  return [argv[0], argv[1], ...hoisted, ...remaining];
+}
+
 // src/client.ts
 var ApiClientError = class extends Error {
   name = "ApiClientError";
@@ -1998,17 +2196,17 @@ var fieldTypeDefinitions = [
     className: "FormulaField",
     aliases: ["formula", "FormulaField"],
     description: "Calculated field from a formula.",
-    rawShape: `{"type":"FormulaField","slug":"formula-summary","label":"Formula Summary","config":{"formulaText":"concat(firstName, ' ', lastName)","uiFormatKind":"none"}}`,
+    rawShape: '{"type":"FormulaField","slug":"formula-code","label":"Formula Code","config":{"formulaText":"concat(\\"CUST-\\", f1e1d000-0000-0000-0000-000000000005)","uiFormatKind":"none"}}',
     examplePayloads: [
       {
         name: "Formula field (none)",
         payload: {
           type: "FormulaField",
-          slug: "formula-summary",
-          label: "Formula Summary",
+          slug: "formula-code",
+          label: "Formula Code",
           required: false,
           config: {
-            formulaText: "concat(firstName, ' ', lastName)",
+            formulaText: 'concat("CUST-", f1e1d000-0000-0000-0000-000000000005)',
             uiFormatKind: "none",
             status: "ACTIVE",
             conditionalFormatting: []
@@ -2023,7 +2221,7 @@ var fieldTypeDefinitions = [
           label: "Formula Total",
           required: false,
           config: {
-            formulaText: "amount * 1.21",
+            formulaText: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
             uiFormatKind: "number",
             status: "ACTIVE",
             numberFormatOptions: {
@@ -2039,11 +2237,11 @@ var fieldTypeDefinitions = [
         name: "Formula field (date)",
         payload: {
           type: "FormulaField",
-          slug: "formula-deadline",
-          label: "Computed Deadline",
+          slug: "formula-period",
+          label: "Formula Period",
           required: false,
           config: {
-            formulaText: "addDays(startDate, 7)",
+            formulaText: 'date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, "AAAA-MM")',
             uiFormatKind: "date",
             status: "ACTIVE",
             dateFormatOptions: {
@@ -2063,7 +2261,7 @@ var fieldTypeDefinitions = [
           label: "Computed Assignee",
           required: false,
           config: {
-            formulaText: "manager",
+            formulaText: "a7b8c9d0-e1f2-3a4b-5c6d-7e8f90123456",
             uiFormatKind: "member",
             status: "ACTIVE",
             conditionalFormatting: []
@@ -2800,11 +2998,11 @@ var specificExamples = {
     },
     {
       description: "Patch formula field (formula text).",
-      command: `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"amount * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
+      command: `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
       raw: `{
   "type": "FormulaField",
   "config": {
-    "formulaText": "amount * 1.10",
+    "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10",
     "uiFormatKind": "number",
     "status": "ACTIVE",
     "numberFormatOptions": {
@@ -3715,8 +3913,8 @@ var specificExamples = {
 }`
     },
     {
-      description: "Create a bar CHART widget with a time-serie x-axis and two y-axis series.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bar --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"BAR"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"LINE"}' --legend '{"position":"bottom"}'`,
+      description: "Create a bars CHART widget with a time-serie x-axis and two y-axis series.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -3728,7 +3926,7 @@ var specificExamples = {
   },
   "presentation": { "name": "Revenue by month" },
   "chart": {
-    "chartType": "bar",
+    "chartType": "bars",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "MONTH",
     "xAxisAsTimeSerie": true,
@@ -3737,13 +3935,13 @@ var specificExamples = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#4B9CD3",
-        "axisType": "BAR"
+        "axisType": "PRIMARY"
       },
       {
         "typeCalc": "COUNT",
         "fieldCalc": "id",
         "color": "#E57373",
-        "axisType": "LINE"
+        "axisType": "SECONDARY"
       }
     ],
     "legend": { "position": "bottom" }
@@ -3889,11 +4087,11 @@ var specificExamples = {
 }`
     },
     {
-      description: "Replace the chart series with a weekly line.",
-      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type line --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"LINE"}'`,
+      description: "Replace the chart series with weekly lines.",
+      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type lines --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"PRIMARY"}'`,
       raw: `{
   "chart": {
-    "chartType": "line",
+    "chartType": "lines",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "WEEK",
     "xAxisAsTimeSerie": true,
@@ -3902,7 +4100,7 @@ var specificExamples = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#2E7D32",
-        "axisType": "LINE"
+        "axisType": "PRIMARY"
       }
     ]
   }
@@ -4230,7 +4428,7 @@ var specificExamples = {
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "amount * 1.21",
+        "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
         "uiFormatKind": "number",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -4245,12 +4443,12 @@ var specificExamples = {
     {
       "id": "6d7e8f90-1234-5678-9abc-def012345678",
       "type": "FormulaField",
-      "slug": "formula-deadline",
-      "label": "Computed Deadline",
+      "slug": "formula-period",
+      "label": "Formula Period",
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "addDays(startDate, 7)",
+        "formulaText": "date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, "AAAA-MM")",
         "uiFormatKind": "date",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -4532,6 +4730,16 @@ var specificExamples = {
       response: `{
   "recordId": "550e8400-e29b-41d4-a716-446655440000",
   "deleted": true
+}`
+    }
+  ]),
+  "records clear": buildCommandExamples([
+    {
+      description: "Delete every record from a schema's table. Heritage rules (CASCADE / SET NULL) propagate to child schemas asynchronously via the CDC pipeline.",
+      command: "zinkee --json records clear contacts",
+      response: `{
+  "schemaId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+  "cleared": true
 }`
     }
   ]),
@@ -5613,7 +5821,7 @@ var specificExamples = {
     },
     {
       description: "Add a search-records action whose condition pulls its value from the trigger payload using --condition-json.",
-      command: `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+      command: `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}'`,
       raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -5628,7 +5836,7 @@ var specificExamples = {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "f1e1d000-0000-0000-0000-000000000005"
             }
           }
         ]
@@ -6137,7 +6345,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
       return buildCommandExamples([
         {
           description: `Add a create-record action with literal and trigger-based mappings targeting ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}'`,
+          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}'`,
           raw: `{
   "type": "create_record",
   "name": "Create follow-up order",
@@ -6152,7 +6360,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
         "rawValue": null,
         "source": {
           "type": "TRIGGER",
-          "id": "payload_value"
+          "id": "${schemaField.fieldId}"
         }
       }
     }
@@ -6179,7 +6387,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
         },
         {
           description: `Add a search-records action with a trigger-based condition on ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}]}'`,
           raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -6194,7 +6402,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "${schemaField.fieldId}"
             }
           }
         ]
@@ -6392,26 +6600,6 @@ async function getResolvedCommandExamples(commandName, filters = {}, options = {
 function getStdout(stdout) {
   return stdout ?? process.stdout;
 }
-function resolveExampleCommand(tokens) {
-  const commands = Object.keys(commandRegistry).sort(
-    (left, right) => right.split(" ").length - left.split(" ").length
-  );
-  for (const commandName of commands) {
-    const commandTokens2 = commandName.split(" ");
-    const matches = commandTokens2.every((token, index) => tokens[index] === token);
-    if (matches) {
-      return {
-        commandName,
-        remainingTokens: tokens.slice(commandTokens2.length)
-      };
-    }
-  }
-  const commandTokens = tokens.filter((token) => !token.startsWith("-"));
-  return {
-    commandName: commandTokens.join(" "),
-    remainingTokens: []
-  };
-}
 function extractExampleFilters(tokens) {
   const filters = {};
   for (let index = 0; index < tokens.length; index += 1) {
@@ -6451,18 +6639,19 @@ function extractExampleOverrides(tokens) {
   }
   return overrides;
 }
-function extractExampleRequest(argv) {
-  const exampleIndex = argv.indexOf("--example");
-  if (exampleIndex === -1) {
+function extractExampleRequest(argv, optionMeta = createDefaultOptionMetadata()) {
+  if (!argv.includes("--example")) {
     return null;
   }
-  const requestTokens = argv.slice(exampleIndex + 1);
-  const { commandName, remainingTokens } = resolveExampleCommand(requestTokens);
-  if (commandName.length === 0) {
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta, { skipFlag: "--example" });
+  const cmdPath = findCommandPath(operands, commandRegistry);
+  if (!cmdPath) {
     throw new CliError("invalid_cli_usage", 'Provide a command after "--example".');
   }
+  const remainingTokens = userArgs.slice(cmdPath.lastArgvIndex + 1);
   return {
-    commandName,
+    commandName: cmdPath.commandName,
     filters: extractExampleFilters(remainingTokens),
     overrides: extractExampleOverrides(argv),
     json: argv.includes("--json")
@@ -9601,6 +9790,12 @@ var RecordsApi = class {
       { method: "DELETE" }
     );
   }
+  clearRecords(schema) {
+    return this.client.requestJson(
+      `/api/v2/schemas/${selectorValue8(schema)}/records:clear`,
+      { method: "DELETE" }
+    );
+  }
   normalizeQueryInput(query) {
     const where = query.where?.map((expression) => ({
       field: expression.field,
@@ -10127,6 +10322,17 @@ function registerRecordsCommands(program, options = {}) {
     }
     writeLine9(stdout, `Deleted record "${record.value}" from schema "${schema.value}".`);
   });
+  records.command("clear").description("Delete all records from a schema's table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector7).action(async function action(schema) {
+    const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+    ensureWritable6("records clear", readOnly, "destructive");
+    const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+    const data = await api.clearRecords(resolvedSchema);
+    if (json) {
+      emitJson9(stdout, "records clear", data, filePath);
+      return;
+    }
+    writeLine9(stdout, `Cleared all records from schema "${schema.value}".`);
+  });
 }
 
 // src/commands/schemas.ts
@@ -11541,7 +11747,9 @@ async function runCli(argv) {
       process.exitCode = exitCode;
       return;
     }
-    const exampleRequest = extractExampleRequest(argv);
+    const program = buildProgram();
+    const optionMeta = buildOptionMetadata(program);
+    const exampleRequest = extractExampleRequest(argv, optionMeta);
     if (exampleRequest) {
       await showExamples(
         exampleRequest.commandName,
@@ -11555,7 +11763,8 @@ async function runCli(argv) {
       );
       throw new ExampleDisplayed();
     }
-    await buildProgram().parseAsync(argv);
+    const rewrittenArgv = hoistGlobalOptions(argv, optionMeta, commandRegistry);
+    await program.parseAsync(rewrittenArgv);
   } catch (error) {
     if (error instanceof ExampleDisplayed) {
       process.exitCode = 0;