@kelviq/mcp-server 0.2.3 → 0.4.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 (72) hide show
  1. package/README.md +26 -23
  2. package/dist/config.d.ts +9 -1
  3. package/dist/config.js +38 -7
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/mcp-server.md +61 -0
  12. package/dist/docs/changelog/node-sdk.md +153 -0
  13. package/dist/docs/changelog/python-sdk.md +182 -0
  14. package/dist/docs/cli/commands.md +225 -0
  15. package/dist/docs/cli/environments.md +95 -0
  16. package/dist/docs/cli/kelviq-config.md +141 -0
  17. package/dist/docs/cli/overview.md +223 -0
  18. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  19. package/dist/docs/guides/mcp-server.md +141 -194
  20. package/dist/docs/guides/sandbox.md +107 -0
  21. package/dist/docs/guides/webhooks.md +81 -0
  22. package/dist/docs/manifest.json +64 -8
  23. package/dist/docs/openapi.json +1206 -50
  24. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  25. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  26. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  27. package/dist/prompts/index.d.ts +2 -0
  28. package/dist/prompts/index.js +107 -0
  29. package/dist/prompts/index.js.map +1 -0
  30. package/dist/schemas/kelviq.d.ts +30 -128
  31. package/dist/schemas/kelviq.js +50 -63
  32. package/dist/schemas/kelviq.js.map +1 -1
  33. package/dist/server.js +5 -2
  34. package/dist/server.js.map +1 -1
  35. package/dist/tools/checkout.js +2 -1
  36. package/dist/tools/checkout.js.map +1 -1
  37. package/dist/tools/customers.js +2 -0
  38. package/dist/tools/customers.js.map +1 -1
  39. package/dist/tools/docs.js +2 -0
  40. package/dist/tools/docs.js.map +1 -1
  41. package/dist/tools/entitlements.js +1 -0
  42. package/dist/tools/entitlements.js.map +1 -1
  43. package/dist/tools/features.js +4 -0
  44. package/dist/tools/features.js.map +1 -1
  45. package/dist/tools/index.js +0 -4
  46. package/dist/tools/index.js.map +1 -1
  47. package/dist/tools/licenses.js +3 -0
  48. package/dist/tools/licenses.js.map +1 -1
  49. package/dist/tools/offerings.js +1 -0
  50. package/dist/tools/offerings.js.map +1 -1
  51. package/dist/tools/plan-entitlements.js +4 -0
  52. package/dist/tools/plan-entitlements.js.map +1 -1
  53. package/dist/tools/plan-files.js +4 -1
  54. package/dist/tools/plan-files.js.map +1 -1
  55. package/dist/tools/plans.js +9 -15
  56. package/dist/tools/plans.js.map +1 -1
  57. package/dist/tools/portal.d.ts +11 -1
  58. package/dist/tools/portal.js +28 -2
  59. package/dist/tools/portal.js.map +1 -1
  60. package/dist/tools/product-files.js +2 -0
  61. package/dist/tools/product-files.js.map +1 -1
  62. package/dist/tools/product-settings.js +2 -0
  63. package/dist/tools/product-settings.js.map +1 -1
  64. package/dist/tools/products.js +6 -1
  65. package/dist/tools/products.js.map +1 -1
  66. package/dist/tools/promotions.js +1 -0
  67. package/dist/tools/promotions.js.map +1 -1
  68. package/dist/tools/subscriptions.js +6 -2
  69. package/dist/tools/subscriptions.js.map +1 -1
  70. package/dist/tools/usage.js +1 -0
  71. package/dist/tools/usage.js.map +1 -1
  72. package/package.json +5 -2
