From 91e4712be4b7dc1b627027b67b2399a9704e0854 Mon Sep 17 00:00:00 2001 From: JonJagger Date: Tue, 18 Aug 2026 14:11:39 +0100 Subject: [PATCH 1/5] docs: say that an empty flag value is refused A pipeline that has been quietly passing an empty flag value starts failing on the release that refuses it, and the person it fails for reads the docs, not the release notes. The FAQ section follows the boolean-flags one it sits below: the failing command, the error verbatim, why the value is usually empty, and what to do about it. The changelog entry says the accepting was the bug, so a new failure reads as a diagnosis rather than a regression. Both carry vX.Y.0 as a placeholder until the release version is decided. --- changelog/index.mdx | 11 +++++++++++ faq/faq.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/changelog/index.mdx b/changelog/index.mdx index 50935e3..5a40146 100644 --- a/changelog/index.mdx +++ b/changelog/index.mdx @@ -4,6 +4,17 @@ description: "Release notes for Kosli products." rss: true --- + + +## 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/vX.Y.0) + + + ## Breaking changes diff --git a/faq/faq.md b/faq/faq.md index 4737a97..c2b9e54 100644 --- a/faq/faq.md +++ b/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 vX.Y.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 +behaviour 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. From 9e15ac1dd1f1e23efbfb9ed1ddadc85af1d2019e Mon Sep 17 00:00:00 2001 From: JonJagger Date: Tue, 18 Aug 2026 14:17:57 +0100 Subject: [PATCH 2/5] docs: name v2.37.0 as the release that refuses empty flag values The FAQ and changelog were written before the version was known. A customer reading either needs to know which version changed under them, so the version is the part that cannot stay a placeholder. --- changelog/index.mdx | 4 ++-- faq/faq.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/changelog/index.mdx b/changelog/index.mdx index 78a1a18..a4432d2 100644 --- a/changelog/index.mdx +++ b/changelog/index.mdx @@ -4,14 +4,14 @@ description: "Release notes for Kosli products." rss: true --- - + ## 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/vX.Y.0) +[View on GitHub](https://github.com/kosli-dev/cli/releases/tag/v2.37.0) diff --git a/faq/faq.md b/faq/faq.md index c2b9e54..2137afe 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -119,7 +119,7 @@ arguments to `kosli attest generic`. ## Empty flag values -A flag given an empty value is an error from CLI vX.Y.0 onwards: +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 From 3e730d2cdf400df245dfb1eaced7b490ab0dd054 Mon Sep 17 00:00:00 2001 From: Jon Jagger Date: Tue, 18 Aug 2026 14:27:01 +0100 Subject: [PATCH 3/5] Update faq/faq.md Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- faq/faq.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/faq/faq.md b/faq/faq.md index 2137afe..ef5ed72 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -137,7 +137,8 @@ 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 -behaviour and says so plainly. +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`. From 80e95a6d79c15e2a8e06ea5f7c9f816c77e94944 Mon Sep 17 00:00:00 2001 From: Jon Jagger Date: Tue, 18 Aug 2026 14:30:12 +0100 Subject: [PATCH 4/5] Update faq/faq.md Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- faq/faq.md | 1 - 1 file changed, 1 deletion(-) diff --git a/faq/faq.md b/faq/faq.md index ef5ed72..2ad79cf 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -137,7 +137,6 @@ 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 -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 From 43aa21d141e11ea63b05c43a51336e673f7a5e4c Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 18 Aug 2026 16:44:29 +0100 Subject: [PATCH 5/5] chore: Apply suggestions from code review Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- changelog/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/index.mdx b/changelog/index.mdx index 30146ca..21080d5 100644 --- a/changelog/index.mdx +++ b/changelog/index.mdx @@ -4,7 +4,7 @@ description: "Release notes for Kosli products." rss: true --- - + ## Breaking changes