@lexq/cli 3.0.0 → 3.0.1

package/AGENTS.md

@@ -46,7 +46,7 @@ Detailed documentation lives in the `skills/` directory. **Read the relevant ski
 2. **Always dry-run before publishing.** Run `lexq analytics dry-run` to validate.
 3. **Never modify a non-DRAFT version.** Check version status first. Clone if needed.
 4. **Always check facts before creating rules.** Run `lexq facts list` to know available keys and types.
-5. **Use `--format json` for parsing.** This is the default. Don't change it.
+5. **Leave `--format` at its default, `json`, and parse the output.** A command that writes a file chooses the file's format with `--as`, not `--format`.
 6. **Copy full UUIDs from output.** Never guess or truncate IDs.
 7. **Memo is required for all deploy operations.** `publish`, `live`, `rollback`, `undeploy` — every one needs `--memo`.
 8. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.

package/README.md

@@ -224,13 +224,15 @@ lexq webhook-subscriptions list | get | save | delete | test
 
 | Flag                     | Description                                |
 |--------------------------|--------------------------------------------|
-| `--format <json\|table>` | Output format (default: `json`)            |
+| `--format <json\|table>` | How results are printed (default: `json`)  |
 | `--api-key <key>`        | Override stored API key                    |
 | `--base-url <url>`       | Override API base URL                      |
 | `--dry-run`              | Preview the HTTP request without executing |
 | `--verbose`              | Show request/response details              |
 | `--no-color`             | Disable colored output                     |
 
+`--format` only changes how results are printed. A command that writes a file, such as `lexq facts export`, chooses the file's format with `--as csv` or `--as json`.
+
 ## Configuration
 
 Config is stored at `~/.lexq/config.json`:

package/dist/index.js

