From ddd38d7cfe1d98c93085339f3144045bdd3e6459 Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:41 +0100 Subject: [PATCH 1/6] docs: add installation and overview sections to README Expand the minimal root README into a proper front door for the repo: - Turn the one-line description into a short "what it does" overview listing the CLI's key capabilities (fingerprinting, attestations, environment snapshots, compliance assertions). - Add an Installation section with copy-paste blocks for the shell installer, Homebrew, `npm`, Docker, and building from source, plus a note on the available deb/rpm packages. - Keep the existing badges and the four reference links, and continue to link out to the docs site, developer guide, and public trails rather than duplicating them. --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c23e96a20..684d3fa1e 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,69 @@ # Kosli CLI -This repo contains the Kosli CLI, for recording and querying software delivery events to [Kosli](www.kosli.com). +The Kosli CLI records and queries software delivery events with [Kosli](https://www.kosli.com), giving you a tamper-evident record of how your software was built, tested, and deployed. -Some useful links: +With it you can: + +* **Fingerprint artifacts** — compute the SHA256 of files, directories, and OCI/Docker images. +* **Record attestations and evidence** — bind test results, security scans (Snyk, SonarQube), pull-request approvals, Jira issues, and custom evidence to your flows and trails. +* **Snapshot running environments** — report what is actually running in Kubernetes, ECS, Lambda, S3, Docker, Azure Web Apps, GCP Cloud Run, servers, and filesystem paths. +* **Query and assert compliance** — search and diff snapshots, and gate your CI/CD pipelines with `kosli assert` commands. + +See the [documentation site](https://docs.kosli.com/) for the full command reference and usage guides. + +## Installation + +Install with whichever method suits your platform. After installing, run `kosli version` to verify. + +### Install script (Linux / macOS) + +```sh +curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh +``` + +The script detects your OS and architecture and installs the matching release binary into a directory on your `PATH`. To install a specific version, pass the tag as an argument: + +```sh +curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh -s -- v2.35.0 +``` + +### Homebrew (macOS / Linux) + +```sh +brew install kosli-cli +``` + +Upgrade later with `brew upgrade kosli-cli`. + +### npm + +```sh +npm install -g @kosli/cli +``` + +> `npx @kosli/cli` is **not** supported — `npx` skips the optional platform dependency, so install the package first. + +### Docker + +```sh +docker run --rm ghcr.io/kosli-dev/cli:v2.35.0 version +``` + +Images are published to `ghcr.io/kosli-dev/cli` for each release tag. + +### Build from source + +```sh +make build # produces ./kosli +./kosli version +``` + +See the [developer guide](/dev-guide.md) for full build details, including Windows. + +`.deb` and `.rpm` packages are also published for each release. See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options. + +## Documentation and links * [Documentation site](https://docs.kosli.com/) for full details on usage. * [Developer guide](/dev-guide.md) for details on working with the code in this repo. From 09bf530aab9bebe1d7fccfc8c85f9e188f298ffb Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:43 +0100 Subject: [PATCH 2/6] docs: reorder PR template --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ac57c18b8..64bfd2e6f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,6 +2,6 @@ ### Checklist +- [ ] **Docs** are autogenerated from CLI help — make sure the help text reflects your changes - [ ] **Helm chart** (`charts/k8s-reporter/`) updated, if needed. Note: these changes live in a **separate PR** - [ ] **Terraform provider** and related changes ([terraform-provider-kosli](https://github.com/kosli-dev/terraform-provider-kosli), [terraform-aws-evidence-reporter](https://github.com/kosli-dev/terraform-aws-evidence-reporter), [terraform-aws-kosli-reporter](https://github.com/kosli-dev/terraform-aws-kosli-reporter)) updated, if needed -- [ ] **Docs** are autogenerated from CLI help — make sure the help text reflects your changes From f65fbf97042ec423490189cd4c63e5a4832ce1aa Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:44 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Marko Bevc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 684d3fa1e..3e5b6e948 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | The script detects your OS and architecture and installs the matching release binary into a directory on your `PATH`. To install a specific version, pass the tag as an argument: ```sh -curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh -s -- v2.35.0 +curl -sSL https://raw.githubusercontent.com/kosli-dev/cli/main/install-cli.sh | sh -s -- v ``` ### Homebrew (macOS / Linux) From f360b7a3da6dcae68f4e79477c9728b523ea403b Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:45 +0100 Subject: [PATCH 4/6] Apply suggestion from @mbevc1 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e5b6e948..a4bbe5d38 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ npm install -g @kosli/cli ### Docker ```sh -docker run --rm ghcr.io/kosli-dev/cli:v2.35.0 version +docker run --rm ghcr.io/kosli-dev/cli:v version ``` Images are published to `ghcr.io/kosli-dev/cli` for each release tag. From 38c4ef471af0829c208ce89dcc4940c8488061c8 Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:46 +0100 Subject: [PATCH 5/6] docs: add GitHub Releases install option to README Document downloading a prebuilt binary directly from the GitHub Releases page, for users who don't want the install script, a package manager, Docker, or a source build. Includes a Linux amd64 example and the archive naming convention, and points the deb/rpm note at the Releases page where those assets are attached. --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a4bbe5d38..b9ab35f02 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,18 @@ docker run --rm ghcr.io/kosli-dev/cli:v version Images are published to `ghcr.io/kosli-dev/cli` for each release tag. +### Download a release binary + +Every release ships prebuilt archives, `.deb`/`.rpm` packages, and checksums on the [GitHub Releases](https://github.com/kosli-dev/cli/releases) page. Download the archive for your OS and architecture, extract it, and move the `kosli` binary onto your `PATH`. For example, on Linux amd64: + +```sh +curl -L https://github.com/kosli-dev/cli/releases/download/v/kosli__linux_amd64.tar.gz | tar xz +sudo mv kosli /usr/local/bin/ +kosli version +``` + +Archive names follow `kosli___.tar.gz` for Linux and macOS, and `kosli__windows_.zip` for Windows. + ### Build from source ```sh @@ -65,7 +77,7 @@ make build # produces ./kosli See the [developer guide](/dev-guide.md) for full build details, including Windows. -`.deb` and `.rpm` packages are also published for each release. See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options. +`.deb` and `.rpm` packages are attached to each [GitHub Release](https://github.com/kosli-dev/cli/releases). See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options. ## Documentation and links From c878b8c2d43b6abdf9b710c0bd3fa085a7ff9a5f Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Jul 2026 16:42:47 +0100 Subject: [PATCH 6/6] docs: fold orphaned deb/rpm note into release-binary section The trailing .deb/.rpm + install-docs note sat under "Build from source" and duplicated the .deb/.rpm mention already in "Download a release binary". Move the install-docs link into the release-binary section and drop the orphaned paragraph so Build from source ends at its developer- guide pointer. --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index b9ab35f02..374b5502e 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ sudo mv kosli /usr/local/bin/ kosli version ``` -Archive names follow `kosli___.tar.gz` for Linux and macOS, and `kosli__windows_.zip` for Windows. +Archive names follow `kosli___.tar.gz` for Linux and macOS, and `kosli__windows_.zip` for Windows. See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options. ### Build from source @@ -77,8 +77,6 @@ make build # produces ./kosli See the [developer guide](/dev-guide.md) for full build details, including Windows. -`.deb` and `.rpm` packages are attached to each [GitHub Release](https://github.com/kosli-dev/cli/releases). See the [install docs](https://docs.kosli.com/getting_started/install/) for the complete list of options. - ## Documentation and links * [Documentation site](https://docs.kosli.com/) for full details on usage.