@kelviq/mcp-server 1.1.0 → 1.2.0

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.
Files changed (40) hide show
  1. package/README.md +18 -8
  2. package/dist/docs/backend-integration/node-sdk.md +41 -17
  3. package/dist/docs/backend-integration/python-sdk.md +16 -17
  4. package/dist/docs/changelog.md +108 -0
  5. package/dist/docs/cli/commands.md +140 -5
  6. package/dist/docs/cli/environments.md +3 -3
  7. package/dist/docs/cli/kelviq-config.md +28 -7
  8. package/dist/docs/cli/overview.md +11 -9
  9. package/dist/docs/guides/agent-toolkit.md +3 -3
  10. package/dist/docs/guides/mcp-server.md +14 -6
  11. package/dist/docs/guides/webhooks.md +1 -1
  12. package/dist/docs/product-catalog/free-and-trials.md +13 -0
  13. package/dist/docs/product-catalog/license-keys.md +13 -0
  14. package/dist/http/client.d.ts +7 -0
  15. package/dist/http/client.js +9 -0
  16. package/dist/http/client.js.map +1 -1
  17. package/dist/prompts/index.js +11 -11
  18. package/dist/prompts/index.js.map +1 -1
  19. package/dist/schemas/kelviq.d.ts +1 -0
  20. package/dist/schemas/kelviq.js +6 -4
  21. package/dist/schemas/kelviq.js.map +1 -1
  22. package/dist/server.js +1 -0
  23. package/dist/server.js.map +1 -1
  24. package/dist/tools/_resolve.d.ts +4 -0
  25. package/dist/tools/_resolve.js +46 -0
  26. package/dist/tools/_resolve.js.map +1 -0
  27. package/dist/tools/connection.d.ts +12 -0
  28. package/dist/tools/connection.js +44 -0
  29. package/dist/tools/connection.js.map +1 -0
  30. package/dist/tools/discounts.js +14 -2
  31. package/dist/tools/discounts.js.map +1 -1
  32. package/dist/tools/index.js +3 -0
  33. package/dist/tools/index.js.map +1 -1
  34. package/dist/tools/offerings.js +6 -2
  35. package/dist/tools/offerings.js.map +1 -1
  36. package/dist/tools/plan-entitlements.js +11 -3
  37. package/dist/tools/plan-entitlements.js.map +1 -1
  38. package/dist/tools/plans.js +6 -2
  39. package/dist/tools/plans.js.map +1 -1
  40. package/package.json +1 -1
package/README.md CHANGED
@@ -13,7 +13,7 @@ capabilities at once:
13
13
  inside the package and exposed as MCP resources plus `docs_search` /
14
14
  `docs_read` tools, so the LLM can ground its answers in the canonical docs.
15
15
 
16
- > **56 tools** across **11 domains**, plus a resource for every docs page and
16
+ > **57 tools** across **12 domains**, plus a resource for every docs page and
17
17
  > the full OpenAPI spec. Works offline for docs Q&A — only API tools require a
18
18
  > key.
19
19
 
@@ -114,6 +114,14 @@ precedence over `KELVIQ_ENV`.
114
114
 
115
115
  ## Tools
116
116
 
117
+ Tools that take a product or feature reference (`plan_create`,
118
+ `plan_entitlements_add`, `discount_create`, `offering_get_product`) accept
119
+ either the UUID or the human-readable identifier; identifiers are resolved
120
+ through the retrieve endpoints before anything is written.
121
+
122
+ ### Connection
123
+ - `connection_check` — reports the environment (env, base/edge URLs) and whether the server key is accepted, without printing it
124
+
117
125
  ### Customers
118
126
  - `customer_create` — create a customer
119
127
  - `customer_update` — patch an existing customer
@@ -134,11 +142,11 @@ precedence over `KELVIQ_ENV`.
134
142
  - `usage_report` — report metered usage (`SET` or `DELTA`)
135
143
 
136
144
  ### Offerings & Promotions
137
- - `offering_get_product` — public pricing scoped to a product UUID
145
+ - `offering_get_product` — public pricing scoped to a product (UUID or identifier)
138
146
  - `promotion_get` — resolve the active promotion for the caller's location *(uses Client API key, edge host)*
139
147
 
140
148
  ### Discounts
141
- - `discount_list` / `discount_create` / `discount_retrieve` / `discount_archive`
149
+ - `discount_list` / `discount_create` (`appliesTo[].product` takes a UUID or identifier) / `discount_retrieve` / `discount_archive`
142
150
  - `discount_update` — enable or disable a code (nothing else can change after creation)
143
151
 
144
152
  ### Webhooks
