docs: update CLI and helm reference for v2.40.0

[github-actions]

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

[mintlify]

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

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 11, 2026, 8:10 AM

[claude]

Claude encountered an error after 3m 34s —— View job

---

Doc quality review

Reviewed all 94 changed files at 55bc449. The bulk of the diff — kosli_get_snapshot.md, kosli_diff_snapshots.md, kosli_log_environment.md, kosli_list_*, and the live-docs example links — is regenerated sample data (timestamps, fingerprints, commit SHAs, snapshot indices) with no structural change; not itemised.

The substantive upstream changes are: the --config-file default moving from kosli to $HOME/.kosli.yml, the rewritten .kosli_ignore paragraph, the new --jira-trailer flag, the 1 MB JSON payload note, new S3 object-key validation, and new --digests-source acr guidance. Two of those contradict hand-authored pages.

---

Critical — hand-authored pages now contradict the v2.40.0 CLI

kosli config and every flag table in this PR now say the config file is read from $HOME/.kosli.yml (or --config-file / KOSLI_CONFIG_FILE) and "never implicitly from the current directory". Two hand-authored pages still tell readers the opposite. A customer with ./kosli.yaml next to their pipeline loses their org and API token silently on upgrade, and both pages tell them that setup is supported.

1. faq/faq.md:56

--config-file defaults to kosli, so if you name your file kosli.<yaml|toml|json> and the file is in the same location as where you run Kosli commands from, you can skip the --config-file altogether.

Both halves are now wrong: the default is $HOME/.kosli.yml, and a file in the working directory is never picked up. Replace with the new default path and note that a project-local file must be named explicitly with --config-file or KOSLI_CONFIG_FILE. Fix this →

2. getting_started/install.md:168

By default, the CLI looks for a config file called kosli.<yaml/yml/json/toml>

Same defect, on the page the rest of the site links to for flag configuration (/getting_started/install#assigning-flags-via-config-files is referenced from administration/authentication/api_authentication_methods.md:28 and getting_started/flows.md:10). While here, the precedence list at install.md:141-145 should mention KOSLI_CONFIG_FILE, which kosli_config.md now documents as an alternative to the flag. Fix this →

Improvement

3. changelog/index.mdx — no v2.40.0 entry

The changelog stops at v2.39.2. The config-file change is the kind a reader needs told explicitly rather than discovered from a flag table: an existing ./kosli.yaml stops being honoured. Worth an entry under Changes calling out the new default and the end of implicit current-directory lookup, alongside --jira-trailer (new feature) and the 1 MB --user-data / --attestation-data limit. If .mintlify/workflows/update-changelog.md generates this from the release tag, make sure it runs for v2.40.0 and doesn't bury the config-file change as a help-text tweak.

---

Upstream — does not block this merge

These are faithful copies of the release binary's output. A hand-edit here is deleted by the next update-cli-docs.yml run, so the fix belongs in kosli-dev/cli.

4. Three empty accordions and fragment titles on kosli attest jira — client_reference/kosli_attest_jira.md:247-261

The new --jira-trailer example's comment is a four-line comment block, and the docs generator starts a new <Accordion> at each comment line. The published page renders four accordions, three with an empty shell block, and titles that read as broken sentences: "confines scanning to the trailer value — useful when project keys collide with", "patterns like CVE identifiers; write the issue key alone (e.g. 'Jira: CVE-42'),", "not embedded in a longer hyphenated string ('Jira: CVE-2026-41284' is still filtered)". The last one is the accordion that actually holds the command.

Fix in kosli-dev/cli → cmd/kosli/attestJira.go: collapse the example's comment to a single line (the surrounding long description already carries the CVE-collision explanation), or keep only the first line as the title. Every other example in the file uses a one-line comment.

5. kosli snapshot s3 contradicts itself on include/exclude precedence — client_reference/kosli_snapshot_s3.md:24 vs :39-40

New prose: "when --include or --include-regex is set, exclude filters are ignored, so narrow the include filter instead." The flag table on the same page: "Cannot be used together with --include or --include-regex." A reader cannot tell whether passing both is silently ignored or rejected — and the answer decides whether the suggested workaround is even usable. Reconcile in kosli-dev/cli → cmd/kosli/snapshotS3.go.

6. .kosli_ignore advice points at a flag kosli snapshot paths doesn't have — client_reference/kosli_snapshot_paths.md:28-29

The shared paragraph says "Excluding the file with --exclude …" and "move its entries to --exclude and delete it", but kosli snapshot paths has no --exclude flag — its only flags are --dry-run, --help, --paths-file, --watch, and exclusions are the per-artifact exclude: key in the paths spec (shown at :37). kosli snapshot path (singular) does have -x, --exclude, so only the plural form is wrong. Either use the two-sentence variant here (as kosli snapshot azure and kosli snapshot s3 already do) or word it in terms of the spec file, in kosli-dev/cli → cmd/kosli/snapshotPaths.go.

7. Two unrelated paragraphs merge into one on kosli snapshot azure — client_reference/kosli_snapshot_azure.md:29-30

The new --dry-run sentence has no blank line after it, so Markdown renders "--dry-run suppresses only the request to Kosli. Azure discovery and registry lookups still run. To specify paths in a directory artifact…" as a single paragraph. Add a trailing blank line before the appended .kosli_ignore block in kosli-dev/cli → cmd/kosli/snapshotAzure.go.

---

2 Critical, 1 Improvement, 4 upstream. The regeneration itself is faithful and should merge; the two Critical findings are pre-existing hand-authored pages that this release makes wrong, and are worth a follow-up PR before v2.40.0 is announced. Note: mint broken-links was not run (CLI not installed in this job), but the diff adds no new internal links.
· branch reference-docs/v2.40.0