This tutorial shows you how to use Kosli’s query commands to search for artifacts, inspect their history, and browse runtime environment snapshots.
get, list, log, and diff commands let you query everything Kosli knows about your artifacts and environments directly from your terminal.
By the end of this tutorial, you will have searched for an artifact by commit SHA, inspected its full history, browsed environment snapshots, and compared two snapshots to see what changed.We will query cyber-dojo, an open-source project whose Kosli data is public.
export KOSLI_ORG=cyber-dojo# cyber-dojo is public, so the token is not checked; the CLI only needs a non-empty valueexport KOSLI_API_TOKEN=ignored
cyber-dojo is a public organization, so you can follow this tutorial before you have a token of your own. When you query your own organization, replace ignored with a real API token.
If you have a git commit SHA, kosli search will find any artifact built from it:
kosli search 99d7b74
Search result resolved to commit 99d7b74f39e311d492902ad48dbe97da63f2c687Name: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/creator:99d7b74Fingerprint: a39fa3230549d3c6cb1732cc929c4e21041a09a21b2bb692cd37c9afe5fcd424Has provenance: trueFlow: creator-ciGit commit: 99d7b74f39e311d492902ad48dbe97da63f2c687Commit URL: https://github.com/cyber-dojo/creator/commit/99d7b74f39e311d492902ad48dbe97da63f2c687Build URL: https://github.com/cyber-dojo/creator/actions/runs/34443243072Artifact URL: https://app.kosli.com/cyber-dojo/flows/creator-ci/artifacts/a39fa3230549d3c6cb1732cc929c4e21041a09a21b2bb692cd37c9afe5fcd424Compliance state: COMPLIANTRunning in: [ aws-beta, aws-prod ]Exited from: [ ]History: Commit 99d7b74 Thu, 10 Sep 2026 07:58:56 CEST Artifact created Thu, 10 Sep 2026 08:01:20 CEST Started running in aws-beta#8339 environment Thu, 10 Sep 2026 08:06:24 CEST Started running in aws-prod#5349 environment Thu, 10 Sep 2026 08:55:58 CEST[... further artifacts for this commit ...]
One commit can produce several artifacts, and kosli search prints each one as its own block. Here the same commit also produced Terraform state artifacts in other flows; those blocks are trimmed from the output above.
The search result tells us this artifact belongs to the creator-ci flow. If you don’t know which flows exist in your org, you can list them all:
kosli list flows
NAME DESCRIPTION VISIBILITY TAGScreator-ci UX for Group/Kata creation private [ci=github], [repo_url=https://github.com/cyber-dojo/creator], [kind=build], [env=aws-beta]custom-start-points-ci Custom exercises choices private [ci=github], [repo_url=https://github.com/cyber-dojo/custom-start-points], [kind=build], [env=aws-beta]dashboard-ci UX for a group practice dashboard private [ci=github], [repo_url=https://github.com/cyber-dojo/dashboard], [kind=build], [env=aws-beta]differ-ci Diff files from two traffic-lights private [ci=github], [repo_url=https://github.com/cyber-dojo/differ], [kind=build], [env=aws-beta][...]web-ci UX for practicing TDD private [ci=github], [repo_url=https://github.com/cyber-dojo/web], [kind=build], [env=aws-beta]
The VISIBILITY column is a legacy per-flow field and does not affect who can read a flow. Access is determined by the organization’s visibility. cyber-dojo is a public organization, so every flow listed here is readable without a real token.Once you know the flow name, you can list the artifacts reported to it:
kosli list artifacts --flow creator-ci
COMMIT ARTIFACT STATE CREATED_AT99d7b74 Name: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/creator:99d7b74 COMPLIANT Thu, 10 Sep 2026 08:01:20 CEST Fingerprint: a39fa3230549d3c6cb1732cc929c4e21041a09a21b2bb692cd37c9afe5fcd424abdc613 Name: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/creator:abdc613 COMPLIANT Mon, 07 Sep 2026 12:56:13 CEST Fingerprint: ba988cfdac64da22bc8268442c467504fe8df565e65c2f3c4344ce00c83e561ab1e77bf Name: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/creator:b1e77bf COMPLIANT Thu, 03 Sep 2026 16:53:05 CEST Fingerprint: 3e2248d4cd5715c23ef4b322291cc34b48c741f5ea299f8681349529b0829d56[...]
By default, the last 15 artifacts are shown. Use to change how many are shown, to paginate, and to change the format.
Now that you can see individual snapshots, you can also diff two of them to find out exactly what changed between any two points in time. Comparing snapshot #8339 with the one before it shows the creator deployment:
kosli diff snapshots aws-beta#8339 aws-beta#8338
Only present in aws-beta#8339 Name: 244531986313.dkr.ecr.eu-central-1.amazonaws.com/creator:99d7b74@sha256:a39fa3230549d3c6cb1732cc929c4e21041a09a21b2bb692cd37c9afe5fcd424 Fingerprint: a39fa3230549d3c6cb1732cc929c4e21041a09a21b2bb692cd37c9afe5fcd424 Flow: creator-ci Commit URL: https://github.com/cyber-dojo/creator/commit/99d7b74f39e311d492902ad48dbe97da63f2c687 Started: Thu, 10 Sep 2026 08:06:01 CEST • 4 days ago Instances: 1
Relative references work here too. kosli diff snapshots aws-beta aws-beta~1 compares the two most recent snapshots. If the same artifacts are running in both, the command prints nothing; add --show-unchanged to list the artifacts that are present in both.You can also diff two different environments to see what’s running in one but not the other:
The human-readable output you see above (tables, COMPLIANT/NON-COMPLIANT labels, history lines, etc.) is intended for people, not scripts. The exact wording, casing, and field labels may change between CLI versions to improve clarity or to stay aligned with the UI, and parsing this text in scripts or CI gates will silently break when it does.If you need to act on Kosli data programmatically — for example, to fail a pipeline when an artifact is non-compliant — use one of the stable interfaces instead:
Exit codes. Commands like kosli assert exit non-zero when the assertion fails, so you can branch on $? directly without parsing any output.
Structured output. Pass --output json to any get, list, search, or diff command and read the documented JSON fields (e.g. compliant) rather than grepping the text rendering.
As a rule of thumb: if you’re tempted to grep COMPLIANT or grep NON-COMPLIANT in a script, switch to the exit-code check or JSON field - it will keep working across CLI upgrades.
You have searched for an artifact by commit SHA, inspected a flow’s artifact list, fetched an artifact’s full history, browsed environment snapshots, and diffed two snapshots to see exactly what changed.From here you can:
