Skip to main content
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.

​
Prerequisites

​
Setup

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.

​
Search by commit SHA

If you have a git commit SHA, kosli search will find any artifact built from it:
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.

​
List flows and artifacts

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:
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:
By default, the last 15 artifacts are shown. Use to change how many are shown, to paginate, and to change the format.

​
Get an artifact

The artifact list gives you commit SHAs and fingerprints. Use either to fetch the full history of a specific artifact — the syntax is :

​
Browse environment snapshots

The artifact history shows it was deployed to aws-beta and aws-prod. To explore those environments, start by listing what Kosli knows about them:
To browse the history of changes in an environment:
To see what was running in a specific snapshot, for example #8339, where the creator artifact above started running:
You can also reference snapshots relatively — aws-beta~1 means one behind the current snapshot, aws-beta~19 means 19 behind.

​
Compare snapshots

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:
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:

​
Don’t parse the raw CLI output

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.

​
What you’ve accomplished

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:
Last modified on September 14, 2026