---
name: Kosli
description: Use when building compliance automation for software delivery, tracking artifacts through CI/CD pipelines, reporting runtime environments, creating attestations for controls, enforcing policies on deployments, or querying audit trails. Agents should reach for this skill when users need to set up compliance tracking, create flows and trails, attest artifacts, manage environments, define policies, or verify deployment compliance.
metadata:
    mintlify-proj: kosli
    version: "1.0"
---

# Kosli Skill Reference

## Product summary

Kosli is a compliance automation platform that consolidates evidence from CI/CD pipelines, runtime environments, and business processes into immutable audit trails. It models software delivery as **Flows** (repeatable processes), **Trails** (individual executions), **Artifacts** (deliverables identified by SHA256 fingerprint), and **Attestations** (evidence that controls ran). Agents use the Kosli CLI, REST API, or Terraform provider to report events, define compliance requirements via policies and flow templates, and enforce gates on deployments. Key entry points: CLI at `kosli` command, API at `https://app.kosli.com/api/v2` (EU) or `https://app.us.kosli.com/api/v2` (US), Terraform provider at `kosli-dev/kosli`. Authentication requires an API token (personal or service account).

## When to use

Reach for this skill when:
- A user needs to set up compliance tracking for a CI/CD pipeline or software delivery process
- Creating or managing Flows, Trails, Artifacts, or Attestations
- Reporting runtime environment snapshots (Kubernetes, ECS, Lambda, Docker, S3, etc.)
- Defining or attaching environment policies to enforce compliance requirements
- Blocking non-compliant artifacts from deploying via `kosli assert artifact`
- Querying artifact history, environment snapshots, or deployment records
- Setting up Terraform-managed Kosli resources (environments, policies, flows)
- Integrating Kosli into GitHub Actions, GitLab CI, or other CI/CD systems
- Downloading audit packages or evidence for compliance investigations

## Quick reference

### Essential CLI commands

| Task | Command |
|------|---------|
| Create a flow | `kosli create flow <name> --template-file <file.yml>` |
| Begin a trail | `kosli begin trail <trail-id> --flow <flow-name>` |
| Attest an artifact | `kosli attest artifact <image> --artifact-type docker --flow <flow> --trail <id> --name <name>` |
| Attest a test result | `kosli attest junit <file.xml> --flow <flow> --trail <id> --name <name>` |
| Attest a security scan | `kosli attest snyk <file.json> --flow <flow> --trail <id> --name <name>` |
| Create an environment | `kosli create environment <name> --type kubernetes` |
| Snapshot an environment | `kosli snapshot k8s --environment <name>` |
| Create a policy | `kosli create policy <name> <policy.yml>` |
| Attach policy to environment | `kosli attach-policy <policy-name> --environment <env-name>` |
| Assert artifact compliance | `kosli assert artifact <image> --artifact-type oci --environment production` |
| Search for an artifact | `kosli search <commit-sha>` |
| Get artifact history | `kosli get artifact <flow>:<commit-sha>` |
| List environment snapshots | `kosli list snapshots <environment-name>` |
| Compare snapshots | `kosli diff snapshots <env-name> <env-name~1>` |

### Configuration precedence

CLI flags can be set in three ways (highest to lowest precedence):
1. Command-line flags: `--api-token`, `--org`, `--flow`, etc.
2. Environment variables: `KOSLI_API_TOKEN`, `KOSLI_ORG`, `KOSLI_FLOW`, etc.
3. Config file: `~/.kosli/config.yml` (set via `kosli config`)

### Artifact types

| Type | Use case |
|------|----------|
| `docker` | Docker images (requires image in registry) |
| `oci` | Container images fetched directly from registry |
| `file` | Single file artifacts (binaries, JARs) |
| `dir` | Directory artifacts |

### Environment types

Kubernetes, Docker, ECS, Lambda, S3, Azure Web Apps, Cloud Run, server (paths)

