From a3ca108e1cc083eaac85237b857d5a4711a6f8b1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 14:52:05 +0000 Subject: [PATCH 1/3] docs: advise against parsing raw CLI output in querying tutorial --- tutorials/querying_kosli.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tutorials/querying_kosli.md b/tutorials/querying_kosli.md index 7ac46c2..6a10d63 100644 --- a/tutorials/querying_kosli.md +++ b/tutorials/querying_kosli.md @@ -195,6 +195,17 @@ You can also diff two different environments to see what's running in one but no kosli diff snapshots aws-beta~3 aws-prod ``` +## 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 INCOMPLIANT` in a script, switch to an exit-code check or a 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 4eda304755530195a3f1a8224d089088ba19f1a9 Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Wed, 24 Jun 2026 16:03:41 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- tutorials/querying_kosli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/querying_kosli.md b/tutorials/querying_kosli.md index 6a10d63..34a7d9b 100644 --- a/tutorials/querying_kosli.md +++ b/tutorials/querying_kosli.md @@ -204,7 +204,7 @@ If you need to act on Kosli data programmatically — for example, to fail a pip * **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 INCOMPLIANT` in a script, switch to an exit-code check or a JSON field — it will keep working across CLI upgrades. +As a rule of thumb: if you're tempted to `grep COMPLIANT` or `grep NON-COMPLIANT` in a script (or `INCOMPLIANT` — yes, the label has changed), switch to an exit-code check or a JSON field — it will keep working across CLI upgrades. ## What you've accomplished From 5dbca542b5aea5f7aeb98cab01fa8451059be10e Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Wed, 24 Jun 2026 16:04:36 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Marko Bevc --- tutorials/querying_kosli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/querying_kosli.md b/tutorials/querying_kosli.md index 34a7d9b..0684689 100644 --- a/tutorials/querying_kosli.md +++ b/tutorials/querying_kosli.md @@ -204,7 +204,7 @@ If you need to act on Kosli data programmatically — for example, to fail a pip * **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 (or `INCOMPLIANT` — yes, the label has changed), switch to an exit-code check or a JSON field — it will keep working across CLI upgrades. +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