@@ -184,6 +184,14 @@ async function apiRequestWithMeta(method, path, options = {}) {
 
 // src/lib/output.ts
 import Table from "cli-table3";
+import { InvalidArgumentError } from "commander";
+var OUTPUT_FORMATS = ["json", "table"];
+function parseOutputFormat(value) {
+  if (OUTPUT_FORMATS.includes(value)) return value;
+  throw new InvalidArgumentError(
+    `Use ${OUTPUT_FORMATS.join(" or ")}. The format of an exported file is chosen with --as.`
+  );
+}
 function printJson(data) {
   console.log(stringifyJson(data, 2));
 }
@@ -394,6 +402,7 @@ var PURGE_AFTER_DAYS = 30;
 var DESCRIPTION_MAX_LENGTH = 255;
 var COMMIT_MESSAGE_MAX_LENGTH = 500;
 var SCHEDULE_TICK_MAX_MILLIS = 6e4;
+var MAX_DRY_RUN_EVALUATIONS_PER_MINUTE = 60;
 
 // src/commands/groups.ts
 import "commander";
@@ -1346,6 +1355,7 @@ function escapeUnsafe(json) {
 
 // src/lib/export.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+import { extname } from "path";
 var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
 function parseFormat(value) {
   if (typeof value === "string" && EXPORT_FORMATS.includes(value)) {
@@ -1355,6 +1365,25 @@ function parseFormat(value) {
     `Unsupported export format: ${String(value)}. Use ${EXPORT_FORMATS.join(" or ")}.`
   );
 }
+function fileFormat(command) {
+  const opts = command.opts();
+  const format = parseFormat(opts.as);
+  const extension = typeof opts.output === "string" ? extname(opts.output).slice(1).toLowerCase() : "";
+  let root = command;
+  while (root.parent) root = root.parent;
+  if (EXPORT_FORMATS.includes(extension)) {
+    if (extension !== format) {
+      console.error(
+        `Note: ${opts.output} will hold ${format}. Pass --as ${extension} to write ${extension}.`
+      );
+    }
+  } else if (root.getOptionValueSource("format") === "cli" && command.getOptionValueSource("as") !== "cli") {
+    console.error(
+      `Note: --format sets how results are printed, not the file. This file is ${format}; choose ${EXPORT_FORMATS.join(" or ")} with --as.`
+    );
+  }
+  return format;
+}
 async function runExport(path, format, options) {
   const { output, params, ...clientOptions } = options;
   const body = await apiRequest("GET", path, {
@@ -1621,10 +1650,10 @@ ${warning}
           $ lexq facts export --as json --output facts.json
           $ lexq facts export --keyword user --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport("schema/facts/export", parseFormat(opts.as), {
+      await runExport("schema/facts/export", fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -2208,13 +2237,13 @@ import "commander";
 import dedent8 from "dedent";
 
 // src/lib/dataset-upload.ts
-import { extname } from "path";
+import { extname as extname2 } from "path";
 var DATASET_CONTENT_TYPES = {
   ".csv": "text/csv",
   ".json": "application/json"
 };
 function datasetContentType(filename) {
-  return DATASET_CONTENT_TYPES[extname(filename).toLowerCase()];
+  return DATASET_CONTENT_TYPES[extname2(filename).toLowerCase()];
 }
 function uploadDataset(bytes, filename, options) {
   const form = new FormData();
@@ -2226,6 +2255,9 @@ function uploadDataset(bytes, filename, options) {
   });
 }
 
+// src/lib/dry-run-limit.ts
+var DRY_RUN_LIMIT_NOTE = `Not billed and not counted toward the plan's usage. Dry runs, dry run compares, and single-decision replays share a limit of ${MAX_DRY_RUN_EVALUATIONS_PER_MINUTE} evaluations per minute for each organization; a compare counts as two. Past the limit, a call fails with 429 (C-007) until the next minute starts.`;
+
 // src/commands/analytics.ts
 function registerAnalyticsCommands(program) {
   const analytics = program.command("analytics").description("Dry run, simulation, and requirements").addHelpText(
@@ -2255,6 +2287,8 @@ function registerAnalyticsCommands(program) {
           $ lexq analytics dry-run --version-id <vid> --file test-input.json
 
         The request body must include a "facts" object. Use --debug for execution traces
+
+        ${DRY_RUN_LIMIT_NOTE}
       `
   ).action(async (opts) => {
     try {
@@ -2293,6 +2327,8 @@ function registerAnalyticsCommands(program) {
             }'
 
         Shows side-by-side which rules matched and what actions fired for each version.
+
+        ${DRY_RUN_LIMIT_NOTE}
       `
   ).action(async (opts) => {
     try {
@@ -2604,10 +2640,10 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq analytics simulation export --id <simId> --as csv --output results.csv
           $ lexq analytics simulation export --id <simId> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport(`analytics/simulations/${opts.id}/export`, parseFormat(opts.as), {
+      await runExport(`analytics/simulations/${opts.id}/export`, fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -2666,7 +2702,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --output template.csv
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
       const config = loadConfig();
@@ -2675,7 +2711,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       if (!apiKey) {
         throw new Error('Not authenticated. Run "lexq auth login" first.');
       }
-      const fmt = parseFormat(opts.as);
+      const fmt = fileFormat(command);
       const url = new URL(
         `analytics/groups/${opts.groupId}/versions/${opts.versionId}/dataset-template`,
         baseUrl.endsWith("/") ? baseUrl : baseUrl + "/"
@@ -3007,8 +3043,10 @@ function registerReplayCommands(program) {
     "after",
     dedent11`
 
-        Free of charge (TPS throttle only). Returns decisionChanged, effect
-        changes, fired rules on both sides, and a determinism verdict.
+        Returns decisionChanged, effect changes, fired rules on both sides,
+        and a determinism verdict.
+
+        ${DRY_RUN_LIMIT_NOTE}
 
         Example:
           $ lexq replay decision --trace-id <tid> --version-id <vid>
@@ -3140,10 +3178,10 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq replay export --id <jobId> --as csv --output blast-radius.csv
           $ lexq replay export --id <jobId> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport(`replay/jobs/${opts.id}/export`, parseFormat(opts.as), {
+      await runExport(`replay/jobs/${opts.id}/export`, fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -3684,7 +3722,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       annotations: READ_ONLY,
       description: dedent15`
-        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           inputFacts        — normalized input facts
@@ -3713,7 +3751,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run Compare",
       annotations: READ_ONLY,
       description: dedent15`
-        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        Compare dry run results between two versions using the same input facts. Useful for validating changes. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           resultA / resultB — full DryRunResponse for each version
@@ -4830,7 +4868,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Replay a Decision",
       annotations: READ_ONLY,
-      description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
+      description: `Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous. ${DRY_RUN_LIMIT_NOTE} A replay sends no webhook, notification, or event: rule actions produce no outward effects.`,
       inputSchema: z10.object({
         traceId: z10.string().describe("Trace ID of the past execution to replay"),
         candidateVersionId: z10.string().uuid().describe("Version to re-evaluate against")
@@ -5428,7 +5466,12 @@ function createCli() {
   const program = new Command();
   program.name("lexq").description(
     "Command-line interface for the LexQ Decision Operations Platform. Manage policies, run Impact Simulation, and deploy from your terminal."
-  ).version(getVersion2(), "-V, --version").option("--format <format>", "Output format: json or table", "json").option("--api-key <key>", "Override stored API key").option(
+  ).version(getVersion2(), "-V, --version").option(
+    "--format <format>",
+    `How results are printed: ${OUTPUT_FORMATS.join(" or ")}`,
+    parseOutputFormat,
+    "json"
+  ).option("--api-key <key>", "Override stored API key").option(
     "--base-url <url>",
     "Override API base URL \u2014 must include the API prefix, e.g. http://localhost:8080/api/v1/partners"
   ).option("--dry-run", "Preview the HTTP request without executing").option("--verbose", "Show request/response details").option("--no-color", "Disable colored output");

package/dist/mcp/register.js

@@ -219,6 +219,7 @@ var STATS_DEFAULT_WINDOW_DAYS = 30;
 var STATS_MAX_WINDOW_DAYS = 31;
 var FAILURE_LOG_LOOKBACK_DAYS = 7;
 var PURGE_AFTER_DAYS = 30;
+var MAX_DRY_RUN_EVALUATIONS_PER_MINUTE = 60;
 
 // src/mcp/tools/groups.ts
 function registerGroupTools(server, callApi) {
@@ -652,6 +653,7 @@ var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/lib/export.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+import { extname } from "path";
 var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
 
 // src/mcp/tools/facts.ts
@@ -977,6 +979,11 @@ function registerDeployTools(server, callApi) {
 // src/mcp/tools/analytics.ts
 import { z as z7 } from "zod";
 import dedent3 from "dedent";
+
+// src/lib/dry-run-limit.ts
+var DRY_RUN_LIMIT_NOTE = `Not billed and not counted toward the plan's usage. Dry runs, dry run compares, and single-decision replays share a limit of ${MAX_DRY_RUN_EVALUATIONS_PER_MINUTE} evaluations per minute for each organization; a compare counts as two. Past the limit, a call fails with 429 (C-007) until the next minute starts.`;
+
+// src/mcp/tools/analytics.ts
 function datasetBlock(path) {
   const dataset = { type: "UPLOADED", source: "S3_BUCKET", path };
   return {
@@ -991,7 +998,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       annotations: READ_ONLY,
       description: dedent3`
-        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           inputFacts        — normalized input facts
@@ -1020,7 +1027,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run Compare",
       annotations: READ_ONLY,
       description: dedent3`
-        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        Compare dry run results between two versions using the same input facts. Useful for validating changes. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           resultA / resultB — full DryRunResponse for each version
@@ -1295,7 +1302,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Replay a Decision",
       annotations: READ_ONLY,
-      description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
+      description: `Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous. ${DRY_RUN_LIMIT_NOTE} A replay sends no webhook, notification, or event: rule actions produce no outward effects.`,
       inputSchema: z9.object({
         traceId: z9.string().describe("Trace ID of the past execution to replay"),
         candidateVersionId: z9.string().uuid().describe("Version to re-evaluate against")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "mcpName": "io.lexq/lexq",
   "description": "The Decision Operations Platform for engineering teams",
   "type": "module",
@@ -47,6 +47,7 @@
     "test:rollback": "pnpm build && node tests/rollback.mjs",
     "test:dataset-upload": "pnpm build && node tests/dataset-upload.mjs",
     "test:export-limit": "pnpm build && node tests/export-limit.mjs",
+    "test:format-options": "pnpm build && node tests/format-options.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",
     "format": "prettier --write \"src/**/*.ts\"",

package/skills/lexq-shared/SKILL.md

@@ -72,16 +72,19 @@ Every command accepts these flags:
 
 | Flag                     | Description                                | Default                               |
 |--------------------------|--------------------------------------------|---------------------------------------|
-| `--format <json\|table>` | Output format                              | `json`                                |
+| `--format <json\|table>` | How results are printed                    | `json`                                |
 | `--api-key <key>`        | Override stored API key                    | from config                           |
 | `--base-url <url>`       | Override API base URL                      | `https://api.lexq.io/api/v1/partners` |
 | `--dry-run`              | Preview the HTTP request without executing | off                                   |
 | `--verbose`              | Show request/response details              | off                                   |
 | `--no-color`             | Disable colored output                     | off                                   |
 
-**Agent best practice:** Always use `--format json` (the default). Parse JSON output programmatically. Use
+**Agent best practice:** Leave `--format` at its default, `json`, and parse the output programmatically. Use
 `--format table` only when displaying to humans.
 
+`--format` does not change a file. The commands that write one (`facts export`, `analytics simulation export`,
+`replay export`, `analytics dataset template`) choose its format with `--as csv` or `--as json`.
+
 ## Command Groups
 
 | Group                   | Commands                                                                                                                   | Description                     |