@@ -154,11 +162,11 @@ precedence over `KELVIQ_ENV`.
154
162
  - `feature_list` / `feature_create` / `feature_retrieve` / `feature_archive`
155
163
 
156
164
  ### Catalog: Plans
157
- - `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
165
+ - `plan_list` / `plan_create` (`product` takes a UUID or identifier) / `plan_retrieve` / `plan_update` / `plan_archive`
158
166
  - `plan_publish` — release the latest draft, optionally migrate existing customers
159
167
  - `plan_discard_draft` — drop the current draft, keep the published version
160
168
  - `plan_prices_list` — per-currency pricing on a plan
161
- - `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
169
+ - `plan_entitlements_list` / `plan_entitlements_add` (`feature` takes a UUID or identifier) / `plan_entitlement_update` / `plan_entitlement_delete`
162
170
  - `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
163
171
 
164
172
  ### Docs (no API key required)
@@ -180,7 +188,7 @@ Once wired into your MCP client, try prompts like:
180
188
 
181
189
  - *"Search Kelviq docs for license keys"* → `docs_search` + `docs_read`
182
190
  - *"List my Kelviq products"* → `product_list`
183
- - *"Create a plan named 'Pro Monthly' under product UUID `…`, then publish it"* → `plan_create` → `plan_publish`
191
+ - *"Create a plan named 'Pro Monthly' under product `acme-app`, then publish it"* → `plan_create` → `plan_publish`
184
192
  - *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
185
193
  - *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
186
194
  - *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
@@ -197,7 +205,7 @@ npx -y @modelcontextprotocol/inspector \
197
205
  npx -y @kelviq/mcp-server@latest
198
206
  ```
199
207
 
200
- Opens a browser UI where you can browse all 56 tools, fill in arguments, and
208
+ Opens a browser UI where you can browse all 57 tools, fill in arguments, and
201
209
  run them against the real Kelviq API. Pre-fill env vars by exporting them
202
210
  before the command:
203
211
 
@@ -246,7 +254,9 @@ PATH. Either:
246
254
  ### Tool returns `{"error": {"status": "Configuration error", …}}`
247
255
 
248
256
  Means a required env var is missing. The error message names which one. Set
249
- it in your MCP client config and reconnect.
257
+ it in your MCP client config and reconnect. Ask the LLM to run
258
+ `connection_check` to see which environment the server is using and whether
259
+ the server key is accepted — it never prints the key.
250
260
 
251
261
  ### API tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
252
262
 
@@ -1506,25 +1506,38 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
1506
1506
 
1507
1507
  Use `express.raw()` (not `express.json()`) so that the raw request body is preserved for signature verification. Parsing the body as JSON before verification will break the signature check.
1508
1508
 
1509
+ On a framework built on the Fetch API — Next.js route handlers, Hono, Remix, SvelteKit, Cloudflare Workers — `request.headers` is a `Headers` object, not a plain object. Convert it with `Object.fromEntries`, and read the body with `request.text()` so it stays unparsed:
1510
+
1511
+ ```typescript
1512
+ import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';
1513
+
1514
+ export async function POST(request: Request) {
1515
+ const body = await request.text();
1516
+
1517
+ try {
1518
+ const event = validateEvent(
1519
+ body,
1520
+ Object.fromEntries(request.headers),
1521
+ process.env.KELVIQ_WEBHOOK_SECRET!,
1522
+ );
1523
+
1524
+ console.log('Event type:', event.type);
1525
+
1526
+ return new Response(null, { status: 202 });
1527
+ } catch (err) {
1528
+ if (err instanceof WebhookVerificationError) {
1529
+ return new Response(null, { status: 403 });
1530
+ }
1531
+ throw err;
1532
+ }
1533
+ }
1534
+ ```
1535
+
1536
+ Passing a `Headers` object straight to `validateEvent` fails with `Missing required webhook headers`, because the helper reads headers as plain object entries.
1537
+
1509
1538
  ### Webhook event types
1510
1539
 
1511
- | Event | Description |
1512
- |---|---|
1513
- | `checkout.completed` | A checkout session was completed |
1514
- | `customer.created` | A new customer was created |
1515
- | `customer.updated` | A customer's details were updated |
1516
- | `order.created` | A new order was placed |
1517
- | `order.updated` | An order was updated |
1518
- | `order.refunded` | An order was refunded |
1519
- | `subscription.created` | A new subscription was created |
1520
- | `subscription.updated` | A subscription was updated |
1521
- | `subscription.cancelled` | A subscription was cancelled |
1522
- | `subscription.plan_changed` | A subscription plan was changed |
1523
- | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1524
- | `invoice.created` | A new invoice was created |
1525
- | `invoice.paid` | An invoice was paid |
1526
- | `refund.created` | A refund was initiated |
1527
- | `refund.updated` | A refund status changed |
1540
+ See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
1528
1541
 
