@lexq/cli 0.1.18 → 0.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +60 -21
- package/CONTEXT.md +110 -49
- package/README.md +134 -109
- package/dist/index.js +1248 -169
- package/dist/mcp/register.d.ts +1 -1
- package/dist/mcp/register.js +210 -68
- package/package.json +3 -1
- package/skills/lexq-shared/SKILL.md +48 -42
package/AGENTS.md
CHANGED
|
@@ -4,7 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
## What is this?
|
|
6
6
|
|
|
7
|
-
LexQ CLI (`@lexq/cli`, binary: `lexq`) manages a policy execution engine. Policies are business rules (if-then) that
|
|
7
|
+
LexQ CLI (`@lexq/cli`, binary: `lexq`) manages a policy execution engine. Policies are business rules (if-then) that
|
|
8
|
+
evaluate input facts and produce actions (discounts, blocks, notifications, etc.).
|
|
9
|
+
|
|
10
|
+
The CLI also doubles as an **MCP server** — run `lexq serve --mcp` to expose 62 tools to any MCP-compatible AI client.
|
|
8
11
|
|
|
9
12
|
This file tells you how to use the CLI as an AI agent.
|
|
10
13
|
|
|
@@ -27,14 +30,14 @@ lexq auth whoami
|
|
|
27
30
|
|
|
28
31
|
Detailed documentation lives in the `skills/` directory. **Read the relevant skill before executing commands.**
|
|
29
32
|
|
|
30
|
-
| Skill
|
|
31
|
-
|
|
32
|
-
| **Shared**
|
|
33
|
-
| **Groups**
|
|
34
|
-
| **Rules**
|
|
35
|
-
| **Simulation** | `skills/lexq-simulation/SKILL.md` | Dry run, batch simulation, compare
|
|
36
|
-
| **Execution**
|
|
37
|
-
| **Recipes**
|
|
33
|
+
| Skill | File | What it covers |
|
|
34
|
+
|----------------|-----------------------------------|-------------------------------------------------------------------|
|
|
35
|
+
| **Shared** | `skills/lexq-shared/SKILL.md` | Core concepts, auth, workflow, error codes. **Read first.** |
|
|
36
|
+
| **Groups** | `skills/lexq-groups/SKILL.md` | Policy groups, conflict resolution, A/B testing |
|
|
37
|
+
| **Rules** | `skills/lexq-rules/SKILL.md` | Condition syntax, action types, mutex, examples |
|
|
38
|
+
| **Simulation** | `skills/lexq-simulation/SKILL.md` | Dry run, batch simulation, compare |
|
|
39
|
+
| **Execution** | `skills/lexq-execution/SKILL.md` | History, stats, failure logs, integrations, webhook subscriptions |
|
|
40
|
+
| **Recipes** | `skills/lexq-recipes/SKILL.md` | End-to-end workflows (copy-paste ready) |
|
|
38
41
|
|
|
39
42
|
## Agent Rules
|
|
40
43
|
|
|
@@ -44,25 +47,30 @@ Detailed documentation lives in the `skills/` directory. **Read the relevant ski
|
|
|
44
47
|
4. **Always check facts before creating rules.** Run `lexq facts list` to know available keys and types.
|
|
45
48
|
5. **Use `--format json` for parsing.** This is the default. Don't change it.
|
|
46
49
|
6. **Copy full UUIDs from output.** Never guess or truncate IDs.
|
|
47
|
-
7. **
|
|
50
|
+
7. **Memo is required for all deploy operations.** `publish`, `live`, `rollback`, `undeploy` — every one needs `--memo`.
|
|
51
|
+
8. **For deployment lifecycle notifications use webhook subscriptions, not integrations.** Integrations fire on rule
|
|
52
|
+
match; webhook subscriptions fire on platform events (VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED).
|
|
53
|
+
9. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.
|
|
48
54
|
|
|
49
|
-
## Complete Command Inventory (
|
|
55
|
+
## Complete Command Inventory (67 commands)
|
|
50
56
|
|
|
51
57
|
```
|
|
52
58
|
lexq auth login|logout|whoami
|
|
53
59
|
lexq status
|
|
60
|
+
lexq serve --mcp # MCP stdio server mode
|
|
54
61
|
lexq groups list|get|create|update|delete
|
|
55
62
|
lexq groups ab-test start|stop|adjust
|
|
56
63
|
lexq versions list|get|create|update|delete|clone
|
|
57
64
|
lexq rules list|get|create|update|delete|reorder|toggle
|
|
58
|
-
lexq facts list|create|update|delete
|
|
59
|
-
lexq deploy publish|live|rollback|undeploy|history|detail|overview
|
|
65
|
+
lexq facts list|create|update|delete|action-metadata
|
|
66
|
+
lexq deploy publish|live|rollback|undeploy|history|detail|overview|deployable|diff
|
|
60
67
|
lexq analytics dry-run|dry-run-compare|requirements
|
|
61
68
|
lexq analytics simulation start|status|list|cancel|export
|
|
62
69
|
lexq analytics dataset upload|template
|
|
63
70
|
lexq history list|get|stats
|
|
64
71
|
lexq integrations list|get|save|delete|config-spec
|
|
65
72
|
lexq logs list|get|action|bulk-action
|
|
73
|
+
lexq webhook-subscriptions list|get|save|delete|test
|
|
66
74
|
```
|
|
67
75
|
|
|
68
76
|
## Example: Create and Deploy a Policy (Minimal)
|
|
@@ -95,24 +103,55 @@ lexq deploy publish --group-id $GID --version-id $VID --memo "v1"
|
|
|
95
103
|
lexq deploy live --group-id $GID --version-id $VID --memo "Initial deploy"
|
|
96
104
|
```
|
|
97
105
|
|
|
106
|
+
## Example: Subscribe to Deployment Notifications
|
|
107
|
+
|
|
108
|
+
Webhook subscriptions fire on platform events — separate from rule-level webhooks.
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
# Subscribe to Slack for deployment events
|
|
112
|
+
lexq webhook-subscriptions save --json '{
|
|
113
|
+
"name": "Slack Deploy Notifications",
|
|
114
|
+
"webhookUrl": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
|
|
115
|
+
"subscribedEvents": ["VERSION_PUBLISHED", "DEPLOYED", "ROLLED_BACK", "UNDEPLOYED"],
|
|
116
|
+
"payloadFormat": "SLACK"
|
|
117
|
+
}'
|
|
118
|
+
|
|
119
|
+
# Test delivery
|
|
120
|
+
lexq webhook-subscriptions test --id <SUBSCRIPTION_ID>
|
|
121
|
+
```
|
|
122
|
+
|
|
98
123
|
## IDE-Specific Notes
|
|
99
124
|
|
|
100
125
|
### Cursor / Windsurf / Cline
|
|
126
|
+
|
|
101
127
|
Place this file in the project root. The IDE will auto-discover it.
|
|
102
128
|
|
|
103
129
|
### Claude Code
|
|
104
|
-
|
|
130
|
+
|
|
131
|
+
See `.claude/CLAUDE.md` for additional project-specific context (code structure, build commands, architecture
|
|
132
|
+
principles).
|
|
105
133
|
|
|
106
134
|
### Gemini CLI
|
|
135
|
+
|
|
107
136
|
Read this file and the skills directory. All commands are documented with full examples.
|
|
108
137
|
|
|
138
|
+
### MCP clients (Claude.ai, Claude Desktop, VS Code, etc.)
|
|
139
|
+
|
|
140
|
+
Connect via:
|
|
141
|
+
|
|
142
|
+
- **Cloud:** `https://mcp.lexq.io` (OAuth 2.1)
|
|
143
|
+
- **Local stdio:** `npx @lexq/cli serve --mcp`
|
|
144
|
+
|
|
145
|
+
62 tools mirror the CLI command inventory.
|
|
146
|
+
|
|
109
147
|
## Troubleshooting
|
|
110
148
|
|
|
111
|
-
| Problem
|
|
112
|
-
|
|
113
|
-
| `Not authenticated`
|
|
114
|
-
| `ENTITY_NOT_FOUND`
|
|
115
|
-
| `CANNOT_MODIFY`
|
|
116
|
-
| `EMPTY_RULES`
|
|
149
|
+
| Problem | Solution |
|
|
150
|
+
|------------------------------|--------------------------------------------------------------------------|
|
|
151
|
+
| `Not authenticated` | Run `lexq auth login` |
|
|
152
|
+
| `ENTITY_NOT_FOUND` | Verify the ID exists via the corresponding `list` command |
|
|
153
|
+
| `CANNOT_MODIFY` | Version is not DRAFT. Clone it: `lexq versions clone` |
|
|
154
|
+
| `EMPTY_RULES` | Add at least one rule before publishing |
|
|
117
155
|
| `ACTIVATION_CONFIG_MISMATCH` | All groups in the same activationGroup must share the same mode/strategy |
|
|
118
|
-
|
|
|
156
|
+
| `WH_URL_INVALID` | Webhook URL must be HTTPS and return 2xx for a POST |
|
|
157
|
+
| Network error | Check `lexq status` for API health |
|
package/CONTEXT.md
CHANGED
|
@@ -2,104 +2,165 @@
|
|
|
2
2
|
|
|
3
3
|
## What is LexQ?
|
|
4
4
|
|
|
5
|
-
LexQ is a **B2B SaaS policy execution engine**. Customers define business rules (conditions → actions), test them via
|
|
5
|
+
LexQ is a **B2B SaaS policy execution engine**. Customers define business rules (conditions → actions), test them via
|
|
6
|
+
simulation, deploy to production, and execute via REST API — all without modifying application code.
|
|
6
7
|
|
|
7
8
|
**Core differentiators:**
|
|
9
|
+
|
|
8
10
|
- Pre-deploy simulation against real data
|
|
9
11
|
- A/B testing for rule versions
|
|
10
12
|
- Git-style versioning with full audit trail
|
|
13
|
+
- Platform event webhooks for deployment lifecycle notifications
|
|
11
14
|
|
|
12
15
|
## Architecture
|
|
16
|
+
|
|
13
17
|
```
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
┌─────────────────────────────────────────────────────┐
|
|
19
|
+
│ Clients │
|
|
20
|
+
│ • LexQ CLI (@lexq/cli — API Key auth) │
|
|
21
|
+
│ • MCP clients (mcp.lexq.io — OAuth 2.1) │
|
|
22
|
+
│ • Console (console.lexq.io — web UI) │
|
|
23
|
+
│ • Direct HTTP (api.lexq.io — API Key) │
|
|
24
|
+
└─────────────────────────────────────────────────────┘
|
|
25
|
+
│
|
|
26
|
+
▼
|
|
27
|
+
api.lexq.io (ALB, path-routed)
|
|
28
|
+
│
|
|
29
|
+
┌──────────────┴──────────────┐
|
|
30
|
+
▼ ▼
|
|
31
|
+
/api/v1/partners /api/v1/execution
|
|
32
|
+
(policy management) (real-time rule eval)
|
|
33
|
+
│ │
|
|
34
|
+
└──────────────┬──────────────┘
|
|
35
|
+
▼
|
|
36
|
+
LexQ Policy Engine
|
|
18
37
|
```
|
|
19
38
|
|
|
20
|
-
The CLI exclusively calls the Partner API
|
|
39
|
+
The CLI exclusively calls the Partner API. Execution requests (runtime rule evaluation) use a separate path-routed
|
|
40
|
+
endpoint.
|
|
21
41
|
|
|
22
|
-
**Base URL:** `https://api.lexq.io/api/v1/partners`
|
|
42
|
+
**Partner Base URL:** `https://api.lexq.io/api/v1/partners`
|
|
43
|
+
**Execution Base URL:** `https://api.lexq.io/api/v1/execution`
|
|
23
44
|
|
|
24
45
|
## Domain Model
|
|
25
46
|
|
|
26
47
|
```
|
|
27
48
|
Tenant
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
49
|
+
├── PolicyGroup (ACTIVE | DISABLED | ARCHIVED)
|
|
50
|
+
│ ├── PolicyVersion (DRAFT → ACTIVE → ARCHIVED | EXPIRED)
|
|
51
|
+
│ │ └── PolicyRule (condition + actions, priority-ordered)
|
|
52
|
+
│ ├── PolicyDeployment (PUBLISH | DEPLOY | ROLLBACK | UNDEPLOY)
|
|
53
|
+
│ └── A/B Test (testVersionId + trafficRate)
|
|
54
|
+
│
|
|
55
|
+
├── FactDefinition (key, type, displayName — shared across all groups)
|
|
56
|
+
│
|
|
57
|
+
├── Integration (WEBHOOK | COUPON | POINT | NOTIFICATION | CRM | MESSENGER)
|
|
58
|
+
│ — fires on rule match (per-rule configured)
|
|
59
|
+
│
|
|
60
|
+
└── WebhookSubscription (subscribedEvents + webhookUrl + payloadFormat)
|
|
61
|
+
— fires on platform events (deployment lifecycle)
|
|
39
62
|
```
|
|
40
63
|
|
|
41
64
|
## Key Enums
|
|
42
65
|
|
|
43
66
|
### Policy Group Status
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
67
|
+
|
|
68
|
+
| Value | Description |
|
|
69
|
+
|------------|------------------------------------|
|
|
70
|
+
| `ACTIVE` | Normal operation |
|
|
47
71
|
| `DISABLED` | Execution blocked (emergency stop) |
|
|
48
|
-
| `ARCHIVED` | Permanently removed
|
|
72
|
+
| `ARCHIVED` | Permanently removed |
|
|
49
73
|
|
|
50
74
|
### Policy Version Status
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
75
|
+
|
|
76
|
+
| Value | Description |
|
|
77
|
+
|------------|----------------------------------------------------------|
|
|
78
|
+
| `DRAFT` | Editable. Rules can be added/modified. |
|
|
79
|
+
| `ACTIVE` | Published. Locked — no modifications allowed. |
|
|
80
|
+
| `ARCHIVED` | Superseded by a newer version. |
|
|
81
|
+
| `EXPIRED` | Past `effectiveTo` date. Auto-transitioned by scheduler. |
|
|
57
82
|
|
|
58
83
|
### Condition Operators
|
|
59
|
-
|
|
84
|
+
|
|
85
|
+
`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `CONTAINS`, `IN`,
|
|
86
|
+
`NOT_IN`
|
|
60
87
|
|
|
61
88
|
### Value Types
|
|
89
|
+
|
|
62
90
|
`STRING`, `NUMBER`, `BOOLEAN`, `LIST_STRING`, `LIST_NUMBER`
|
|
63
91
|
|
|
64
92
|
### Action Types
|
|
93
|
+
|
|
65
94
|
`DISCOUNT`, `POINT`, `COUPON_ISSUE`, `BLOCK`, `NOTIFICATION`, `WEBHOOK`, `SET_FACT`, `ADD_TAG`
|
|
66
95
|
|
|
67
96
|
### Conflict Resolution Modes
|
|
97
|
+
|
|
68
98
|
`NONE` (all fire), `EXCLUSIVE` (one winner), `MAX_N` (up to N winners)
|
|
69
99
|
|
|
70
100
|
### Conflict Resolution Strategies
|
|
101
|
+
|
|
71
102
|
`FIRST_MATCH`, `HIGHEST_PRIORITY`, `MAX_BENEFIT`
|
|
72
103
|
|
|
73
104
|
### Deployment Types
|
|
74
|
-
|
|
105
|
+
|
|
106
|
+
`PUBLISH` (DRAFT → ACTIVE), `DEPLOY` (ACTIVE → live traffic), `ROLLBACK` (revert to previous), `UNDEPLOY` (remove from
|
|
107
|
+
live)
|
|
75
108
|
|
|
76
109
|
### Execution Statuses
|
|
110
|
+
|
|
77
111
|
`SUCCESS`, `NO_MATCH`, `ERROR`, `TIMEOUT`
|
|
78
112
|
|
|
79
113
|
### Simulation Statuses
|
|
114
|
+
|
|
80
115
|
`PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`
|
|
81
116
|
|
|
82
117
|
### Decision Statuses
|
|
118
|
+
|
|
83
119
|
`SELECTED`, `NO_MATCH`, `NOT_SELECTED`, `BLOCKED_MUTEX`, `LOST_PRIORITY`, `DROPPED_LIMIT`, `ERROR`
|
|
84
120
|
|
|
121
|
+
### Platform Event Types (for webhook subscriptions)
|
|
122
|
+
|
|
123
|
+
`VERSION_PUBLISHED`, `DEPLOYED`, `ROLLED_BACK`, `UNDEPLOYED`
|
|
124
|
+
|
|
125
|
+
### Webhook Payload Formats
|
|
126
|
+
|
|
127
|
+
`GENERIC` (full JSON payload), `SLACK` (`{"text": "..."}` simplified)
|
|
128
|
+
|
|
129
|
+
## Integration vs Webhook Subscription
|
|
130
|
+
|
|
131
|
+
Two distinct webhook mechanisms — do not confuse them:
|
|
132
|
+
|
|
133
|
+
| Concern | **Integration** (WEBHOOK type) | **WebhookSubscription** |
|
|
134
|
+
|---------------|--------------------------------------------|---------------------------------------------------|
|
|
135
|
+
| When it fires | Rule match during execution | Platform event (publish/deploy/rollback/undeploy) |
|
|
136
|
+
| Configured at | Per-rule action | Per-tenant subscription |
|
|
137
|
+
| Payload | Rule-defined template | Standard platform event schema |
|
|
138
|
+
| Use case | "Notify when VIP makes a purchase" | "Notify Slack when a policy is deployed" |
|
|
139
|
+
| Signing | Optional (HMAC via Integration.credential) | Optional HMAC-SHA256 via `secret` |
|
|
140
|
+
| Formats | Free-form (any) | GENERIC or SLACK |
|
|
141
|
+
|
|
85
142
|
## Glossary
|
|
86
143
|
|
|
87
|
-
| Term
|
|
88
|
-
|
|
89
|
-
| **Policy Group**
|
|
90
|
-
| **Policy Version**
|
|
91
|
-
| **Policy Rule**
|
|
92
|
-
| **Fact**
|
|
93
|
-
| **Fact Definition**
|
|
94
|
-
| **Dry Run**
|
|
95
|
-
| **Simulation**
|
|
96
|
-
| **Activation Group**
|
|
97
|
-
| **Mutex Group**
|
|
98
|
-
| **Deployment**
|
|
99
|
-
| **Rollback**
|
|
100
|
-
| **Undeploy**
|
|
101
|
-
| **A/B Test**
|
|
102
|
-
| **Execution Trace**
|
|
103
|
-
| **Decision Trace**
|
|
104
|
-
| **Snapshot Hash**
|
|
105
|
-
| **Traffic Rate**
|
|
144
|
+
| Term | Definition |
|
|
145
|
+
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
|
146
|
+
| **Policy Group** | Top-level container for rule versions. Controls deployment lifecycle, conflict resolution, and A/B testing. |
|
|
147
|
+
| **Policy Version** | An immutable snapshot of rules. Only DRAFT versions can be modified. |
|
|
148
|
+
| **Policy Rule** | A condition → actions pair. Evaluated in priority order within a version. |
|
|
149
|
+
| **Fact** | An input variable passed during execution. Declared via Fact Definitions with key, type, and name. |
|
|
150
|
+
| **Fact Definition** | Schema declaration for a fact — its key (snake_case), value type, display name, and description. |
|
|
151
|
+
| **Dry Run** | Single-input test execution. Returns which rules matched, what actions would fire, and decision traces. |
|
|
152
|
+
| **Simulation** | Batch test replaying historical executions against a version. Compares with a baseline. |
|
|
153
|
+
| **Activation Group** | A logical grouping of Policy Groups for cross-group conflict resolution. |
|
|
154
|
+
| **Mutex Group** | A logical grouping of Policy Rules within a version for intra-version conflict resolution. |
|
|
155
|
+
| **Deployment** | The act of putting an ACTIVE version into production to receive traffic. |
|
|
156
|
+
| **Rollback** | Reverting to the previously deployed version. Creates a new deployment record. |
|
|
157
|
+
| **Undeploy** | Removing a group from live traffic. No version serves requests until re-deployed. |
|
|
158
|
+
| **A/B Test** | Splitting traffic between the current live version and a test version by percentage. |
|
|
159
|
+
| **Execution Trace** | Per-rule evaluation result showing whether the condition matched and what actions were generated. |
|
|
160
|
+
| **Decision Trace** | Final disposition of a rule after conflict resolution (SELECTED, BLOCKED_MUTEX, etc.). |
|
|
161
|
+
| **Snapshot Hash** | SHA-256 hash of a version's rule snapshot at deployment time. Used to verify integrity. |
|
|
162
|
+
| **Traffic Rate** | Percentage (0–100) of traffic routed to the A/B test version. |
|
|
163
|
+
| **Integration** | An external service binding (WEBHOOK, COUPON, POINT, NOTIFICATION, CRM, MESSENGER) referenced by rule actions. Fires per rule match. |
|
|
164
|
+
| **Webhook Subscription** | A platform event listener — receives notifications on deployment lifecycle events. Tenant-level, independent from Integrations. |
|
|
165
|
+
| **Platform Event** | A lifecycle event emitted by the engine itself (VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED). |
|
|
166
|
+
| **Failure Log** | A record of a background task failure (webhook delivery, coupon issuance, etc.) available for retry/resolve/ignore. |
|
package/README.md
CHANGED
|
@@ -1,13 +1,34 @@
|
|
|
1
1
|
# LexQ CLI
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
>
|
|
3
|
+
> **The decision platform for engineering teams.**
|
|
4
|
+
> CLI and MCP server for [LexQ](https://lexq.io) — move business rules out of
|
|
5
|
+
> your deploy pipeline, prove every change with simulation, and ship without
|
|
6
|
+
> a git push.
|
|
5
7
|
|
|
6
8
|
**[Website](https://lexq.io)** · **[Docs](https://docs.lexq.io)** · **[Console](https://console.lexq.io)**
|
|
7
9
|
|
|
8
10
|
[](https://www.npmjs.com/package/@lexq/cli)
|
|
9
11
|
[](LICENSE)
|
|
10
12
|
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Why LexQ?
|
|
16
|
+
|
|
17
|
+
Your business rules — pricing, promotions, fee logic, eligibility checks —
|
|
18
|
+
change often. But every change ships through the same PR → review → staging
|
|
19
|
+
→ deploy cycle as your core application code. A one-line discount rule
|
|
20
|
+
takes two weeks.
|
|
21
|
+
|
|
22
|
+
This is an architectural problem, not a process problem. Business logic
|
|
23
|
+
that changes weekly shouldn't live in code that ships quarterly.
|
|
24
|
+
|
|
25
|
+
**LexQ separates the two.** Rules live outside your application. You change
|
|
26
|
+
them in a visual console or through this CLI. You prove every change with
|
|
27
|
+
batch simulation against real execution data. You deploy without touching
|
|
28
|
+
your codebase.
|
|
29
|
+
|
|
30
|
+
Every decision leaves a full audit trace.
|
|
31
|
+
|
|
11
32
|
## Install
|
|
12
33
|
|
|
13
34
|
```bash
|
|
@@ -55,7 +76,7 @@ lexq rules create --group-id <GROUP_ID> --version-id <VERSION_ID> --json '{
|
|
|
55
76
|
}]
|
|
56
77
|
}'
|
|
57
78
|
|
|
58
|
-
# 6. Test
|
|
79
|
+
# 6. Test against your data before shipping
|
|
59
80
|
lexq analytics dry-run --version-id <VERSION_ID> --debug --mock \
|
|
60
81
|
--json '{"facts":{"customer_tier":"VIP","payment_amount":100000}}'
|
|
61
82
|
|
|
@@ -64,108 +85,24 @@ lexq deploy publish --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "v1"
|
|
|
64
85
|
lexq deploy live --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "Initial deploy"
|
|
65
86
|
```
|
|
66
87
|
|
|
67
|
-
##
|
|
68
|
-
|
|
69
|
-
```
|
|
70
|
-
lexq auth login | logout | whoami
|
|
71
|
-
lexq status API health check
|
|
72
|
-
lexq groups list | get | create | update | delete
|
|
73
|
-
lexq groups ab-test start | stop | adjust
|
|
74
|
-
lexq versions list | get | create | update | delete | clone
|
|
75
|
-
lexq rules list | get | create | update | delete | reorder | toggle
|
|
76
|
-
lexq facts list | create | update | delete
|
|
77
|
-
lexq deploy publish | live | rollback | undeploy | history | detail | overview
|
|
78
|
-
lexq analytics dry-run | dry-run-compare | requirements
|
|
79
|
-
lexq analytics simulation start | status | list | cancel | export
|
|
80
|
-
lexq analytics dataset upload | template
|
|
81
|
-
lexq history list | get | stats
|
|
82
|
-
lexq integrations list | get | save | delete | config-spec
|
|
83
|
-
lexq logs list | get | action | bulk-action
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
## Global Options
|
|
87
|
-
|
|
88
|
-
| Flag | Description |
|
|
89
|
-
|---|---|
|
|
90
|
-
| `--format <json\|table>` | Output format (default: `json`) |
|
|
91
|
-
| `--api-key <key>` | Override stored API key |
|
|
92
|
-
| `--base-url <url>` | Override API base URL |
|
|
93
|
-
| `--dry-run` | Preview the HTTP request without executing |
|
|
94
|
-
| `--verbose` | Show request/response details |
|
|
95
|
-
| `--no-color` | Disable colored output |
|
|
96
|
-
|
|
97
|
-
## AI Agent Skills
|
|
98
|
-
|
|
99
|
-
LexQ CLI ships with **AI Agent Skills** — structured documentation that AI coding agents can read to autonomously manage policies.
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
skills/
|
|
103
|
-
├── lexq-shared/SKILL.md Core concepts, auth, workflow
|
|
104
|
-
├── lexq-groups/SKILL.md Policy groups, conflict resolution, A/B testing
|
|
105
|
-
├── lexq-rules/SKILL.md Condition syntax, action types, mutex
|
|
106
|
-
├── lexq-simulation/SKILL.md Dry run, batch simulation, compare
|
|
107
|
-
├── lexq-execution/SKILL.md Execution history, stats, failure logs
|
|
108
|
-
└── lexq-recipes/SKILL.md 10 end-to-end recipes
|
|
109
|
-
|
|
110
|
-
.claude/CLAUDE.md Claude Code project context
|
|
111
|
-
AGENTS.md Universal agent guide (Cursor, Windsurf, Gemini CLI, Cline)
|
|
112
|
-
CONTEXT.md Platform architecture & glossary
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
### For AI Agent Developers
|
|
116
|
-
|
|
117
|
-
Skills are included in the npm package. After installing `@lexq/cli`, agents can read skills from:
|
|
118
|
-
|
|
119
|
-
```
|
|
120
|
-
node_modules/@lexq/cli/skills/
|
|
121
|
-
node_modules/@lexq/cli/AGENTS.md
|
|
122
|
-
node_modules/@lexq/cli/CONTEXT.md
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Or reference them directly in your project by copying the `skills/` directory.
|
|
126
|
-
|
|
127
|
-
## Configuration
|
|
128
|
-
|
|
129
|
-
Config is stored at `~/.lexq/config.json`:
|
|
130
|
-
|
|
131
|
-
```json
|
|
132
|
-
{
|
|
133
|
-
"apiKey": "sk_live_xxxxxxxxxxxxx",
|
|
134
|
-
"baseUrl": "https://api.lexq.io/api/v1/partners",
|
|
135
|
-
"format": "json"
|
|
136
|
-
}
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
## Development
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
git clone https://github.com/lexq-io/lexq-cli.git
|
|
143
|
-
cd lexq-cli
|
|
144
|
-
pnpm install
|
|
145
|
-
pnpm build
|
|
146
|
-
pnpm start -- groups list
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
pnpm typecheck # Type check
|
|
151
|
-
pnpm lint # ESLint
|
|
152
|
-
bash tests/e2e.sh # E2E tests (requires API key)
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
## MCP Server Mode
|
|
88
|
+
## For AI Agents — 63 MCP Tools
|
|
156
89
|
|
|
157
|
-
LexQ
|
|
90
|
+
LexQ is designed to be AI-native. The entire policy engine API — all 63 tools
|
|
91
|
+
— is exposed via Model Context Protocol. Claude, Cursor, and other MCP-compatible
|
|
92
|
+
agents can create, simulate, and deploy rules autonomously, with human approval
|
|
93
|
+
before production.
|
|
158
94
|
|
|
159
95
|
### Claude.ai (Cloud — no install)
|
|
160
96
|
|
|
161
|
-
1.
|
|
97
|
+
1. **Settings → Connectors → Add Custom Integration**
|
|
162
98
|
2. Enter: `https://mcp.lexq.io`
|
|
163
99
|
3. Sign in with your LexQ account and select an API key
|
|
164
|
-
4. Done —
|
|
100
|
+
4. Done — 63 tools available in every conversation
|
|
165
101
|
|
|
166
102
|
### Remote (Streamable HTTP)
|
|
167
103
|
|
|
168
104
|
For any MCP client that supports remote servers:
|
|
105
|
+
|
|
169
106
|
```json
|
|
170
107
|
{
|
|
171
108
|
"mcpServers": {
|
|
@@ -176,27 +113,26 @@ For any MCP client that supports remote servers:
|
|
|
176
113
|
}
|
|
177
114
|
```
|
|
178
115
|
|
|
179
|
-
OAuth 2.1 authentication is
|
|
116
|
+
OAuth 2.1 authentication is handled automatically by your client.
|
|
180
117
|
|
|
181
118
|
### Local (stdio)
|
|
182
119
|
|
|
183
120
|
Run LexQ CLI as a local MCP server:
|
|
121
|
+
|
|
184
122
|
```bash
|
|
185
123
|
lexq serve --mcp
|
|
186
124
|
```
|
|
187
125
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
### Claude Desktop
|
|
126
|
+
#### Claude Desktop
|
|
191
127
|
|
|
192
128
|
Add to `claude_desktop_config.json`:
|
|
193
129
|
|
|
194
130
|
```json
|
|
195
131
|
{
|
|
196
|
-
"mcpServers":{
|
|
197
|
-
"lexq":{
|
|
198
|
-
"command":"npx",
|
|
199
|
-
"args":[
|
|
132
|
+
"mcpServers": {
|
|
133
|
+
"lexq": {
|
|
134
|
+
"command": "npx",
|
|
135
|
+
"args": [
|
|
200
136
|
"-y",
|
|
201
137
|
"@lexq/cli",
|
|
202
138
|
"serve",
|
|
@@ -207,16 +143,16 @@ Add to `claude_desktop_config.json`:
|
|
|
207
143
|
}
|
|
208
144
|
```
|
|
209
145
|
|
|
210
|
-
|
|
146
|
+
#### VS Code / Cursor
|
|
211
147
|
|
|
212
148
|
`.vscode/mcp.json`:
|
|
213
149
|
|
|
214
150
|
```json
|
|
215
151
|
{
|
|
216
|
-
"servers":{
|
|
217
|
-
"lexq":{
|
|
218
|
-
"command":"npx",
|
|
219
|
-
"args":[
|
|
152
|
+
"servers": {
|
|
153
|
+
"lexq": {
|
|
154
|
+
"command": "npx",
|
|
155
|
+
"args": [
|
|
220
156
|
"-y",
|
|
221
157
|
"@lexq/cli",
|
|
222
158
|
"serve",
|
|
@@ -227,7 +163,96 @@ Add to `claude_desktop_config.json`:
|
|
|
227
163
|
}
|
|
228
164
|
```
|
|
229
165
|
|
|
230
|
-
> **Prerequisite:** `lexq auth login` must have been run once to store an
|
|
166
|
+
> **Prerequisite:** `lexq auth login` must have been run once to store an
|
|
167
|
+
> API key in `~/.lexq/config.json`.
|
|
168
|
+
|
|
169
|
+
## AI Agent Skills
|
|
170
|
+
|
|
171
|
+
LexQ CLI ships with **AI Agent Skills** — structured documentation agents
|
|
172
|
+
read to understand *how* to use the tools, not just *what* they are.
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
skills/
|
|
176
|
+
├── lexq-shared/SKILL.md Core concepts, auth, workflow
|
|
177
|
+
├── lexq-groups/SKILL.md Policy groups, conflict resolution, A/B testing
|
|
178
|
+
├── lexq-rules/SKILL.md Condition syntax, action types, mutex
|
|
179
|
+
├── lexq-simulation/SKILL.md Dry run, batch simulation, compare
|
|
180
|
+
├── lexq-execution/SKILL.md Execution history, stats, failure logs
|
|
181
|
+
└── lexq-recipes/SKILL.md End-to-end recipes
|
|
182
|
+
|
|
183
|
+
.claude/CLAUDE.md Claude Code project context
|
|
184
|
+
AGENTS.md Universal agent guide (Cursor, Windsurf, Gemini CLI, Cline)
|
|
185
|
+
CONTEXT.md Platform architecture & glossary
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
After installing `@lexq/cli`, agents can read skills from:
|
|
189
|
+
|
|
190
|
+
```
|
|
191
|
+
node_modules/@lexq/cli/skills/
|
|
192
|
+
node_modules/@lexq/cli/AGENTS.md
|
|
193
|
+
node_modules/@lexq/cli/CONTEXT.md
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Commands
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
lexq auth login | logout | whoami
|
|
200
|
+
lexq status API health check
|
|
201
|
+
lexq serve Run as MCP stdio server (--mcp)
|
|
202
|
+
lexq groups list | get | create | update | delete
|
|
203
|
+
lexq groups ab-test start | stop | adjust
|
|
204
|
+
lexq versions list | get | create | update | delete | clone
|
|
205
|
+
lexq rules list | get | create | update | delete | reorder | toggle
|
|
206
|
+
lexq facts list | create | update | delete | action-metadata
|
|
207
|
+
lexq deploy publish | live | rollback | undeploy | history | detail | overview | deployable | diff
|
|
208
|
+
lexq analytics dry-run | dry-run-compare | requirements
|
|
209
|
+
lexq analytics simulation start | status | list | cancel | export
|
|
210
|
+
lexq analytics dataset upload | template
|
|
211
|
+
lexq history list | get | stats
|
|
212
|
+
lexq integrations list | get | save | delete | config-spec
|
|
213
|
+
lexq logs list | get | action | bulk-action
|
|
214
|
+
lexq webhook-subscriptions list | get | save | delete | test
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Global Options
|
|
218
|
+
|
|
219
|
+
| Flag | Description |
|
|
220
|
+
|--------------------------|--------------------------------------------|
|
|
221
|
+
| `--format <json\|table>` | Output format (default: `json`) |
|
|
222
|
+
| `--api-key <key>` | Override stored API key |
|
|
223
|
+
| `--base-url <url>` | Override API base URL |
|
|
224
|
+
| `--dry-run` | Preview the HTTP request without executing |
|
|
225
|
+
| `--verbose` | Show request/response details |
|
|
226
|
+
| `--no-color` | Disable colored output |
|
|
227
|
+
|
|
228
|
+
## Configuration
|
|
229
|
+
|
|
230
|
+
Config is stored at `~/.lexq/config.json`:
|
|
231
|
+
|
|
232
|
+
```json
|
|
233
|
+
{
|
|
234
|
+
"apiKey": "YOUR_API_KEY",
|
|
235
|
+
"baseUrl": "https://api.lexq.io/api/v1/partners",
|
|
236
|
+
"format": "json"
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
## Development
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
git clone https://github.com/lexq-io/lexq-cli.git
|
|
244
|
+
cd lexq-cli
|
|
245
|
+
pnpm install
|
|
246
|
+
pnpm build
|
|
247
|
+
pnpm start -- groups list
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
pnpm typecheck # Type check
|
|
252
|
+
pnpm lint # ESLint
|
|
253
|
+
bash tests/e2e.sh # CLI E2E tests (requires API key)
|
|
254
|
+
bash tests/test-engine-api.sh # Engine API integration tests
|
|
255
|
+
```
|
|
231
256
|
|
|
232
257
|
## License
|
|
233
258
|
|