Skip to main content
Kosli API documentation is available for logged-in Kosli users at app.kosli.com/api/v2/doc. You can also find the link at app.kosli.com 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 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:
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:
--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.
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. To report generic evidence as non-compliant use --compliant=false:
--compliant is set to true by default, so to report as compliant simply skip the flag altogether.
If you sign in to Kosli with GitHub, you must have a verified email address on your GitHub account — otherwise login will fail.You can check the status of your email addresses at github.com/settings/emails.
It’s not possible to delete a policy in Kosli. This is by design, because there can be snapshots that were previously evaluated using the policy. Deleting it would compromise the integrity of those historical evaluations.Archiving policies isn’t available yet. If this is something you’d find useful, we’d love to hear about your use case — reach out to us at support@kosli.com.

​
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. Boolean flags accept both forms from CLI v2.36.0 onwards:
On earlier versions an explicitly specified boolean flag value must use an =. Either upgrade the CLI, or write the flag as --compliant=false. Without the = the command above fails with:
because --compliant is parsed as if implicitly defaulting to --compliant=true, leaving:
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:
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.
Last modified on August 18, 2026