### Attestation types

- `pull-request` — GitHub, GitLab, Bitbucket, Azure DevOps PRs
- `junit` — JUnit test results
- `snyk` — Snyk security scans
- `sonar` — SonarQube scan results
- `jira` — Jira issue references
- `custom` — Custom types with jq evaluation rules
- `generic` — Generic attestations (less sophisticated than custom)

## Decision guidance

| Scenario | Use | Why |
|----------|-----|-----|
| Automating compliance in CI/CD | `kosli attest` commands in pipeline | Captures evidence at build time; immutable records |
| Gating deployments on compliance | `kosli assert artifact --environment prod` | Fails pipeline if artifact violates policies |
| Tracking what's running in production | `kosli snapshot k8s` on schedule | Detects drift and shadow changes; links to build trail |
| Defining required controls per flow | Flow Template YAML | Declarative, version-controlled, enforced automatically |
| Defining required controls per environment | Environment Policy YAML | Allows conditional rules (e.g., only for high-risk flows) |
| Personal scripts or testing | Personal API key | Tied to your user; simpler setup |
| CI/CD pipelines or automation | Service account API key | Scoped to org; no personal permission leakage |
| Managing Kosli resources as code | Terraform provider | Version-controlled; integrates with IaC workflows |
| Querying artifact history | `kosli get artifact` or `kosli search` | Direct CLI; use `--output json` for scripts |
| Downloading evidence for audits | `kosli get artifact` then download audit package | Immutable, timestamped evidence |

## Workflow

### Set up a new flow with compliance tracking

1. **Create the flow** with a template defining required attestations:
   ```bash
   kosli create flow backend-ci --template-file .kosli.yml
   ```
   Template specifies artifact names and required attestations (tests, scans, reviews).

2. **Begin a trail** for each build (typically at CI start):
   ```bash
   kosli begin trail $(git rev-parse HEAD) --flow backend-ci
   ```

3. **Attest artifacts and evidence** as pipeline steps run:
   ```bash
   kosli attest junit test-results.xml --flow backend-ci --trail $(git rev-parse HEAD) --name backend.unit-tests
   kosli attest artifact my-app:latest --artifact-type docker --flow backend-ci --trail $(git rev-parse HEAD) --name backend
   ```

4. **Assert compliance before deployment**:
   ```bash
   kosli assert artifact my-app:latest --artifact-type oci --environment production
   ```
   Exits non-zero if non-compliant; pipeline fails.

### Set up runtime compliance monitoring

1. **Create an environment** matching your runtime:
   ```bash
   kosli create environment prod-k8s --type kubernetes
   ```

2. **Define a policy** specifying what artifacts may run:
   ```yaml
   # prod-policy.yml
   artifacts:
     provenance:
       required: true
     attestations:
       - name: unit-tests
         type: junit
       - name: security-scan
         type: snyk
   ```

3. **Attach the policy** to the environment:
   ```bash
   kosli create policy prod-requirements prod-policy.yml
   kosli attach-policy prod-requirements --environment prod-k8s
   ```

4. **Schedule environment snapshots** (e.g., via cron or Helm chart):
   ```bash
   kosli snapshot k8s --environment prod-k8s
   ```
   Kosli automatically evaluates compliance and flags violations.

### Query and investigate

1. **Search for an artifact** by commit SHA:
   ```bash
   kosli search abc123def
   ```

2. **Get full artifact history**:
   ```bash
   kosli get artifact backend:abc123def
   ```

3. **List environment snapshots**:
   ```bash
   kosli list snapshots prod-k8s
   ```

4. **Compare two snapshots** to see what changed:
   ```bash
   kosli diff snapshots prod-k8s prod-k8s~1
   ```

## Common gotchas

- **Docker artifact type requires registry push**: `kosli attest artifact` with `--artifact-type docker` fails if the image has only been built locally. Push to a registry first or use `--artifact-type oci` to fetch the digest directly from the registry.

