From 12c0ba8e5496192284a347bd807bd7a3fc44b12b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 25 Mar 2026 09:43:03 +0100 Subject: [PATCH 1/4] docs: add troubleshooting pages extracted from FAQ Move 5 error-driven sections from the monolithic FAQ into individual troubleshooting pages with a consistent Error/Solution/Context structure. --- docs.json | 7 +++++- troubleshooting/docker_api_version_error.md | 23 +++++++++++++++++ troubleshooting/github_kosli_api_token.md | 21 ++++++++++++++++ troubleshooting/subshell_stderr.md | 28 +++++++++++++++++++++ troubleshooting/whitespace_path.md | 18 +++++++++++++ troubleshooting/zsh_no_such_user.md | 25 ++++++++++++++++++ 6 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 troubleshooting/docker_api_version_error.md create mode 100644 troubleshooting/github_kosli_api_token.md create mode 100644 troubleshooting/subshell_stderr.md create mode 100644 troubleshooting/whitespace_path.md create mode 100644 troubleshooting/zsh_no_such_user.md diff --git a/docs.json b/docs.json index 93ab42f..dd2abd9 100644 --- a/docs.json +++ b/docs.json @@ -159,7 +159,12 @@ "group": "Troubleshooting", "icon": "wrench", "pages": [ - "troubleshooting/what_do_i_do_if_kosli_is_down" + "troubleshooting/what_do_i_do_if_kosli_is_down", + "troubleshooting/docker_api_version_error", + "troubleshooting/zsh_no_such_user", + "troubleshooting/github_kosli_api_token", + "troubleshooting/subshell_stderr", + "troubleshooting/whitespace_path" ] }, { diff --git a/troubleshooting/docker_api_version_error.md b/troubleshooting/docker_api_version_error.md new file mode 100644 index 0000000..3eedb7f --- /dev/null +++ b/troubleshooting/docker_api_version_error.md @@ -0,0 +1,23 @@ +--- +title: "Docker API version error in GitHub Actions" +description: 'How to fix the "client version 1.47 is too new" error when running the Kosli CLI in GitHub Action workflows.' +--- + +## Error + +``` +Error response from daemon: client version 1.47 is too new. Maximum supported API version is 1.45 +``` + +## Solution + +Set the `DOCKER_API_VERSION` environment variable in your workflow: + +```yaml +env: + DOCKER_API_VERSION: "1.45" +``` + +## Context + +The latest Kosli CLI defaults to Docker API version 1.47, but GitHub Action workflows currently support a maximum of 1.45. diff --git a/troubleshooting/github_kosli_api_token.md b/troubleshooting/github_kosli_api_token.md new file mode 100644 index 0000000..f9da263 --- /dev/null +++ b/troubleshooting/github_kosli_api_token.md @@ -0,0 +1,21 @@ +--- +title: "GitHub can't see KOSLI_API_TOKEN secret" +description: "How to make the KOSLI_API_TOKEN secret available in GitHub Actions workflows." +--- + +## Error + +Kosli CLI commands fail in GitHub Actions because `KOSLI_API_TOKEN` is not set, even though the secret exists in your repository. + +## Solution + +Add the secret to your workflow's environment variables explicitly: + +```yaml +env: + KOSLI_API_TOKEN: ${{ secrets.kosli_api_token }} +``` + +## Context + +Secrets in GitHub Actions are not automatically exported as environment variables. You must map them explicitly in each workflow or job. diff --git a/troubleshooting/subshell_stderr.md b/troubleshooting/subshell_stderr.md new file mode 100644 index 0000000..8bb8b39 --- /dev/null +++ b/troubleshooting/subshell_stderr.md @@ -0,0 +1,28 @@ +--- +title: "CLI in subshell captures stderr" +description: "How to handle Kosli CLI debug output being captured in subshell variables in CI workflows." +--- + +## Error + +When capturing Kosli CLI output in a subshell variable in CI, the variable contains debug output mixed with the expected value: + +```shell +DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker)" + +echo "DIGEST=${DIGEST}" +DIGEST=[debug] calculated fingerprint: 2c6079df5829... +2c6079df58292ed10e8074adcb74be549b7f841a1bd8266f06bb5c518643193e +``` + +## Solution + +Explicitly set `--debug=false` when running Kosli CLI commands in a subshell: + +```shell +DIGEST="$(kosli fingerprint "${IMAGE_NAME}" --artifact-type=docker --debug=false)" +``` + +## Context + +The Kosli CLI writes debug information to `stderr` and all other output to `stdout`. In a local terminal, a `$(subshell)` captures only `stdout`. However, in many CI workflows (including GitHub and GitLab), `stdout` and `stderr` are multiplexed together, causing debug output to leak into captured variables. diff --git a/troubleshooting/whitespace_path.md b/troubleshooting/whitespace_path.md new file mode 100644 index 0000000..71575e3 --- /dev/null +++ b/troubleshooting/whitespace_path.md @@ -0,0 +1,18 @@ +--- +title: "Path/Image name is a single whitespace character" +description: "How to fix the whitespace path error when using multi-line Kosli CLI commands." +--- + +## Error + +``` +Error: failed to calculate artifact fingerprint: stat : no such file or directory. The directory path is ' '. +``` + +## Solution + +Check your multi-line command for extraneous whitespace after line-continuation backslashes (`\`). Remove any spaces or tabs after the `\` on each line. + +## Context + +When using multi-line commands, whitespace added after a line-continuation backslash is interpreted as the artifact path or image name argument. diff --git a/troubleshooting/zsh_no_such_user.md b/troubleshooting/zsh_no_such_user.md new file mode 100644 index 0000000..e44f2b2 --- /dev/null +++ b/troubleshooting/zsh_no_such_user.md @@ -0,0 +1,25 @@ +--- +title: "zsh: no such user or named directory" +description: "How to fix the zsh error when using arguments starting with ~ in Kosli CLI commands." +--- + +## Error + +```shell +kosli list snapshots prod ~3..NOW +``` +```plaintext +zsh: no such user or named directory: 3..NOW +``` + +## Solution + +Wrap the argument in quotation marks (single or double): + +```shell +kosli list snapshots prod '~3..NOW' +``` +or +```shell +kosli list snapshots prod "~3..NOW" +``` From 0a3d820a82331904504009f68144a00c9d5ebb7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 25 Mar 2026 13:21:45 +0100 Subject: [PATCH 2/4] docs: add FAQ page with accordion layout and navigation Restructure remaining FAQ content using Mintlify AccordionGroup and CodeGroup components. Add FAQ to docs.json navigation. Boolean flags section kept as a heading to preserve client_reference anchor links. --- docs.json | 7 ++++ faq/faq.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 faq/faq.md diff --git a/docs.json b/docs.json index dd2abd9..288fdef 100644 --- a/docs.json +++ b/docs.json @@ -167,6 +167,13 @@ "troubleshooting/whitespace_path" ] }, + { + "group": "FAQ", + "icon": "circle-question", + "pages": [ + "faq/faq" + ] + }, { "group": "Integrations", "icon": "puzzle-piece", diff --git a/faq/faq.md b/faq/faq.md new file mode 100644 index 0000000..ec1987e --- /dev/null +++ b/faq/faq.md @@ -0,0 +1,109 @@ +--- +title: FAQ +description: "Frequently asked questions" +--- + + + + +Kosli API documentation is available for logged-in Kosli users at [app.kosli.com](https://app.kosli.com). +You can find the link after clicking your avatar (top-right corner of the page). + + + +A number of flags won't change their values often (or at all) between commands, like `--org` or `--api-token`. Some will differ between e.g. workflows, like `--flow`. You can define them as environment variables to avoid unnecessary redundancy. Check [Environment variables](/getting_started/install#assigning-flags-via-environment-variables) to learn more. + + + +You can use dry run to disable writing to app.kosli.com — e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode). + +There are three ways to enable a dry run: +1. Use the `--dry-run` flag (no value needed) to enable it per command +2. Set the `KOSLI_DRY_RUN` environment variable to `true` to enable it globally (e.g. in your terminal or CI) +3. Set the `KOSLI_API_TOKEN` environment variable to `DRY_RUN` to enable it globally (e.g. in your terminal or CI) + + + +A config file is an alternative to using Kosli flags or environment variables. Usually you'd use a config file for values that rarely change — like api token or org — but you can represent all Kosli flags in a config file. The key for each value is the same as the flag name, capitalized, so `--api-token` becomes `API-TOKEN`, and `--org` becomes `ORG`, etc. + +You can use JSON, YAML, or TOML format: + + +```json kosli-conf.json +{ + "ORG": "my-org", + "API-TOKEN": "123456abcdef" +} +``` + +```yaml kosli-conf.yaml +ORG: "my-org" +API-TOKEN: "123456abcdef" +``` + +```toml kosli-conf.toml +ORG = "my-org" +API-TOKEN = "123456abcdef" +``` + + +When calling a Kosli command you can skip the file extension. For example, to list environments with `org` and `api-token` in the configuration file: + +```shell +kosli list environments --config-file kosli-conf +``` + +`--config-file` defaults to `kosli`, so if you name your file `kosli.` and the file is in the same location as where you run Kosli commands from, you can skip the `--config-file` altogether. + + + +If an artifact or evidence is reported multiple times there are a few corner cases: + +**Template** — When an artifact is reported, the template for the flow is stored together with the artifact. If the template has changed between reports, the last template is considered the template for that artifact. + +**Evidence** — If a given named evidence is reported multiple times, the compliance status of the last reported version is considered the compliance state of that evidence. If an artifact is reported multiple times with different git-commits, the last reported version of the named commit-evidence is considered the compliance state. + +**Evidence outside the template** — If an artifact has evidence (commit or artifact evidence) that is not part of the template, the state of the extra evidence will affect the overall compliance of the artifact. + + + +The `--compliant` flag is a [boolean flag](#boolean-flags). +To report generic evidence as non-compliant use `--compliant=false`: + +```shell +kosli report evidence artifact generic server:1.0 \ + --artifact-type docker \ + --name test \ + --description "generic test evidence" \ + --compliant=false \ + --flow server +``` + +`--compliant` is set to `true` by default, so to report as compliant simply skip the flag altogether. + + + + +## Boolean flags + +Flags with values can usually be specified with an `=` or with a **space** as a separator. +For example, `--artifact-type=file` or `--artifact-type file`. +However, an explicitly specified boolean flag value **must** use an `=`. +For example, if you try this: +``` +kosli attest generic Dockerfile --artifact-type file --compliant true ... +``` +You will get an error stating: +``` +Error: accepts at most 1 arg(s), received 2 +``` +Here, `--artifact-type file` is parsed as if it was `--artifact-type=file`, leaving: +``` +kosli attest generic Dockerfile --compliant true ... +``` +Then `--compliant` is parsed as if *implicitly* defaulting to `--compliant=true`, leaving: +``` +kosli attest generic Dockerfile true ... +``` +The parser then sees `Dockerfile` and `true` as the two +arguments to `kosli attest generic`. From 3d53b49a5f6e17c864e9067381d249cb5f57c52f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 25 Mar 2026 13:27:07 +0100 Subject: [PATCH 3/4] fix: correct broken link to try_kosli_locally tutorial --- labs/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/labs/index.mdx b/labs/index.mdx index 685d1da..2934391 100644 --- a/labs/index.mdx +++ b/labs/index.mdx @@ -9,7 +9,7 @@ These labs provide a progressive, practical introduction to Kosli's core feature Each lab builds on the previous one — complete them in order. - Want something shorter first? [Try Kosli locally](/tutorials/get_familiar_with_Kosli) is a 10-minute Docker-based demo that requires no GitHub account or CI pipeline. + Want something shorter first? [Try Kosli locally](/tutorials/try_kosli_locally) is a 10-minute Docker-based demo that requires no GitHub account or CI pipeline. From a011cbd55b0a33cc0af1e59623f47600f7d8de3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 25 Mar 2026 13:28:44 +0100 Subject: [PATCH 4/4] fix: address PR review feedback on FAQ page --- faq/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/faq/faq.md b/faq/faq.md index ec1987e..94e3471 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -6,8 +6,8 @@ description: "Frequently asked questions" -Kosli API documentation is available for logged-in Kosli users at [app.kosli.com](https://app.kosli.com). -You can find the link after clicking your avatar (top-right corner of the page). +Kosli API documentation is available for logged-in Kosli users at [app.kosli.com/api/v2/doc](https://app.kosli.com/api/v2/doc/). +You can also find the link at [app.kosli.com](https://app.kosli.com) after clicking your avatar (top-right corner of the page). @@ -15,7 +15,7 @@ A number of flags won't change their values often (or at all) between commands, -You can use dry run to disable writing to app.kosli.com — e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode). +You can use dry run to disable writing to `app.kosli.com` — e.g. if you're just trying things out, or troubleshooting (dry run will print the payload the CLI would send in a non dry run mode). There are three ways to enable a dry run: 1. Use the `--dry-run` flag (no value needed) to enable it per command