ketch documentation

Catch releases straight from GitHub.

ketch installs command-line tools and apps from GitHub releases on macOS, Linux, and Windows. It picks the release asset built for your machine, checks the checksum the project published, unpacks it into a versioned store, and links it onto your PATH.

Start with Getting started About ketch

19 pages from pyrlyn/ketch/docs at 4e43843, in development

Install

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

02 First tool
```
ketch install BurntSushi/ripgrep
```
03 Lock
```
ketch lock
```
04 Reproduce
```
ketch sync
```

How it works

From install to first result.

1
Resolve

Point it at owner/repo, a name from the registry, or an exact version. ketch why explains a resolution without installing.
```
ketch install sharkdp/[email protected]
```
2
Verify

Published SHA-256 sums are checked against what landed on disk. require_checksums refuses anything that publishes none.
```
ketch install --require-checksum rg
```
3
Link

The payload is unpacked into a versioned store under ~/.ketch and linked onto your PATH; an .app bundle goes to /Applications.
```
ketch list
```
4
Undo or reproduce

An upgrade keeps the previous version on disk; ketch rollback relinks it without re-downloading. ketch lock and ketch sync reproduce a machine.
```
ketch rollback rg
```

One tree

Everything lives under ~/.ketch.

Versioned payloads in store/, links in bin/, a state.json recording what is installed, and a stats.db recording what happened. Nothing is written outside that tree except the .app bundles that belong in /Applications and the files you ask for, such as ./ketch.lock.

state.json says what is installed now; stats.db is the append-only other half, which is why ketch history rg still works after ketch uninstall rg.

~/.ketch/
├── store/       versioned payloads
├── bin/         links onto your PATH
├── state.json   what is installed now
└── stats.db     what happened, and when

Layout described in the ketch README

Paths into the docs

Pick where to go next.

What you can install

Five ways to name a package.

Reference	What it means
`BurntSushi/ripgrep`	Any repository that publishes releases
`rg`	A name ketch already knows from the registry
`sharkdp/[email protected]`	An exact version
`--path ./mytool`	A local binary, archive, symlink, or `.app`
`local:/abs/or/rel`	The same thing, as a package ref

Questions the docs answer

Good to know.

Can I install from GitLab or an internal server?

Yes. GitHub is built in; anything else is a source plugin — an executable named ketch-source-<scheme> that ketch runs with a subcommand and that answers with one JSON document. No recompile and no ketch release needed.

How do I set up a new machine the same way?

ketch lock writes ./ketch.lock from what is installed. Commit it next to your dotfiles; ketch sync makes another machine match it, and ketch lock --check tells you whether anything has drifted.

What is the registry?

An ordinary GitHub repository. Every top-level folder is a package and holds one ketch.toml describing it.

How do I remove ketch again?

ketch self uninstall removes every package ketch installed, the whole ~/.ketch tree and the PATH block it added. It lists what it is about to delete and asks first; --keep-packages removes only ketch.

Next steps

Catch releases straight from GitHub.

Resolve

Verify

Link

Undo or reproduce

Everything lives under ~/.ketch.

Five ways to name a package.