- **Attestations before artifacts exist**: You can attest evidence (tests, scans) before the artifact is built by using the artifact's template name (e.g., `backend.unit-tests`) instead of a fingerprint. Kosli binds it to the real fingerprint later when the artifact is reported. Order does not matter.

- **Flow templates are immutable**: Updating a template creates a new version. Earlier compliance evaluations (e.g., in snapshots) are not retroactively changed.

- **Attestations are append-only**: Reporting the same attestation twice creates two records; only the latest is used for compliance evaluation. You cannot delete or edit attestations.

- **Environment compliance is "Unknown" by default**: New environments have no policies attached, so compliance cannot be evaluated. Attach at least one policy to enable compliance checking.

- **Policy attachment triggers re-evaluation**: Attaching or detaching a policy immediately evaluates the latest snapshot and creates a new one with updated compliance status.

- **API token shown once**: When creating an API key (personal or service account), the token is displayed once and cannot be retrieved later. Copy it immediately to your secret store.

- **Fingerprints are immutable**: Artifacts are identified by SHA256 fingerprint, not by name or tag. A `latest` tag can point to different images, but the fingerprint uniquely identifies a specific build.

- **Service accounts inherit no permissions by default**: Create a service account and explicitly assign it a role (Member, Admin, Snapshotter) before it can perform actions.

- **Dry-run mode doesn't send data**: Use `--dry-run` to test commands without contacting Kosli. The CLI prints the payload and exits with code 0.

- **Parsing CLI output in scripts breaks**: Human-readable output (tables, `COMPLIANT` labels) may change between versions. Use `--output json` and check exit codes instead.

## Verification checklist

Before submitting work with Kosli:

- [ ] Flow is created with a template (or explicitly with `--use-empty-template` if no template needed)
- [ ] Trail is begun before attestations are reported
- [ ] Artifact fingerprint is correct (use `--dry-run` to verify)
- [ ] All required attestations per template are reported (check with `kosli get trail`)
- [ ] Artifact is compliant before deployment (run `kosli assert artifact` locally)
- [ ] Environment is created with correct type (matches runtime: K8S, ECS, Lambda, etc.)
- [ ] Policy is attached to environment (check with `kosli get environment`)
- [ ] Service account has correct role for the task (Member for attestations, Snapshotter for snapshots)
- [ ] API token is stored securely (use CI/CD secrets, not hardcoded)
- [ ] Snapshot reports what you expect (run `kosli get snapshot <env>#<number>` to verify)
- [ ] Compliance status is as expected (check `kosli get artifact` or `kosli get environment`)

## Resources

- **Comprehensive page listing**: [https://docs.kosli.com/llms.txt](https://docs.kosli.com/llms.txt) — full navigation of all documentation pages for agent reference
- **Getting started**: [https://docs.kosli.com/getting_started/install](https://docs.kosli.com/getting_started/install) — CLI installation and configuration
- **How Kosli works**: [https://docs.kosli.com/understand_kosli/how_kosli_works](https://docs.kosli.com/understand_kosli/how_kosli_works) — conceptual overview of Flows, Trails, Artifacts, Attestations, Environments
- **CLI reference**: [https://docs.kosli.com/client_reference/overview](https://docs.kosli.com/client_reference/overview) — all CLI commands and flags
- **API reference**: [https://docs.kosli.com/api-reference](https://docs.kosli.com/api-reference) — REST API endpoints
- **Terraform provider**: [https://docs.kosli.com/terraform-reference/index](https://docs.kosli.com/terraform-reference/index) — managing Kosli resources as code
- **CI/CD integrations**: [https://docs.kosli.com/integrations/ci_cd](https://docs.kosli.com/integrations/ci_cd) — GitHub Actions, GitLab CI, Azure DevOps, etc.

---

> For additional documentation and navigation, see: https://docs.kosli.com/llms.txt