@@ -0,0 +1,61 @@
1
+ ---
2
+ title: "MCP Server"
3
+ slug: "changelog/mcp-server"
4
+ section: "changelog"
5
+ description: "Changelog for @kelviq/mcp-server"
6
+ ---
7
+ <Update label="v0.4.0" description="July 24, 2026">
8
+
9
+ ### New Features
10
+
11
+ #### Full checkout surface
12
+
13
+ `checkout_create_session` now accepts every field the API supports — including `customAmount` (with `taxBehavior` and `currencyCode`) for custom-priced sessions, `discountCode` to pre-apply a coupon, `metadata` (returned verbatim on the `checkout.completed` webhook), `discountsEnabled`, `lockEmail`, and `defaultBillingCountry`. Previously these were silently dropped before the request was sent.
14
+
15
+ #### Subscription update options
16
+
17
+ `subscription_update` now supports `trialEnd` (`"now"` or an ISO 8601 datetime) and `paymentBehavior: "activate_on_payment"` to keep the current subscription active until payment for the update succeeds.
18
+
19
+ #### Safety annotations on every tool
20
+
21
+ All 45 tools now declare [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) — `readOnlyHint`, `destructiveHint`, `idempotentHint` — so MCP clients can auto-approve reads while asking for confirmation on destructive operations like `plan_archive` or `subscription_cancel`.
22
+
23
+ #### Guided prompts
24
+
25
+ Three built-in MCP prompts encode the golden-path workflows: `setup_product` (catalog bootstrap end-to-end), `launch_plan` (add a plan to an existing product), and `diagnose_customer` (entitlement/subscription cross-check). In Claude Code they appear as slash commands, e.g. `/kelviq:setup_product`.
26
+
27
+ ### Fixes
28
+
29
+ - The server now reports its real version to MCP clients (it was pinned to an old value).
30
+ - An automated spec-conformance suite now guards every request schema against the OpenAPI spec, so new API fields can no longer be silently dropped.
31
+
32
+ </Update>
33
+
34
+ <Update label="v0.3.0" description="July 24, 2026">
35
+
36
+ ### New Features
37
+
38
+ #### Sandbox environment support
39
+
40
+ Set `KELVIQ_ENV=sandbox` to target your sandbox environment — the server switches both API hosts (`sandboxapi.kelviq.com` and `edge.sandboxapi.kelviq.com`) automatically. Keys only work against their own environment, and an invalid `KELVIQ_ENV` value fails fast at startup instead of silently hitting production.
41
+
42
+ #### Signed portal links
43
+
44
+ `portal_session_create` now returns a ready-to-share `signedPortalUrl` — the portal URL with the session token already appended. The bare `customerPortalUrl` does not authenticate on its own; always share the signed link.
45
+
46
+ ### Breaking Changes
47
+
48
+ Six tools were removed: `media_presigned_upload`, the four `partner_org_*` tools, and `plan_prices_bulk_set`. Plan pricing is managed in the dashboard or with the [Kelviq CLI](/cli/overview) (`kelviq push`), which previews and confirms every price change; `plan_prices_list` (read) remains available.
49
+
50
+ ### Improvements
51
+
52
+ - `subscription_create` now documents that it requires off-session charging to be enabled for your organization, with `checkout_create_session` as the fallback.
53
+ - The missing-key error links directly to the API-keys page in the right dashboard mode for your environment.
54
+
55
+ </Update>
56
+
57
+ <Update label="v0.2.0 – v0.2.3" description="June 16–17, 2026">
58
+
59
+ Initial public release of `@kelviq/mcp-server`: the full Kelviq API as typed MCP tools plus the entire documentation as searchable resources, followed by packaging fixes and consolidation onto a single edge host.
60
+
61
+ </Update>
@@ -4,6 +4,159 @@ slug: "changelog/node-sdk"
4
4
  section: "changelog"
5
5
  description: "Changelog for @kelviq/node-sdk"
6
6
  ---
