docs: empty flag values

changelog/index.mdx

@@ -4,6 +4,17 @@ description: "Release notes for Kosli products."
 rss: true
 ---
 
+<Update label="August 18, 2026" description="v2.37.0" tags={["CLI"]}>
+
+## Breaking changes
+
+- **An empty flag value is refused** — `--flag ""` is now an error on every flag of every command, wherever the value comes from: the command line, a `KOSLI_` environment variable, or `~/.kosli.yml`. Accepting it was a bug. An empty value never did what the command was asked to do, and usually reported success anyway, so a pipeline that starts failing here was already producing a result nobody asked for. The usual cause is a shell variable that is unset. The error names the flag: give it a real value, or remove the flag, since in almost every case an empty value did what leaving the flag out does. Leaving a flag out is unchanged, including defaults filled in from your CI environment. See [empty flag values](/faq/faq#empty-flag-values).
+- **`--description ""` no longer clears a description** — on `kosli update control` and `kosli update service-account`, an empty value was the only way to empty a description. That is no longer possible: a description can be changed but not emptied.
+
+[View on GitHub](https://github.com/kosli-dev/cli/releases/tag/v2.37.0)
+
+</Update>
+
 <Update label="August 14, 2026" description="v2.36.6" tags={["CLI"]}>
 
 ## Bug fixes

faq/faq.md

@@ -116,3 +116,34 @@ kosli attest generic Dockerfile false ...
 ```
 The parser then sees `Dockerfile` and `false` as the two
 arguments to `kosli attest generic`.
+
+## Empty flag values
+
+A flag given an empty value is an error from CLI v2.37.0 onwards:
+```
+kosli attest generic Dockerfile --artifact-type file --exclude "" ...
+Error: flag '--exclude' was given an empty value
+```
+The usual cause is a shell variable that is unset, so `--exclude "$BUILD_TMP"`
+reaches the CLI as `--exclude ""`. The same applies to a value from a `KOSLI_`
+environment variable or from `~/.kosli.yml`, and to an empty element of a
+comma-separated list such as `--exclude "node_modules,,vendor"`.
+
+On earlier versions most of these were accepted silently. `--exclude ""`
+excluded nothing, so the fingerprint was one no artifact matched;
+`--fingerprint ""` recorded an attestation against the trail rather than the
+artifact named; `--redact-commit-info ""` sent the commit author and message
+the flag exists to withhold. Each exited 0 and printed what success prints.
+
+Either give the flag a real value, or remove it. In almost every case an empty
+value did what leaving the flag out does, so removing it keeps the earlier
+behavior and says so plainly.
+
+Leaving a flag out is unchanged, including the values filled in from your CI
+environment, such as `--build-url`, `--commit-url` and `--repository`.
+
+One case the CLI cannot catch: a boolean flag written without quotes loses the
+empty value in the shell rather than in the CLI, so `--compliant ${UNSET}`
+arrives as `--compliant` with nothing after it, which is indistinguishable from
+typing `--compliant` deliberately. Quote the variable, `--compliant "${VAR}"`,
+and it is refused like any other empty value.