1529
1542
  ### Best practices
1530
1543
 
@@ -1547,4 +1560,15 @@ const client = new Kelviq({
1547
1560
 
1548
1561
  ```
1549
1562
 
1563
+ To pick the environment from the `KELVIQ_ENV` variable that the Kelviq CLI and MCP server also read, use `environmentFromEnv()`: it returns `'sandbox'` when `KELVIQ_ENV` is unset or empty, `'production'` or `'sandbox'` when it is set to one of those, and throws on any other value.
1564
+
1565
+ ```typescript
1566
+ import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';
1567
+
1568
+ const client = new Kelviq({
1569
+ accessToken: process.env.KELVIQ_SERVER_API_KEY!,
1570
+ environment: environmentFromEnv(), // reads KELVIQ_ENV: sandbox when unset
1571
+ });
1572
+ ```
1573
+
1550
1574
  The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.
@@ -1774,23 +1774,7 @@ Always pass the **raw** request body (e.g. `request.data` in Flask) to `validate
1774
1774
 
1775
1775
  ### Webhook event types
1776
1776
 
1777
- | Event | Description |
1778
- |---|---|
1779
- | `checkout.completed` | A checkout session was completed |
1780
- | `customer.created` | A new customer was created |
1781
- | `customer.updated` | A customer's details were updated |
1782
- | `order.created` | A new order was placed |
1783
- | `order.updated` | An order was updated |
1784
- | `order.refunded` | An order was refunded |
1785
- | `subscription.created` | A new subscription was created |
1786
- | `subscription.updated` | A subscription was updated |
1787
- | `subscription.cancelled` | A subscription was cancelled |
1788
- | `subscription.plan_changed` | A subscription plan was changed |
1789
- | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1790
- | `invoice.created` | A new invoice was created |
1791
- | `invoice.paid` | An invoice was paid |
1792
- | `refund.created` | A refund was initiated |
1793
- | `refund.updated` | A refund status changed |
1777
+ See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
1794
1778
 
1795
1779
  ### Best practices
1796
1780
 
@@ -1816,5 +1800,20 @@ client = Kelviq.create_sync_client(
1816
1800
  environment="sandbox"
1817
1801
  )
1818
1802
  ```
1803
+ ### Reading the environment from `KELVIQ_ENV`
1804
+
1805
+ `environment_from_env()` turns the `KELVIQ_ENV` convention shared with the Kelviq CLI and MCP server into the `environment` argument: `"sandbox"` when the variable is unset or empty, `"production"` or `"sandbox"` when it is set to one of those, and a `ValueError` naming any other value.
1806
+
1807
+ ```python
1808
+ import os
1809
+ from kelviq_sdk import Kelviq, environment_from_env
1810
+
1811
+ client = Kelviq.create_sync_client(
1812
+ access_token=os.environ["KELVIQ_SERVER_API_KEY"],
1813
+ environment=environment_from_env(), # reads KELVIQ_ENV: sandbox when unset
1814
+ )
1815
+ ```
1816
+
1817
+ `environment="production"` and `environment="prod"` mean the same thing.
1819
1818
 
1820
1819
  The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.
@@ -6,6 +6,114 @@ description: "Every Kelviq release across the dashboard, API, SDKs, and develope
6
6
  ---
7
7
  import { ChangelogFilter } from "/snippets/changelog-filter.jsx";
8
8
 
9
+ <Update label="v0.4.0" description="September 16, 2026" tags={["CLI"]}>
10
+
11
+ ### New Features
12
+
13
+ #### Env files, a live key check, and the live catalog
14
+
15
+ - Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory, so an app's env file is enough. A variable set in the shell always wins; `--env-file <path>` reads a specific file and `--no-env-file` reads none.
16
+ - `kelviq env --check` makes one authenticated read per configured key and reports `ok`, `rejected` or `error`, exiting non-zero when a key fails. Nothing from the key is printed.
17
+ - `kelviq status` shows the live catalog: products, features, and each plan's latest version with its price and entitlement counts, visibility and license-key state. `--json` for scripts.
18
+
19
+ #### Webhooks and discounts from the terminal
20
+
21
+ - `kelviq webhook add <url> --events … --write-secret .env.local` registers the app's endpoint, reusing one that already has the same URL, and writes the signing secret into the env file as `KELVIQ_WEBHOOK_SECRET` without printing it. `kelviq webhook list` shows endpoints with secrets hidden.
22
+ - `kelviq discount create` creates a code after restating it for confirmation, with `--product` taking the product's identifier. `kelviq discount list` lists codes.
23
+
24
+ #### Starter templates
25
+
26
+ `kelviq init --template saas|usage|license` writes a complete catalog that pushes as written: a SaaS product with free and Pro plans, a metered product with an included quantity and tiered overage, or a plan that issues license keys.
27
+
28
+ ### Improvements
29
+
30
+ - `kelviq push` compares prices only on the fields your config sets. Leaving out `freeTrial`, `taxBehavior`, or a charge's `paymentType` and `reset` no longer shows a difference on every run.
31
+ - `kelviq push` and `kelviq promote` stop before writing when a `METER` feature would be created without `featureDetails`, naming the feature and the fields to add.
32
+
33
+ </Update>
34
+
35
+ <Update label="v1.2.0" description="September 16, 2026" tags={["MCP Server"]}>
36
+
37
+ ### New Features
38
+
39
+ #### `connection_check`
40
+
41
+ A read-only tool that makes one authenticated read with the server key and reports the environment, both API hosts and whether the key is `ok`, `missing` or `rejected`, without ever including the key. Ask for it first when a tool returns 401 or 403.
42
+
43
+ ### Improvements
44
+
45
+ - `plan_create`, `plan_entitlements_add`, `discount_create`'s `appliesTo` and `offering_get_product` accept a product or feature **identifier** as well as a UUID. The server resolves the identifier before calling the API, so the assistant no longer has to look up UUIDs first.
46
+ - The bundled documentation is refreshed with every release, so `docs_search` and `docs_read` match the current docs.
47
+
48
+ </Update>
49
+
50
+ <Update label="v2.9.0" description="September 17, 2026" tags={["Python SDK"]}>
51
+
52
+ ### New Features
53
+
54
+ #### `environment_from_env()`
55
+
56
+ Resolves the client's `environment` argument from `KELVIQ_ENV`, the variable the CLI and MCP server share: `"sandbox"` when unset, `"production"` or `"sandbox"` when set to one of those, and a `ValueError` naming any other value.
57
+
58
+ ```python
59
+ from kelviq_sdk import Kelviq, environment_from_env
60
+
61
+ client = Kelviq.create_sync_client(
62
+ access_token=os.environ["KELVIQ_SERVER_API_KEY"],
63
+ environment=environment_from_env(),
64
+ )
65
+ ```
66
+
67
+ ### Improvements
68
+
69
+ - `environment="production"` is accepted alongside `"prod"`, so a value read straight from `KELVIQ_ENV` works.
70
+ - An environment name the SDK doesn't know now logs a warning. It still falls back to the production hosts.
71
+
72
+ </Update>
73
+
74
+ <Update label="v2.9.0" description="September 16, 2026" tags={["Node SDK"]}>
75
+
76
+ ### New Features
77
+
78
+ #### `environmentFromEnv()`
79
+
80
+ Turns the `KELVIQ_ENV` convention shared with the CLI and MCP server into a typed `environment` option: `sandbox` when unset, `production` or `sandbox` when set to one of those, and an error naming any other value.
81
+
82
+ ```typescript
83
+ import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';
84
+
85
+ const client = new Kelviq({
86
+ accessToken: process.env.KELVIQ_SERVER_API_KEY!,
87
+ environment: environmentFromEnv(),
88
+ });
89
+ ```
90
+
91
+ </Update>
92
+
93
+ <Update label="v0.3.1" description="September 16, 2026" tags={["CLI"]}>
94
+
95
+ ### Improvements
96
+
97
+ #### Cleaner `kelviq pull` output
98
+
99
+ A pulled `kelviq.config.ts` now writes charge prices the way you'd author them. A charge's `feature` is the feature's identifier:
100
+
101
+ ```typescript
102
+ chargeCatalogPrice: [
103
+ {
104
+ feature: 'seats',
105
+ priceModel: 'FLAT',
106
+ ...
107
+ },
108
+ ]
109
+ ```
110
+
111
+ Previously that field held the whole feature object the API returns — its UUID, timestamps and Stripe ids — and each charge carried its own server-generated ids. Those fields are now left out, so a pulled catalog is around 20% smaller, holds no UUIDs or Stripe ids, and reads as something you can edit by hand and review in a pull request.
112
+
113
+ Existing pulled files keep working: `kelviq push` accepts the identifier, the UUID and the embedded object alike.
114
+
115
+ </Update>
116
+
9
117
  <Update label="v1.1.0" description="September 16, 2026" tags={["MCP Server"]}>
10
118
 
11
119
  ### New Features
@@ -6,6 +6,13 @@ description: "Every Kelviq CLI command, flag by flag."
6
6
  ---
7
7
  All commands support `--help`. The CLI targets your **sandbox** environment unless you pass `--prod` — see [Environments & authentication](/cli/environments).
8
8
 
9
+ Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory before it runs, so a project's env file works without exporting anything. A variable already set in your shell always wins. Two global flags control this:
10
+
11
+ | Flag | Description |
12
+ |---|---|
13
+ | `--env-file <path>` | Read this dotenv file instead of `.env.local`/`.env`. Repeat it for several files; a missing file is an error. |
14
+ | `--no-env-file` | Don't read any env file. |
15
+
9
16
  Output is colorized on interactive terminals (green creates, yellow updates, red archives) and automatically plain when piped. Disable colors explicitly with the global `--no-color` flag or the `NO_COLOR` environment variable.
10
17
 
11
18
  ---
@@ -15,17 +22,24 @@ Output is colorized on interactive terminals (green creates, yellow updates, red
15
22
  Writes a starter `kelviq.config.ts` to the current directory.
16
23
 
17
24
  ```shell
18
- kelviq init
25
+ kelviq init # the saas template
26
+ kelviq init --template usage # metered usage with an overage price
27
+ kelviq init --template license # a plan that issues license keys
19
28
  kelviq init -o pricing/kelviq.config.ts
20
29
  kelviq init --force
21
30
  ```
22
31
 
23
32
  | Flag | Description |
24
33
  |---|---|
34
+ | `--template <name>` | Which starter catalog to write: `saas` (default), `usage`, or `license`. |
25
35
  | `-o, --output <path>` | Where to write the file. Defaults to `kelviq.config.ts` in the current directory. |
26
36
  | `--force` | Overwrite the file if it already exists. Without it, `init` refuses rather than clobbering your edits. |
27
37
 
28
- The starter file defines one product, one feature, and one plan using the typed builders from `@kelviq/cli/config` — see the [format reference](/cli/kelviq-config).
38
+ Each template is a complete catalog that `kelviq push` accepts as written, using the typed builders from `@kelviq/cli/config` — see the [format reference](/cli/kelviq-config):
39
+
40
+ - **`saas`** — a product with a free plan and a Pro plan billed monthly or yearly, gating a boolean feature and a configurable limit.
41
+ - **`usage`** — a `METER` feature with the details the API requires, a free plan with a hard monthly allowance, and a Pro plan with an included quantity plus a tiered pay-as-you-go overage price.
42
+ - **`license`** — a Pro plan whose orders issue license keys valid on up to three devices.
29
43
 
30
44
  ---
31
45
 
@@ -79,22 +93,37 @@ Removing a key locally does not revoke it. To revoke a key, delete it from the [
79
93
 
80
94
  ## kelviq env
81
95
 
82
- Shows which environment and keys the CLI is configured with. Read-only — it never calls the API.
96
+ Shows which environment and keys the CLI is configured with, and which env files it read.
83
97
 
84
98
  ```shell
85
99
  kelviq env
100
+ kelviq env --check
86
101
  ```
87
102
 
88
103
  ```text
89
104
  Environment : sandbox (default — use --prod to target production)
105
+ KELVIQ_ENV : unset (sandbox) — unprefixed KELVIQ_* vars apply to sandbox
90
106
  Sandbox URL : https://sandboxapi.kelviq.com/api/v1
91
107
  Prod URL : https://api.kelviq.com/api/v1
92
108
  Sandbox key : set
93
109
  Prod key : missing
94
110
  Org : unknown — Kelviq has no key-introspection endpoint yet
111
+ Env files : /path/to/app/.env.local (KELVIQ_SERVER_API_KEY, KELVIQ_ENV)
95
112
  ```
96
113
 
97
- Key rows show `set` or `missing` only — `env` reports what's configured locally and does not validate keys against the API. `kelviq env --json` emits the same report as JSON (never any part of a key's value).
114
+ | Flag | Description |
115
+ |---|---|
116
+ | `--check` | Make one authenticated read per configured key and report whether the API accepted it. |
117
+ | `--json` | Machine-readable output. Never includes any part of a key's value. |
118
+
119
+ Without `--check`, key rows show `set` or `missing` only and nothing is sent to the API. With `--check`, each configured key gets one `GET /catalog/products/` call against its own environment's host and a result line:
120
+
121
+ ```text
122
+ Sandbox check : ok
123
+ Prod check : skipped (no key configured)
124
+ ```
125
+
126
+ `ok` means the key was accepted. `rejected` (HTTP 401 or 403) almost always means the key belongs to the other environment. The command exits non-zero when any configured key fails, or when no key is configured, so a script or agent can gate on it. `--check --json` adds `sandboxCheck` and `prodCheck` objects (`{ ok, status, httpStatus?, message? }`) to the JSON document.
98
127
 
99
128
  ---
100
129
 
@@ -173,7 +202,11 @@ Push stamps a `managed-by: kelviq-cli` entry into the `metadata` of every featur
173
202
 
174
203
  A plan **with** a `prices` array in config always pushes that complete array, replacing the plan's entire remote price set. A plan **without** a `prices` key never touches remote prices at all. Omitting `prices` means "leave pricing alone," not "this plan is free."
175
204
 
176
- If you hand-author prices, set `freeTrial`, `trialPeriod`, `enabled`, and `taxBehavior` explicitly. Omitting them makes your price compare unequal to the server's stored defaults forever, so every push re-replaces that plan's prices (harmless but noisy — each one drafts the plan again). Configs generated by `kelviq pull` don't have this problem.
205
+ Prices are compared on the fields your config sets. A field you omit — `freeTrial`, `taxBehavior`, a charge's `paymentType` or `reset` — is left to the server's default and never counts as a difference, so a hand-authored price diffs clean after its first push.
206
+
207
+ ### METER features are checked before anything is written
208
+
209
+ The API rejects a `METER` feature created without `featureDetails` (`featureSubType` and `units`). Push checks for this while building the plan and stops before any write, naming the feature and the shape to add — see [feature()](/cli/kelviq-config#feature).
177
210
 
178
211
  ### Features can't be updated — by design
179
212
 
@@ -223,3 +256,105 @@ kelviq promote # then do it
223
256
  ```
224
257
 
225
258
  Promotion is one-way — sandbox to production. There is no reverse mode.
259
+
260
+ ---
261
+
262
+ ## kelviq status
263
+
264
+ Shows the live catalog of an environment without writing a config file: products, features, and the latest version of every plan with its price and entitlement counts. Read-only — the check to run after a push to confirm what landed.
265
+
266
+ ```shell
267
+ kelviq status
268
+ kelviq status --prod
269
+ kelviq status --json
270
+ ```
271
+
272
+ ```text
273
+ Environment : sandbox
274
+
275
+ Products (1)
276
+ my-app My App
277
+
278
+ Features (2)
279
+ api-calls METER API calls
280
+ history-retention CUSTOMIZABLE History retention (days)
281
+
282
+ Plans (2)
283
+ free Free product my-app · v1 · 1 price · 1 entitlement · visible
284
+ pro Pro product my-app · v2 · 1 price · 2 entitlements · visible · license keys
285
+ ```
286
+
287
+ | Flag | Description |
288
+ |---|---|
289
+ | `--prod` | Read production instead of sandbox. |
290
+ | `--json` | Emit `{ environment, products, features, plans }`, each plan as `{ identifier, name, product, version, isLatest, isVisible, prices, entitlements, licenseKeys }`. |
291
+
292
+ A plan with no prices is flagged, since it can't be bought. The API reports a plan's version number rather than a draft/published state, so that's what `status` shows.
293
+
294
+ ---
295
+
296
+ ## kelviq webhook
297
+
298
+ Registers the app's webhook endpoint and gets the signing secret into the app's env file without it ever appearing on screen.
299
+
300
+ ```shell
301
+ kelviq webhook list
302
+ kelviq webhook add https://app.example.com/api/kelviq/webhooks \
303
+ --events checkout.completed,subscription.created,subscription.updated,subscription.cancelled,invoice.payment_failed \
304
+ --write-secret .env.local
305
+ ```
306
+
307
+ ### kelviq webhook add
308
+
309
+ | Flag | Description |
310
+ |---|---|
311
+ | `<url>` | The public https URL that receives events. Localhost and private addresses are rejected by the API. |
312
+ | `--events <list>` | Comma-separated event types — see the [event list](/guides/webhooks#event-types). Required. |
313
+ | `--write-secret <file>` | Write the signing secret into this dotenv file, replacing or appending a `KELVIQ_WEBHOOK_SECRET=` line. The value is never printed. |
314
+ | `--variable <name>` | Variable name to write instead of `KELVIQ_WEBHOOK_SECRET`. |
315
+ | `--print-secret` | Print the secret to stdout instead. Off by default. |
316
+ | `--prod` | Target production instead of sandbox. |
317
+ | `--yes` | Skip the confirmation prompt (required in non-interactive sessions). |
318
+ | `--json` | Machine-readable output. The endpoint's `secret` is always `[hidden]` unless `--print-secret` is passed. |
319
+
320
+ `add` is idempotent on the URL: an endpoint that already exists for the same URL is reused instead of registered twice, and its events are extended when the ones you pass aren't all covered. With neither `--write-secret` nor `--print-secret`, the secret stays hidden and the output tells you how to get it.
321
+
322
+ ### kelviq webhook list
323
+
324
+ Lists endpoints with their URL, state, id and events. Secrets are never shown. `--prod` and `--json` as above.
325
+
326
+ ---
327
+
328
+ ## kelviq discount
329
+
330
+ Creates and lists discount codes. Only enabling or disabling a code can change after creation, so `create` restates everything and asks before writing.
331
+
332
+ ```shell
333
+ kelviq discount list
334
+ kelviq discount create --name "Launch offer" --code LAUNCH20 --percent 20 \
335
+ --duration repeating --months 3 --product my-app --plans pro-monthly
336
+ kelviq discount create --name "Ten off" --code TENOFF --amount 10 --currency USD
337
+ ```
338
+
339
+ ### kelviq discount create
340
+
341
+ | Flag | Description |
342
+ |---|---|
343
+ | `--name <text>` | Shown on the customer's invoice. Required. |
344
+ | `--code <CODE>` | What customers enter at checkout: uppercase letters and digits. Required. |
345
+ | `--percent <n>` | Percentage off, 1–100. Exactly one of `--percent` or `--amount`. |
346
+ | `--amount <x>` | Fixed amount off in normal currency units; needs `--currency`. |
347
+ | `--currency <code>` | ISO currency code for `--amount`. |
348
+ | `--duration <once\|repeating\|forever>` | How long the discount applies. Default `once`. |
349
+ | `--months <n>` | With `--duration repeating`: how many **billing periods** it applies for. Not calendar months — `3` on a yearly plan is three years, so scope a "first 3 months" code to monthly plans. |
350
+ | `--product <identifier>` | Limit the code to one product, by identifier or UUID. The CLI resolves the identifier to the UUID the API wants. |
351
+ | `--plans <list>` | With `--product`: comma-separated plan identifiers. Omit to cover every plan of the product. |
352
+ | `--max-redemptions <n>` | Total number of uses across all customers. |
353
+ | `--redeem-by <datetime>` | ISO 8601 date/time after which the code stops working. |
354
+ | `--prod` / `--yes` / `--json` | As for `webhook add`. |
355
+
356
+ Discount codes need a Merchant of Record organization.
357
+
358
+ ### kelviq discount list
359
+
360
+ Lists codes with amount, duration and state. `--search <text>` filters by name or code; `--prod` and `--json` as above.
@@ -53,7 +53,7 @@ Server API Keys have full API access. Never expose them in client-side code, com
53
53
 
54
54
  ## Environment variables
55
55
 
56
- Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
56
+ Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. They can come from the shell or from the project's env file: before every command, the CLI reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory, never overriding a variable the shell already sets. Pass `--env-file <path>` to read a specific file instead, or `--no-env-file` to read none. `kelviq env` lists the files it read. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
57
57
 
58
58
  | Variable | Purpose |
59
59
  |---|---|
@@ -88,7 +88,7 @@ If a command needs a key and finds none — neither in the environment nor store
88
88
 
89
89
  ## Checking your setup
90
90
 
91
- `kelviq env` prints the full picture without calling the API:
91
+ `kelviq env` prints the full picture without calling the API, and `kelviq env --check` adds one authenticated read per configured key:
92
92
 
93
93
  ```text
94
94
  Environment : sandbox (default — use --prod to target production)
@@ -100,4 +100,4 @@ Prod key : missing
100
100
  Org : unknown — Kelviq has no key-introspection endpoint yet
101
101
  ```
102
102
 
103
- `set` means a key is configured (stored or via environment variable) — not that it's valid. Kelviq has no key-introspection endpoint yet, so the CLI can't verify a key or display your organization name; an invalid key surfaces on the first real API call, such as `kelviq pull`.
103
+ `set` means a key is configured (stored, from an env file, or from the shell) — not that it's valid. `kelviq env --check` verifies each key with one read against its own environment and exits non-zero if any configured key is rejected. Kelviq has no key-introspection endpoint yet, so the CLI can't display your organization name.
@@ -23,11 +23,15 @@ export const apiCalls = feature({
23
23
  identifier: 'api-calls',
24
24
  name: 'API calls',
25
25
  type: 'METER',
26
+ featureDetails: {
27
+ featureSubType: 'PRE_AGGREGATED_USAGE',
28
+ units: { singular: 'call', plural: 'calls' },
29
+ },
26
30
  });
27
31
 
28
- export const seats = feature({
29
- identifier: 'seats',
30
- name: 'Seats',
32
+ export const historyRetention = feature({
33
+ identifier: 'history-retention',
34
+ name: 'History retention (days)',
31
35
  type: 'CUSTOMIZABLE',
32
36
  });
33
37
 
@@ -36,13 +40,29 @@ export const pro = plan({
36
40
  name: 'Pro',
37
41
  product: 'my-app',
38
42
  entitlements: [
39
- { feature: 'seats', value: 5 },
43
+ { feature: 'history-retention', value: 30 },
40
44
  { feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
41
45
  ],
42
46
  prices: [
43
47
  {
44
48
  priceType: 'PAID',
45
49
  currency: 'USD',
50
+ freeTrial: false,
51
+ trialPeriod: 0,
52
+ enabled: true,
53
+ taxBehavior: 'EXCLUSIVE',
54
+ chargeCatalogPrice: [
55
+ {
56
+ feature: null,
57
+ priceModel: 'FLAT',
58
+ paymentType: 'ADVANCE_COMMITMENT',
59
+ reset: 'NEVER',
60
+ charges: [
61
+ { chargePeriod: 'MONTHLY', priceData: { amount: 29 } },
62
+ { chargePeriod: 'YEARLY', priceData: { amount: 290 } },
63
+ ],
64
+ },
65
+ ],
46
66
  },
47
67
  ],
48
68
  });
@@ -81,9 +101,9 @@ The plan lifecycle (draft → published) is also deliberately absent: the config
81
101
  |---|---|---|---|
82
102
  | `identifier` | slug | yes | Stable identifier, referenced from plan entitlements. |
83
103
  | `name` | string | yes | Display name. |
84
- | `type` | enum | yes | `BOOLEAN` (on/off), `CUSTOMIZABLE` (a configurable limit), or `METER` (usage-tracked). |
104
+ | `type` | enum | yes | `BOOLEAN` (on/off), `CUSTOMIZABLE` (a setting the plan configures, such as days of history retention), or `METER` (a counted quantity — usage that resets, or seats a customer buys). Seats are a `METER`, not `CUSTOMIZABLE`: only a meter can carry a per-unit price and take a quantity at checkout — see [seat-based pricing](/product-catalog/seat-based-pricing). |
85
105
  | `description` | string | no | Free-text description. |
86
- | `featureDetails` | object | no | Type-specific detail payload, passed through to the API. |
106
+ | `featureDetails` | object | for `METER` | Type-specific detail payload, passed through to the API. A `METER` feature needs `featureSubType` (`PRE_AGGREGATED_USAGE`) and `units` (`{ singular, plural }`): `kelviq push` refuses to create one without them, before writing anything, because the API rejects it. See [Create a feature](/product-catalog/create-a-feature). |
87
107
  | `meter` | object | no | Meter configuration for `METER` features, passed through to the API. |
88
108
  | `metadata` | object | no | Arbitrary key-value metadata. |
89
109
 
@@ -164,9 +184,10 @@ The price envelope is validated; the charge structures inside it are deliberatel
164
184
  | `freeTrial` | boolean | no | Whether the price includes a free trial. |
165
185
  | `trialPeriod` | number | no | Trial length in days. |
166
186
  | `taxBehavior` | enum | no | `INCLUSIVE`, `EXCLUSIVE`, or `UNSPECIFIED`. |
187
+ | `enabled` | boolean | no | Whether the price is available for purchase. |
167
188
  | `chargeCatalogPrice` | array of objects | no | The full charge structure (price models, tiers, billing periods). Passed through verbatim — see the plan-prices endpoints in the [API Reference](/api-reference/introduction) for the shape. |
168
189
 
169
- A pulled config reproduces your remote prices in full, including nested charge structures. You rarely need to author `chargeCatalogPrice` by hand — pull an existing plan and adapt it. If you do author prices by hand, set `freeTrial`, `trialPeriod`, `enabled`, and `taxBehavior` explicitly — omitting them makes `kelviq push` see a difference against the server's stored defaults on every run (see the [push reference](/cli/commands#kelviq-push)).
190
+ A pulled config reproduces your remote prices in full, including nested charge structures. To author one by hand, start from `kelviq init --template saas|usage|license` or pull an existing plan and adapt it. Fields you leave out — `freeTrial`, `taxBehavior`, a charge's `paymentType` or `reset` — take the server's defaults, and `kelviq push` compares prices only on the fields you set, so leaving them out never shows up as a change.
170
191
 
171
192
  ---
172
193