---
name: kit
description: >
  Use the `kit` command-line tool. kit is a content-addressed version control
  system with BLAKE3 object IDs, Ed25519-signed commits and signed attestations.
  Use this skill when you work in a `.kit/` repository, make signed commits,
  manage signing keys, create or verify attestations, or push and pull over
  `kit+file`, `kit+ssh`, `kit+https` and `kit+s3` remotes. kit follows Git
  where it can. This skill covers the parts that differ.
---

# kit

kit is a version control tool like Git. Every commit carries an Ed25519
signature. kit names every object by its BLAKE3 hash. A commit can carry
attestations: in-toto v1 Statements in DSSE envelopes.

If you know Git, you know `add`, `commit`, `log`, `branch`, `merge`, `rebase`,
`stash`, `diff` and `status`. Read the differences below before you start.

## Set up

Install kit and check the version.

```sh
curl -sSfL https://kit.storage/install.sh | sh
kit version          # prints: kit <X.Y.Z>
```

The installer needs `cosign` in `PATH`. It supports Linux and macOS. On
Windows, use WSL.

Start a repository and make the first signed commit.

```sh
kit init
kit keygen
echo hello > hi.txt
kit add hi.txt
kit commit -m "first commit"
kit log
```

Always pass `-m` or `-F` to `kit commit`. Without them, kit opens an editor and
waits. kit always signs commits. Run `kit keygen` before the first commit.

## What differs from Git

1. Object IDs are 64-digit hex BLAKE3 hashes. A Git SHA does not resolve.
2. The repository marker is `.kit/`, not `.git/`.
3. A command that loses data refuses to run without `-f`. This covers
   `reset --hard` and `clean`. `clean` accepts `-n` to preview.
4. Human output goes to stderr. Stdout carries only data, such as
   `--porcelain` output or `--format=json` output. Read stderr to see a
   summary.
5. By default, kit derives the author of a commit from the public key of your
   signing key. You do not configure it.
6. `kit clone --depth N` is rejected.

## Sign and verify

```sh
kit keygen --print-pubkey     # prints ed25519:<hex>
kit verify HEAD               # check the signature on a commit
kit verify HEAD --trusted     # also check the signer against your trust roots
```

`kit verify` alone proves that the key inside the commit made the signature. It
does not prove that you trust that key. Use `--trusted` for that.

## Attest to a commit

An attestation is a signed statement about a commit. The commit hash is the
subject.

```sh
kit attest --predicate-type https://example.com/sign-off/v1
kit trust add ed25519:<hex> <hex>     # trust a key: <keyid> <pubkey-hex>
kit verify-attest
```

`kit verify-attest` trusts only the keys in your user-level trust-roots file.
It refuses a trust-roots file inside the repository unless you pass the path
with `--trust-roots`. kit does not give meaning to a predicate. The consumer
decides what it means.

## Share work

The URL scheme picks the transport. kit never tries another transport.

```sh
kit remote add origin kit+file:///srv/kit/my-repo
kit push origin
kit clone kit+file:///srv/kit/my-repo my-copy
```

Prefer `--force-with-lease` to `--force` when you must overwrite a remote ref.

## Exit codes

Scripts can tell failures apart. `0` is success. `64` is a usage error. `65`
is malformed input. `69` is a transport that could not connect. `75` is a
temporary failure that is safe to retry. `77` is permission denied.
`78` is a config error.

## Read more

- Every command: https://github.com/officialunofficial/kit/blob/main/docs/CLI.md
- Git users: https://github.com/officialunofficial/kit/blob/main/docs/GUIDE-GIT-WORKFLOWS.md
- Verify a commit without the repository: https://github.com/officialunofficial/kit/blob/main/docs/VERIFY.md
- Formats and protocols: https://kit.storage/specs