ketch

Documentation

How ketch resolves a name, picks a release asset and verifies it — plus the manifest schema, the registry layout and the source-plugin protocol.

ketch installs command-line tools and macOS apps directly from GitHub releases. Most of the time it needs nothing from you but a repository name — these pages cover the cases where it does, and the formats you would write when it does.

Installing

curl -fsSL https://raw.githubusercontent.com/listepo/ketch/main/install.sh | bash

On Windows:

irm https://raw.githubusercontent.com/listepo/ketch/main/install.ps1 | iex

Then put ~/.ketch/bin on your PATH (or %USERPROFILE%\.ketch\bin on Windows). ketch doctor reports whether it is, along with anything else that needs attention.

Everyday use

ketch install listepo/rtok           # any repo that publishes releases
ketch install rg                     # or a name the registry knows
ketch install sharkdp/fd@v10.2.0     # or an exact version
ketch upgrade                        # everything unpinned
ketch uninstall rg                   # and away again

Everything lives under ~/.ketch: versioned payloads in store/, links in bin/, and a state.json recording what is installed. Nothing is written outside that tree except .app bundles, which belong in /Applications.

How a name is resolved

Four tiers, in order — the first that answers wins:

  1. your own manifests in ~/.ketch/manifests/
  2. the fetched package registry
  3. the registry compiled into the binary, so common tools work offline
  4. inference from owner/repo

The last tier is the point of ketch: an uncurated repository is installable with no manifest at all. Inference picks the release asset matching your machine — architecture, OS and libc — and ketch info <pkg> --assets shows every candidate with the score it got and why.

Manifests

The package config: where a package comes from, which release asset to take, and what to expose once it is unpacked. Every field, and when you need one at all.

The package registry

One folder per package, one ketch.toml inside. How the registry is laid out, what ketch validates before trusting an entry, and how to add a package to it.

Source plugins

Install from GitLab, Gitea or an internal artifact server. A plugin is one executable that answers in JSON — the whole protocol, with a working example.

The lockfile

ketch.lock pins one machine's tools to exact releases: what it records, what reproduces on another machine and what does not, and how sync catches up.

Roadmap

What ketch does not do yet and what it would take: Linux and Windows backends, signature verification, man pages and shell completions.

Plan

What is being built next and in what order: platform backends, signature verification, registry validation and rollback, each with its exit criteria.

Contributing

The layout, the conventions and the trust boundaries — what to read before changing anything, and where each kind of change belongs.