7
+ <Update label="v2.7.3" description="July 21, 2026">
8
+
9
+ ### New Features
10
+
11
+ #### Activate Subscription Updates After Payment
12
+
13
+ `client.subscriptions.update()` now supports `paymentBehavior`. Use the exported `PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT` constant to keep the current subscription active until payment for the update succeeds.
14
+
15
+ ```typescript
16
+ import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS } from "@kelviq/node-sdk";
17
+
18
+ const subscription = await client.subscriptions.update({
19
+ subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
20
+ planIdentifier: "premium-plan",
21
+ chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
22
+ paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT,
23
+ });
24
+ ```
25
+
26
+ The SDK serializes the option as `payment_behavior: "activate_on_payment"`. If payment is not completed and the pending update expires, the existing subscription remains active and unchanged.
27
+
28
+ </Update>
29
+
30
+ <Update label="v2.7.2" description="July 14, 2026">
31
+
32
+ ### New Features
33
+
34
+ #### List, Retrieve, and Create Subscriptions
35
+
36
+ The subscriptions module now supports the complete read and create workflow:
37
+
38
+ - `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
39
+ - `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
40
+ - `client.subscriptions.create()` creates a subscription directly for a customer.
41
+
42
+ ```typescript
43
+ const page = await client.subscriptions.list({
44
+ customerId: "cust_789",
45
+ page: 1,
46
+ pageSize: 20,
47
+ });
48
+
49
+ const subscription = await client.subscriptions.retrieve({
50
+ subscriptionId: page.results[0].id,
51
+ });
52
+
53
+ const created = await client.subscriptions.create({
54
+ planIdentifier: "plan-pro-monthly",
55
+ chargePeriod: "MONTHLY",
56
+ customerId: "cust_789",
57
+ });
58
+ ```
59
+
60
+ New TypeScript models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
61
+
62
+ </Update>
63
+
64
+ <Update label="v2.7.0-beta.2" description="July 10, 2026">
65
+
66
+ ### New Features
67
+
68
+ #### Create One-Time Charges
69
+
70
+ A new `client.charges.create()` method can immediately charge a customer's saved payment method without creating a checkout session.
71
+
72
+ ```typescript
73
+ const charge = await client.charges.create({
74
+ planIdentifier: "lifetime-access",
75
+ chargePeriod: "ONE_TIME",
76
+ customerId: "cust_789",
77
+ currencyCode: "USD",
78
+ features: [{ identifier: "seats", quantity: 5 }],
79
+ ipAddress: "103.154.35.20",
80
+ });
81
+
82
+ console.log(charge.id, charge.status, charge.amount);
83
+ ```
84
+
85
+ The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. The SDK includes typed request and response models for charge records.
86
+
87
+ </Update>
88
+
89
+ <Update label="v2.7.0" description="July 4, 2026">
90
+
91
+ ### New Features
92
+
93
+ #### Caching & Offline Resilience
94
+
95
+ The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
96
+
97
+ - **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
98
+ - **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes and containers, and survive restarts.
99
+
100
+ Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
101
+
102
+ ```typescript
103
+ const client = new Kelviq({
104
+ accessToken: process.env.KELVIQ_API_KEY,
105
+ enableCache: true, // default true
106
+ cacheTtlMs: 60_000, // freshness window in ms (default 60000)
107
+ });
108
+ ```
109
+
110
+ Set `enableCache: false` to disable caching entirely.
111
+
112
+ #### Offline Usage Queue
113
+
114
+ Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
115
+
116
+ ```typescript
117
+ const remaining = await client.reporting.flush(); // returns count still queued
118
+ ```
119
+
120
+ #### Distributed Cache — `RedisStore`
121
+
122
+ A ready-to-use `RedisStore` (backed by `ioredis`, an optional dependency) can be shared across multiple instances / containers so they use one cache and one durable usage queue.
123
+
124
+ ```typescript
125
+ import { Kelviq, RedisStore } from '@kelviq/node-sdk';
126
+
127
+ const store = new RedisStore({ url: 'redis://localhost:6379/0', prefix: 'kelviq:prod' });
128
+ const client = new Kelviq({ accessToken: process.env.KELVIQ_API_KEY, cacheStore: store });
129
+ ```
130
+
131
+ You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cacheStore`. All instances that should share a cache must use the same `prefix`.
132
+
133
+ </Update>
134
+
135
+ <Update label="v2.6.0" description="June 5, 2026">
136
+
137
+ ### New Features
138
+
139
+ #### Checkout Session — `metadata` Parameter
140
+
141
+ `CreateCheckoutSessionPayload` now accepts an optional `metadata` field for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
142
+
143
+ ```typescript
144
+ const response = await client.checkout.createSession({
145
+ planIdentifier: "plan-pro-monthly",
146
+ chargePeriod: "MONTHLY",
147
+ customerId: "cust_789",
148
+ successUrl: "https://example.com/success",
149
+ metadata: {
150
+ orderId: "order_12345",
151
+ referralCode: "SUMMER2026",
152
+ },
153
+ });
154
+ ```
155
+
156
+ Unlike other payload fields, the **keys inside `metadata` are preserved exactly as provided** — they are not converted to snake_case on the way to the API, so they survive the round-trip back through webhooks unchanged.
157
+
158
+ </Update>
159
+
7
160
  <Update label="v2.5.0" description="May 10, 2026">
8
161
 
9
162
  ### New Features
@@ -4,6 +4,188 @@ slug: "changelog/python-sdk"
4
4
  section: "changelog"
5
5
  description: "Changelog for kelviq-sdk (Python)"
6
6
  ---
7
+ <Update label="v2.7.3" description="July 21, 2026">
8
+
9
+ ### New Features
10
+
11
+ #### Activate Subscription Updates After Payment
12
+
13
+ The synchronous and asynchronous `client.subscriptions.update()` methods now support `paymentBehavior="activate_on_payment"`. This keeps the current subscription active while payment for the update is pending.
14
+
15
+ ```python
16
+ subscription = client.subscriptions.update(
17
+ subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
18
+ planIdentifier="premium-plan",
19
+ chargePeriod="MONTHLY",
20
+ paymentBehavior="activate_on_payment",
21
+ )
22
+ ```
23
+
24
+ The SDK validates the option and serializes it as `payment_behavior`. The new plan and features are applied only after payment succeeds; if the pending update expires, the existing subscription remains active and unchanged.
25
+
26
+ </Update>
27
+
28
+ <Update label="v2.7.2" description="July 14, 2026">
29
+
30
+ ### New Features
31
+
32
+ #### List, Retrieve, and Create Subscriptions
33
+
34
+ The synchronous and asynchronous subscription clients now support the complete read and create workflow:
35
+
36
+ - `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
37
+ - `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
38
+ - `client.subscriptions.create()` creates a subscription directly for a customer.
39
+
40
+ ```python
41
+ page = client.subscriptions.list(
42
+ customerId="cust_789",
43
+ page=1,
44
+ page_size=20,
45
+ )
46
+
47
+ subscription = client.subscriptions.retrieve(
48
+ subscriptionId=page.results[0].id,
49
+ )
50
+
51
+ created = client.subscriptions.create(
52
+ planIdentifier="plan-pro-monthly",
53
+ chargePeriod="MONTHLY",
54
+ customerId="cust_789",
55
+ )
56
+ ```
57
+
58
+ All three methods are also available on `async_client` and return validated Pydantic models. New models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
59
+
60
+ </Update>
61
+
62
+ <Update label="v2.7.1" description="July 10, 2026">
63
+
64
+ ### New Features
65
+
66
+ #### Create One-Time Charges
67
+
68
+ The synchronous and asynchronous clients now provide `client.charges.create()` for immediately charging a customer's saved payment method without creating a checkout session.
69
+
70
+ ```python
71
+ charge = client.charges.create(
72
+ planIdentifier="lifetime-access",
73
+ chargePeriod="ONE_TIME",
74
+ customerId="cust_789",
75
+ currencyCode="USD",
76
+ features=[{"identifier": "seats", "quantity": 5}],
77
+ ipAddress="103.154.35.20",
78
+ )
79
+
80
+ print(charge.id, charge.status, charge.amount)
81
+ ```
82
+
83
+ **Async variant:**
84
+
85
+ ```python
86
+ charge = await async_client.charges.create(
87
+ planIdentifier="lifetime-access",
88
+ chargePeriod="ONE_TIME",
89
+ customerId="cust_789",
90
+ )
91
+ ```
92
+
93
+ The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. Pydantic request and response models validate parameters and provide typed charge records.
94
+
95
+ </Update>
96
+
97
+ <Update label="v2.7.0" description="July 4, 2026">
98
+
99
+ ### New Features
100
+
101
+ #### Caching & Offline Resilience
102
+
103
+ The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
104
+
105
+ - **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
106
+ - **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes / gunicorn workers / containers, and survive restarts.
107
+
108
+ Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
109
+
110
+ ```python
111
+ client = Kelviq.create_sync_client(
112
+ access_token=ACCESS_TOKEN,
113
+ enable_cache=True, # default True
114
+ cache_ttl=60.0, # freshness window in seconds (default 60)
115
+ )
116
+ ```
117
+
118
+ Set `enable_cache=False` to disable caching entirely. Both the sync and async clients are supported.
119
+
120
+ #### Offline Usage Queue
121
+
122
+ Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
123
+
124
+ ```python
125
+ remaining = client.reporting.flush() # returns count still queued
126
+ # async: remaining = await async_client.reporting.flush()
127
+ ```
128
+
129
+ #### Distributed Cache — `RedisStore` / `AsyncRedisStore`
130
+
131
+ Ready-to-use Redis-backed stores can be shared across multiple processes / gunicorn workers / containers so they use one cache and one durable usage queue. Redis is an optional extra (`pip install "kelviq-sdk[redis]"`).
132
+
133
+ ```python
134
+ from kelviq_sdk import Kelviq, RedisStore
135
+
136
+ store = RedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
137
+ client = Kelviq.create_sync_client(access_token=ACCESS_TOKEN, cache_store=store)
138
+ ```
139
+
140
+ ```python
141
+ # Async
142
+ from kelviq_sdk import Kelviq, AsyncRedisStore
143
+
144
+ store = AsyncRedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
145
+ async_client = Kelviq.create_async_client(access_token=ACCESS_TOKEN, cache_store=store)
146
+ ```
147
+
148
+ You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cache_store`. All workers/tasks that should share a cache must use the same `prefix`.
149
+
150
+ </Update>
151
+
152
+ <Update label="v2.6.0" description="June 5, 2026">
153
+
154
+ ### New Features
155
+
156
+ #### Checkout Session — `metadata` Parameter
157
+
158
+ `checkout.create_session()` now accepts an optional `metadata` parameter for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
159
+
160
+ ```python
161
+ response = client.checkout.create_session(
162
+ planIdentifier="plan-pro-monthly",
163
+ chargePeriod="MONTHLY",
164
+ customerId="cust_789",
165
+ successUrl="https://example.com/success",
166
+ metadata={
167
+ "orderId": "order_12345",
168
+ "referralCode": "SUMMER2026",
169
+ },
170
+ )
171
+ ```
172
+
173
+ **Async variant:**
174
+
175
+ ```python
176
+ response = await async_client.checkout.create_session(
177
+ planIdentifier="plan-pro-monthly",
178
+ chargePeriod="MONTHLY",
179
+ customerId="cust_789",
180
+ successUrl="https://example.com/success",
181
+ metadata={"orderId": "order_12345"},
182
+ )
183
+ ```
184
+
185
+ The keys inside `metadata` are preserved exactly as provided — they are not transformed on the way to the API, so they survive the round-trip back through webhooks unchanged.
186
+
187
+ </Update>
188
+
7
189
  <Update label="v2.5.0" description="May 10, 2026">
8
190
 
9
191
  ### New Features
@@ -0,0 +1,225 @@
1
+ ---
2
+ title: "Command reference"
3
+ slug: "cli/commands"
4
+ section: "cli"
5
+ description: "Every Kelviq CLI command, flag by flag."
6
+ ---
7
+ All commands support `--help`. The CLI targets your **sandbox** environment unless you pass `--prod` — see [Environments & authentication](/cli/environments).
8
+
9
+ 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
+
11
+ ---
12
+
13
+ ## kelviq init
14
+
15
+ Writes a starter `kelviq.config.ts` to the current directory.
16
+
17
+ ```shell
18
+ kelviq init
19
+ kelviq init -o pricing/kelviq.config.ts
20
+ kelviq init --force
21
+ ```
22
+
23
+ | Flag | Description |
24
+ |---|---|
25
+ | `-o, --output <path>` | Where to write the file. Defaults to `kelviq.config.ts` in the current directory. |
26
+ | `--force` | Overwrite the file if it already exists. Without it, `init` refuses rather than clobbering your edits. |
27
+
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).
29
+
30
+ ---
31
+
32
+ ## kelviq login
33
+
34
+ Stores a Server API key for the CLI to use.
35
+
36
+ ```shell
37
+ kelviq login # store a sandbox key (default)
38
+ kelviq login --prod # store a production key
39
+ ```
40
+
41
+ | Flag | Description |
42
+ |---|---|
43
+ | `--prod` | Store the key for the production environment instead of sandbox. |
44
+
45
+ What it does:
46
+
47
+ 1. Prints the dashboard's [API keys page](https://app.kelviq.com/settings/api-keys) URL and tries to open it in your default browser — already switched to the environment you're logging into (sandbox by default, production with `--prod`), so the key on screen is the key the CLI expects.
48
+ 2. Prompts you to paste the key. In an interactive terminal each pasted character shows as `*` — so you can see the paste landed — and a `Received a N-character key.` line confirms the length. The key itself is never echoed or logged.
49
+ 3. Stores it in `~/.config/kelviq/config.json` with owner-only permissions (`0600`).
50
+
51
+ Paste a **Server API Key**, not a Client API Key. Server keys have full API access — treat the config file like any other credential store, and never commit it anywhere.
52
+
53
+ Kelviq has no key-introspection endpoint yet, so `login` cannot verify the key is valid or show which organization it belongs to — the first `pull` is where a bad key surfaces.
54
+
55
+ For CI and other non-interactive contexts, skip `login` entirely and set an environment variable instead — see [Environments & authentication](/cli/environments#environment-variables).
56
+
57
+ ---
58
+
59
+ ## kelviq logout
60
+
61
+ Removes stored API keys.
62
+
63
+ ```shell
64
+ kelviq logout # remove the stored sandbox key
65
+ kelviq logout --prod # remove the stored production key
66
+ kelviq logout --all # remove both
67
+ ```
68
+
69
+ | Flag | Description |
70
+ |---|---|
71
+ | `--prod` | Remove the production key instead of sandbox. |
72
+ | `--all` | Remove both sandbox and production keys. |
73
+
74
+ `logout` only touches the stored config file. Keys supplied via environment variables are unaffected — unset those in your shell or CI configuration.
75
+
76
+ Removing a key locally does not revoke it. To revoke a key, delete it from the [API keys page](https://app.kelviq.com/settings/api-keys) in the dashboard.
77
+
78
+ ---
79
+
80
+ ## kelviq env
81
+
82
+ Shows which environment and keys the CLI is configured with. Read-only — it never calls the API.
83
+
84
+ ```shell
85
+ kelviq env
86
+ ```
87
+
88
+ ```text
89
+ Environment : sandbox (default — use --prod to target production)
90
+ Sandbox URL : https://sandboxapi.kelviq.com/api/v1
91
+ Prod URL : https://api.kelviq.com/api/v1
92
+ Sandbox key : set
93
+ Prod key : missing
94
+ Org : unknown — Kelviq has no key-introspection endpoint yet
95
+ ```
96
+
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).
98
+
99
+ ---
100
+
101
+ ## kelviq pull
102
+
103
+ Fetches your remote catalog and writes it as a `kelviq.config.ts`.
104
+
105
+ ```shell
106
+ kelviq pull # pull the sandbox catalog
107
+ kelviq pull --prod # pull the production catalog
108
+ kelviq pull -o pricing.config.ts
109
+ kelviq pull --force # overwrite an existing file
110
+ ```
111
+
112
+ | Flag | Description |
113
+ |---|---|
114
+ | `--prod` | Pull from the production environment instead of sandbox. |
115
+ | `-o, --output <path>` | Where to write the config. Defaults to `kelviq.config.ts` in the current directory. |
116
+ | `--force` | Overwrite the output file if it already exists. Without it, `pull` refuses rather than overwriting local edits. |
117
+
118
+ What it fetches: all products, all features, the **latest version** of each plan, and each plan's prices and entitlements. Every cross-reference in the generated file uses `identifier` slugs, never UUIDs — the file is stable across environments that share identifiers.
119
+
120
+ On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `license`, `links`, `countries`, and `files` are dropped, with one warning each). Warnings are informational — the file it wrote is still valid.
121
+
122
+ On failure — missing key, network error, unexpected API response — `pull` writes `pull failed: <reason>` to stderr and exits non-zero without touching the output file.
123
+
124
+ ---
125
+
126
+ ## kelviq push
127
+
128
+ Deploys a `kelviq.config.ts` to a Kelviq environment: fetches the current remote catalog, computes exactly what would change, shows you the diff, and applies it only after confirmation.
129
+
130
+ ```shell
131
+ kelviq push --dry-run # preview only — never writes anything
132
+ kelviq push # diff, confirm, apply to sandbox
133
+ kelviq push --prod # same, against production
134
+ kelviq push --publish # also publish the plans this run changed
135
+ kelviq push pricing.config.ts # explicit config path
136
+ ```
137
+
138
+ | Flag | Description |
139
+ |---|---|
140
+ | `[config]` | Path to the config file. Defaults to `kelviq.config.ts`. |
141
+ | `--prod` | Target production instead of sandbox. |
142
+ | `--dry-run` | Print the diff and exit. Guaranteed zero writes. |
143
+ | `--yes` | Skip the confirmation prompts (required in non-interactive sessions, e.g. CI). |
144
+ | `--publish` | Publish the plans this run created, updated, or price-replaced — with its own confirmation. |
145
+ | `--migrate-features` | With `--publish`: migrate existing customers to the published plan's entitlements. |
146
+ | `--migrate-pricing` | With `--publish`: migrate existing customers to the published plan's pricing. |
147
+ | `--prune` | Archive remote-only plans/features that the CLI created (see below). |
148
+ | `--allow-prod-prune` | Required in place of the interactive typed confirmation to `--prune` production non-interactively. |
149
+ | `--verbose` | Expand aggregated warnings (e.g. list every stripped server-owned price field individually). |
150
+ | `--json` | With `--dry-run` only: emit the machine-readable plan-of-record as JSON on stdout. |
151
+
152
+ The diff shows **what actually changes**, value to value — `~ update plan "pro": name "Pro" → "Pro Plan"` — so the confirmation gate is reviewable at a glance.
153
+
154
+ ### Scripting with `--json`
155
+
156
+ `kelviq push --dry-run --json` prints exactly one JSON document: `{environment, direction, changes, summary, operations, prune, publish, featureDrift, errors, warnings}`. The `changes` boolean makes drift checks a one-liner in CI:
157
+
158
+ ```shell
159
+ kelviq push --dry-run --json | jq -e '.changes | not' || echo "catalog has drifted"
160
+ ```
161
+
162
+ `--json` is valid only with `--dry-run` (JSON mode never mixes with prompts or writes), always exits 0 on a successful render, and emits `{"error": …}` documents on failures. The shape is a documented, versioned contract — see the repo README.
163
+
164
+ ### What push writes — and in what order
165
+
166
+ Push converges the environment toward your config in dependency order: products → features → plans → entitlements → prices → publish → prune. Cross-references you wrote as identifiers are resolved to UUIDs automatically, including references to resources created earlier in the same run.
167
+
168
+ **Everything push writes is a draft by default.** Plan creates land in draft; updating a published plan creates a new draft version. Nothing a customer sees changes until a plan is explicitly published. On a mid-run failure, push stops immediately, reports exactly what was applied and what wasn't, and exits non-zero — there's no rollback, but because the writes were drafts, a half-applied push has no customer impact.
169
+
170
+ Push stamps a `managed-by: kelviq-cli` entry into the `metadata` of every feature and plan it creates (merged with any metadata you declare). That marker is how `--prune` later distinguishes CLI-managed resources from everything else — you'll see it in the dashboard, and it's safe to leave alone.
171
+
172
+ ### Prices are all-or-nothing per plan
173
+
174
+ 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
+
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.
177
+
178
+ ### Features can't be updated — by design
179
+
180
+ The Kelviq API deliberately treats feature attributes as immutable; renaming a feature is a dashboard operation. If a feature in your config differs from its remote counterpart, push stops **before writing anything** and lists the drifted fields — fix the feature in the [dashboard](https://app.kelviq.com), run `kelviq pull`, and push again.
181
+
182
+ ### Publishing
183
+
184
+ `--publish` publishes the plans the run just changed, after a second, separate confirmation listing them. A bare `--publish` never migrates existing customers — they stay on their current entitlements and pricing until you deliberately pass `--migrate-features` and/or `--migrate-pricing`, each of which spells out its consequence before you confirm. `--yes` skips prompts; it never substitutes for passing a migration flag explicitly.
185
+
186
+ ### Pruning
187
+
188
+ Remote-only resources — things that exist in the environment but not in your config — are normally just listed as warnings. `--prune` archives them, under strict conditions:
189
+
190
+ - Only plans and features **carrying the `managed-by: kelviq-cli` marker** are ever archived. Anything created in the dashboard, by another tool, or before marker support is listed as *skipped* with the reason — never touched.
191
+ - **Products are never pruned**, ever.
192
+ - Archiving is the platform's soft-delete — nothing is destroyed.
193
+ - Pruning production requires typing the environment name at a dedicated prompt (or `--allow-prod-prune` in CI). `--yes` alone never unlocks it.
194
+
195
+ ---
196
+
197
+ ## kelviq promote
198
+
199
+ Moves your sandbox catalog to production in one command — the same engine and safety rails as `push`, with sandbox as the source instead of a local file.
200
+
201
+ ```shell
202
+ kelviq promote --dry-run # preview what production would change — read-only
203
+ kelviq promote # diff, confirm, apply drafts to production
204
+ kelviq promote --publish # and publish the changed plans
205
+ ```
206
+
207
+ | Flag | Description |
208
+ |---|---|
209
+ | `--dry-run` | Print the sandbox→production diff and exit. Guaranteed zero writes. |
210
+ | `--yes` | Skip the confirmation prompts. |
211
+ | `--publish` / `--migrate-features` / `--migrate-pricing` | Same semantics as `push`. |
212
+ | `--prune` | Archive marker-carrying production plans/features absent from sandbox. Always crosses the production-prune gate. |
213
+ | `--allow-prod-prune` | Non-interactive stand-in for the typed production confirmation. |
214
+ | `--verbose` / `--json` | Same semantics as `push` (`--json` requires `--dry-run`). |
215
+
216
+ Promote reads and writes **no local file** — it fetches the sandbox catalog in memory and reconciles production toward it, matching resources by identifier (which is why the config format bans per-environment UUIDs). It needs both keys configured: sandbox to read, production to write.
217
+
218
+ Everything you know about push applies: drafts by default, a confirmation showing the full diff first, feature drift between the environments stops the run with dashboard guidance, and prices replace whole-set per plan. The intended workflow is always `--dry-run` first:
219
+
220
+ ```shell
221
+ kelviq promote --dry-run # read what would change
222
+ kelviq promote # then do it
223
+ ```
224
+
225
+ Promotion is one-way — sandbox to production. There is no reverse mode.