kosli assert artifact

Synopsis

kosli assert artifact [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]

Assert the compliance status of an artifact in Kosli. There are three ways to choose what to assert against:

Against an environment. When --environment is specified, asserts against all policies currently attached to the given environment.
Against one or more policies. When --policy is specified, asserts against all the given policies.
Against flow templates. When neither --environment nor --policy is specified, asserts against the template files of the flows the artifact is found in.

--environment and --policy are mutually exclusive. --flow can be combined with any of the above to narrow the lookup to a specific flow. Without --flow, all flows containing the artifact (by fingerprint) are considered. Exits with zero code if the artifact has compliant status, non-zero code if non-compliant status. To specify paths in a directory artifact that should always be excluded from the SHA256 calculation, you can add a .kosli_ignore file to the root of the artifact. Each line should specify a relative path or path glob to be ignored. You can include comments in this file, using #. The .kosli_ignore will be treated as part of the artifact like any other file, unless it is explicitly ignored itself.

Flags

Flag	Type	Description
`-t`, `--artifact-type`	string	The type of the artifact to calculate its SHA256 fingerprint. One of: [oci, docker, file, dir]. Only required if you want Kosli to calculate the fingerprint for you (i.e. when you don’t specify ‘`--fingerprint`’ on commands that allow it).
`-D`, `--dry-run`	bool	[optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors.
`--environment`	string	The Kosli environment name to assert the artifact against.
`-x`, `--exclude`	strings	[optional] The comma separated list of directories and files to exclude from fingerprinting. Can take glob patterns. Only applicable for `--artifact-type` dir.
`-F`, `--fingerprint`	string	[conditional] The SHA256 fingerprint of the artifact. Only required if you don’t specify ‘`--artifact-type`’.
`-f`, `--flow`	string	The Kosli flow name.
`-h`, `--help`	bool	help for artifact
`-o`, `--output`	string	[defaulted] The format of the output. Valid formats are: [table, json]. (default “table”)
`--policy`	strings	[optional] policy name (can be specified multiple times)
`--registry-password`	string	[conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.
`--registry-provider`	string	[deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used)
`--registry-username`	string	[conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.

Flags inherited from parent commands

Flag	Type	Description
`-a`, `--api-token`	string	The Kosli API token.
`-c`, `--config-file`	string	[optional] The Kosli config file path. (default “kosli”)
`--debug`	bool	[optional] Print debug logs to stdout.
`-H`, `--host`	string	[defaulted] The Kosli endpoint. (default “https://app.kosli.com”)
`--http-proxy`	string	[optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port`
`-r`, `--max-api-retries`	int	[defaulted] How many times should API calls be retried when the API host is not reachable. (default 3)
`--org`	string	The Kosli organization.
`-q`, `--quiet`	bool	[optional] Suppress non-critical warning messages. Errors and normal output are not affected. If both `--quiet` and `--debug` are set, `--debug` wins.

Live Examples in different CI systems

GitHub
GitLab

View an example of the kosli assert artifact command in GitHub.In this YAML file

View an example of the kosli assert artifact command in GitLab.In this YAML file

Examples Use Cases

These examples all assume that the flags --api-token, --org, --host, (and --flow, --trail when required), are set/provided.

assert that an artifact meets all compliance requirements for an environment

kosli assert artifact 
	--fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0 
	--environment prod 

assert that an artifact meets a set of policies

kosli assert artifact 
	--fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0 
	--policy has-approval,has-been-integration-tested 

fail if an artifact has a non-compliant status in a single flow (using the artifact fingerprint)

export KOSLI_FLOW=yourFlowName
kosli assert artifact 
	--fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0 

fail if an artifact has a non-compliant status in any flow (using the artifact name and type)

unset KOSLI_FLOW
kosli assert artifact library/nginx:1.21 
	--artifact-type docker 

Last modified on September 1, 2026

General

Top-level commands

kosli allow

kosli archive

kosli assert

kosli attest

kosli begin

kosli create

kosli delete

kosli diff

kosli disable / enable

kosli evaluate

kosli get

kosli join

kosli list

kosli log

kosli rename

kosli report

kosli rotate

kosli snapshot

kosli unarchive

kosli update

Synopsis

Flags

Flags inherited from parent commands

Live Examples in different CI systems

Examples Use Cases

​Synopsis

​Flags

​Flags inherited from parent commands

​Live Examples in different CI systems

​Examples Use Cases

Synopsis

Flags

Flags inherited from parent commands

Live Examples in different CI systems

Examples Use Cases