docs: update CLI and helm reference for v2.40.1

[github-actions]

Automated update of CLI and Helm reference documentation for release v2.40.1.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 11, 2026, 3:05 PM

[claude]

Claude finished @github-actions[bot]'s task in 2m 29s —— View job

---

Doc review — v2.40.1 reference update

Diff is the expected regeneration: sample-data churn (timestamps, snapshot IDs, a rotated languages-start-points artifact) plus the version stamp in client_reference/overview.md. Not itemised. The substantive part is the reworded API-key expiry and rotation help text, and that is where the rest of the site no longer agrees with it.

---

Critical

1. The Terraform reference says API keys can never expire; the v2.40.1 CLI says every key expires

Location: terraform-reference/resources/service_account_api_key.mdx:35, :57, :62, :87

Issue: client_reference/kosli_create_api-key.md:16 now states flatly "Every API key expires. Without --expires-at the key is given the maximum allowed lifetime, and an --expires-at beyond that maximum is capped to it." The Terraform page describes the same server-side resource and says the opposite in four places:

• line 35 — the example is literally commented # A non-expiring API key
• line 57 — "Omit it for a key that never expires."
• line 62 — "expires_at is null for a key that never expires."
• line 87 — "Omit for a key that never expires… to get a non-expiring key again, the key must be recreated"

Both surfaces hit the same Kosli API, so one of them is wrong. If the max-lifetime rule is enforced server-side, a Terraform user who omits expires_at believing they minted a permanent CI credential gets a silent outage when the cap elapses — and line 87's advice to recreate the key "to get a non-expiring key again" is unachievable.

Recommendation: Confirm with kosli-dev/server whether the cap is server-side or CLI-side, then reconcile. If server-side, rewrite the ## Expiry section and the schema description to say omitting expires_at yields the maximum allowed lifetime, and drop the "non-expiring" example comment. This page is agent-synced from kosli-dev/terraform-provider-kosli, so the same wording needs fixing in the provider's schema descriptions or the next sync reverts it. Fix this →

---

Improvement

2. Rotation docs never mention that the new key inherits the old key's expiry

Location: administration/authentication/api_key_rotation.md:9-17, tutorials/rotating_api_keys.mdx:18-26

Issue: kosli rotate api-key's --expires-at is newly documented as "Defaults to the rotated key's current expiry, and is capped by the maximum allowed key lifetime." Both prose pages describe rotation purely in terms of the grace period on the old key and say nothing about the new key's expiry. Combined with the tutorial's own advice to rotate every 90 days (tutorials/rotating_api_keys.mdx:139), a reader following these docs to the letter rotates a key that is nine months into its maximum lifetime and receives a replacement that expires at the same moment the original would have — the exact failure rotation was supposed to prevent. Nothing on either page tells them to pass --expires-at to extend it.

Recommendation: Add a step to the "How rotation works" list on both pages: the new key inherits the rotated key's expiry unless --expires-at is given, and that value is capped by the maximum key lifetime. In the tutorial's CLI tab, show --expires-at alongside --grace-period-hours. Fix this →

---

Suggestion

3. No changelog entry covers the new expiry behavior

Location: changelog/index.mdx:7

Issue: The newest entry is v2.39.2; there is nothing for v2.40.0 or v2.40.1. "Every API key expires" and "an --expires-at beyond the maximum is capped to it" is a behavior change that can break anyone who provisioned a key expecting it to be permanent, and it is currently discoverable only by diffing CLI help text.

Recommendation: Add a <Update> entry for the release. Per CLAUDE.md, ask the user for the tags value first (likely "CLI", or "Platform" if the cap is server-side).

---

Upstream — does not block this merge

Generated from kosli-dev/cli; a hand-edit here is destroyed by the next release.

• cmd/kosli/createApiKey.go — the --expires-at help ends "…the key gets the maximum allowed lifetime, which also caps later dates." "later dates" is ambiguous: it reads as "dates later than today" rather than "dates beyond the maximum". The body prose two lines up already says it clearly ("an --expires-at beyond that maximum is capped to it"); the flag string should borrow that phrasing. The same string's example dates ('2026-06-04') are also now in the past.
• cmd/kosli/rotateApiKey.go — the grace-period help changed from "server-managed" to "a standard length" / "the standard grace period", which names no number. This docs site asserts a concrete default of 24 hours in two places (administration/authentication/api_key_rotation.md:14, tutorials/rotating_api_keys.mdx:23). Stating the number in the help text would let the docs be verified against it instead of asserting it independently.

---

1 Critical, 1 Improvement, 1 Suggestion, 2 upstream notes; none on files this PR changed. Merge it — the regeneration is a faithful copy of upstream, and the findings above are follow-up work on other pages. Note that I could not run gh pr checks (not permitted in this environment), so the link-rot result is unverified; this diff adds no links, so nothing here needed checking.
· reference-docs/v2.40.1