@lexq/cli 0.1.19 → 0.1.20

package/README.md

@@ -1,13 +1,34 @@
 # LexQ CLI
 
-> CLI and MCP server for [LexQ](https://lexq.io) — a rule engine with built-in simulation.
-> Manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.
+> **The decision platform for engineering teams.**
+> CLI and MCP server for [LexQ](https://lexq.io) — move business rules out of
+> your deploy pipeline, prove every change with simulation, and ship without
+> a git push.
 
 **[Website](https://lexq.io)** · **[Docs](https://docs.lexq.io)** · **[Console](https://console.lexq.io)**
 
 [![npm](https://img.shields.io/npm/v/@lexq/cli)](https://www.npmjs.com/package/@lexq/cli)
 [![License](https://img.shields.io/github/license/lexq-io/lexq-cli)](LICENSE)
 
+---
+
+## Why LexQ?
+
+Your business rules — pricing, promotions, fee logic, eligibility checks —
+change often. But every change ships through the same PR → review → staging
+→ deploy cycle as your core application code. A one-line discount rule
+takes two weeks.
+
+This is an architectural problem, not a process problem. Business logic
+that changes weekly shouldn't live in code that ships quarterly.
+
+**LexQ separates the two.** Rules live outside your application. You change
+them in a visual console or through this CLI. You prove every change with
+batch simulation against real execution data. You deploy without touching
+your codebase.
+
+Every decision leaves a full audit trace.
+
 ## Install
 
 ```bash
@@ -55,7 +76,7 @@ lexq rules create --group-id <GROUP_ID> --version-id <VERSION_ID> --json '{
   }]
 }'
 
-# 6. Test
+# 6. Test against your data before shipping
 lexq analytics dry-run --version-id <VERSION_ID> --debug --mock \
   --json '{"facts":{"customer_tier":"VIP","payment_amount":100000}}'
 
@@ -64,106 +85,16 @@ lexq deploy publish --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "v1"
 lexq deploy live --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "Initial deploy"
 ```
 
-## Commands
-
-```
-lexq auth                  login | logout | whoami
-lexq status                API health check
-lexq serve                 Run as MCP stdio server (--mcp)
-lexq groups                list | get | create | update | delete
-lexq groups ab-test        start | stop | adjust
-lexq versions              list | get | create | update | delete | clone
-lexq rules                 list | get | create | update | delete | reorder | toggle
-lexq facts                 list | create | update | delete | action-metadata
-lexq deploy                publish | live | rollback | undeploy | history | detail | overview | deployable | diff
-lexq analytics             dry-run | dry-run-compare | requirements
-lexq analytics simulation  start | status | list | cancel | export
-lexq analytics dataset     upload | template
-lexq history               list | get | stats
-lexq integrations          list | get | save | delete | config-spec
-lexq logs                  list | get | action | bulk-action
-lexq webhook-subscriptions list | get | save | delete | test
-```
-
-## Global Options
-
-| Flag                     | Description                                |
-|--------------------------|--------------------------------------------|
-| `--format <json\|table>` | Output format (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                     |
-
-## AI Agent Skills
-
-LexQ CLI ships with **AI Agent Skills** — structured documentation that AI coding agents can read to autonomously manage
-policies.
-
-```
-skills/
-├── lexq-shared/SKILL.md       Core concepts, auth, workflow
-├── lexq-groups/SKILL.md       Policy groups, conflict resolution, A/B testing
-├── lexq-rules/SKILL.md        Condition syntax, action types, mutex
-├── lexq-simulation/SKILL.md   Dry run, batch simulation, compare
-├── lexq-execution/SKILL.md    Execution history, stats, failure logs,
-│                              integrations, webhook subscriptions
-└── lexq-recipes/SKILL.md      End-to-end recipes
-
-.claude/CLAUDE.md              Claude Code project context
-AGENTS.md                      Universal agent guide (Cursor, Windsurf, Gemini CLI, Cline)
-CONTEXT.md                     Platform architecture & glossary
-```
-
-### For AI Agent Developers
-
-Skills are included in the npm package. After installing `@lexq/cli`, agents can read skills from:
-
-```
-node_modules/@lexq/cli/skills/
-node_modules/@lexq/cli/AGENTS.md
-node_modules/@lexq/cli/CONTEXT.md
-```
-
-Or reference them directly in your project by copying the `skills/` directory.
-
-## Configuration
-
-Config is stored at `~/.lexq/config.json`:
-
-```json
-{
-  "apiKey": "sk_live_xxxxxxxxxxxxx",
-  "baseUrl": "https://api.lexq.io/api/v1/partners",
-  "format": "json"
-}
-```
-
-## Development
+## For AI Agents — 63 MCP Tools
 
-```bash
-git clone https://github.com/lexq-io/lexq-cli.git
-cd lexq-cli
-pnpm install
-pnpm build
-pnpm start -- groups list
-```
-
-```bash
-pnpm typecheck                  # Type check
-pnpm lint                       # ESLint
-bash tests/e2e.sh               # CLI E2E tests (requires API key)
-bash tests/test-engine-api.sh   # Engine API integration tests
-```
-
-## MCP Server Mode
-
-LexQ exposes **63 policy engine tools** via MCP. Two connection methods:
+LexQ is designed to be AI-native. The entire policy engine API — all 63 tools
+— is exposed via Model Context Protocol. Claude, Cursor, and other MCP-compatible
+agents can create, simulate, and deploy rules autonomously, with human approval
+before production.
 
 ### Claude.ai (Cloud — no install)
 
-1. Go to **Settings → Connectors → Add Custom Integration**
+1. **Settings → Connectors → Add Custom Integration**
 2. Enter: `https://mcp.lexq.io`
 3. Sign in with your LexQ account and select an API key
 4. Done — 63 tools available in every conversation
@@ -182,7 +113,7 @@ For any MCP client that supports remote servers:
 }
 ```
 
-OAuth 2.1 authentication is required. Your AI client will handle authorization automatically.
+OAuth 2.1 authentication is handled automatically by your client.
 
 ### Local (stdio)
 
@@ -192,9 +123,7 @@ Run LexQ CLI as a local MCP server:
 lexq serve --mcp
 ```
 
-This starts a stdio MCP server exposing 63 tools — the full LexQ API — to any MCP-compatible client.
-
-### Claude Desktop
+#### Claude Desktop
 
 Add to `claude_desktop_config.json`:
 
@@ -214,7 +143,7 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-### VS Code / Cursor
+#### VS Code / Cursor
 
 `.vscode/mcp.json`:
 
@@ -234,7 +163,96 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-> **Prerequisite:** `lexq auth login` must have been run once to store an API key in `~/.lexq/config.json`.
+> **Prerequisite:** `lexq auth login` must have been run once to store an
+> API key in `~/.lexq/config.json`.
+
+## AI Agent Skills
+
+LexQ CLI ships with **AI Agent Skills** — structured documentation agents
+read to understand *how* to use the tools, not just *what* they are.
+
+```
+skills/
+├── lexq-shared/SKILL.md       Core concepts, auth, workflow
+├── lexq-groups/SKILL.md       Policy groups, conflict resolution, A/B testing
+├── lexq-rules/SKILL.md        Condition syntax, action types, mutex
+├── lexq-simulation/SKILL.md   Dry run, batch simulation, compare
+├── lexq-execution/SKILL.md    Execution history, stats, failure logs
+└── lexq-recipes/SKILL.md      End-to-end recipes
+
+.claude/CLAUDE.md              Claude Code project context
+AGENTS.md                      Universal agent guide (Cursor, Windsurf, Gemini CLI, Cline)
+CONTEXT.md                     Platform architecture & glossary
+```
+
+After installing `@lexq/cli`, agents can read skills from:
+
+```
+node_modules/@lexq/cli/skills/
+node_modules/@lexq/cli/AGENTS.md
+node_modules/@lexq/cli/CONTEXT.md
+```
+
+## Commands
+
+```
+lexq auth                  login | logout | whoami
+lexq status                API health check
+lexq serve                 Run as MCP stdio server (--mcp)
+lexq groups                list | get | create | update | delete
+lexq groups ab-test        start | stop | adjust
+lexq versions              list | get | create | update | delete | clone
+lexq rules                 list | get | create | update | delete | reorder | toggle
+lexq facts                 list | create | update | delete | action-metadata
+lexq deploy                publish | live | rollback | undeploy | history | detail | overview | deployable | diff
+lexq analytics             dry-run | dry-run-compare | requirements
+lexq analytics simulation  start | status | list | cancel | export
+lexq analytics dataset     upload | template
+lexq history               list | get | stats
+lexq integrations          list | get | save | delete | config-spec
+lexq logs                  list | get | action | bulk-action
+lexq webhook-subscriptions list | get | save | delete | test
+```
+
+## Global Options
+
+| Flag                     | Description                                |
+|--------------------------|--------------------------------------------|
+| `--format <json\|table>` | Output format (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                     |
+
+## Configuration
+
+Config is stored at `~/.lexq/config.json`:
+
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "baseUrl": "https://api.lexq.io/api/v1/partners",
+  "format": "json"
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/lexq-io/lexq-cli.git
+cd lexq-cli
+pnpm install
+pnpm build
+pnpm start -- groups list
+```
+
+```bash
+pnpm typecheck                  # Type check
+pnpm lint                       # ESLint
+bash tests/e2e.sh               # CLI E2E tests (requires API key)
+bash tests/test-engine-api.sh   # Engine API integration tests
+```
 
 ## License
 

package/dist/index.js

@@ -222,20 +222,25 @@ function registerAuthCommands(program) {
       `
   ).action(async () => {
     try {
+      const globalOpts = program.opts();
       const config = loadConfig();
-      if (!config.apiKey) {
+      const apiKey = globalOpts.apiKey ?? config.apiKey;
+      const baseUrl = globalOpts.baseUrl ?? config.baseUrl;
+      if (!apiKey) {
         console.error('Not authenticated. Run "lexq auth login" first.');
         process.exit(1);
       }
       const info = await apiRequest("GET", "whoami", {
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl
+        apiKey,
+        baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
       });
-      const masked = config.apiKey.length > 8 ? config.apiKey.substring(0, 4) + "****" + config.apiKey.substring(config.apiKey.length - 4) : "****";
+      const masked = apiKey.length > 8 ? apiKey.substring(0, 4) + "****" + apiKey.substring(apiKey.length - 4) : "****";
       printJson({
         ...info,
         apiKey: masked,
-        baseUrl: config.baseUrl
+        baseUrl
       });
     } catch (error) {
       printError(error);
@@ -3437,9 +3442,16 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       description: dedent14`
         Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        
+        Returns:
+          inputFacts        — normalized input facts
+          mutatedFacts      — input facts changed by rule actions (e.g. DISCOUNT mutates payment_amount)
+          generatedVariables — new variables created by rules (e.g. last_discount_amount)
+          executionTraces   — per-rule match status
+          decisionTraces    — per-rule decision (SELECTED / BLOCKED_MUTEX / etc.)
+        
         Example input: { "facts": { "payment_amount": 100000, "customer_tier": "VIP" } }
-        Always dry-run before publishing to validate rule behavior.
-      `,
+        Always dry-run before publishing to validate rule behavior.`,
       inputSchema: {
         versionId: z6.string().uuid().describe("Policy version ID to test against"),
         facts: z6.string().describe('JSON string of facts object, e.g. {"payment_amount":100000}'),
@@ -3458,7 +3470,13 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run_compare",
     {
       title: "Dry Run Compare",
-      description: "Compare dry run results between two versions using the same input facts. Useful for validating changes.",
+      description: dedent14`
+        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        
+        Returns:
+          resultA / resultB — full DryRunResponse for each version
+          diff.mutatedDiff   — changes in mutatedFacts between A and B (key → {before, after})
+          diff.generatedDiff — changes in generatedVariables between A and B`,
       inputSchema: {
         versionIdA: z6.string().uuid().describe("Baseline version ID"),
         versionIdB: z6.string().uuid().describe("Candidate version ID"),

package/dist/mcp/register.js

@@ -611,9 +611,16 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       description: dedent2`
         Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        
+        Returns:
+          inputFacts        — normalized input facts
+          mutatedFacts      — input facts changed by rule actions (e.g. DISCOUNT mutates payment_amount)
+          generatedVariables — new variables created by rules (e.g. last_discount_amount)
+          executionTraces   — per-rule match status
+          decisionTraces    — per-rule decision (SELECTED / BLOCKED_MUTEX / etc.)
+        
         Example input: { "facts": { "payment_amount": 100000, "customer_tier": "VIP" } }
-        Always dry-run before publishing to validate rule behavior.
-      `,
+        Always dry-run before publishing to validate rule behavior.`,
       inputSchema: {
         versionId: z6.string().uuid().describe("Policy version ID to test against"),
         facts: z6.string().describe('JSON string of facts object, e.g. {"payment_amount":100000}'),
@@ -632,7 +639,13 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run_compare",
     {
       title: "Dry Run Compare",
-      description: "Compare dry run results between two versions using the same input facts. Useful for validating changes.",
+      description: dedent2`
+        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        
+        Returns:
+          resultA / resultB — full DryRunResponse for each version
+          diff.mutatedDiff   — changes in mutatedFacts between A and B (key → {before, after})
+          diff.generatedDiff — changes in generatedVariables between A and B`,
       inputSchema: {
         versionIdA: z6.string().uuid().describe("Baseline version ID"),
         versionIdB: z6.string().uuid().describe("Candidate version ID"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {