Команды — ketch docs

Все команды ketch в одном месте: что делает каждая, какую форму принимает и один рабочий пример. PKG ниже — установленное имя, алиас или owner/repo; большинство команд, принимающих его, также допускают @version в конце (sharkdp/[email protected]). Глобальные флаги работают везде: --root <DIR> указывает на другое дерево ketch, -v/--verbose показывает, что делает ketch, -q/--quiet печатает только ошибки и запрошенные данные, --no-color отключает цвет, а --no-emoji убирает значки перед строками статуса.

Значки. В терминале каждая строка статуса начинается со значка того, о чём она сообщает: 📦 установка, ⏫ обновление пакета или реестра, 🧹 удаление, ⏬ загрузка, 🔗 ссылка, ⏪ откат, 🔍 поиск, 🩺 doctor, а в остальных случаях ✅ успех, ❗ предупреждение, ❌ ошибка, 💡 примечание. По умолчанию они включены (emoji в config.toml, KETCH_EMOJI) и никогда не появляются в пайпе или файле, при TERM=dumb, в выводе --json или --names-only, в табличных данных и в логе.

Установка и удаление

`ketch install [PKG]... [options]`

Устанавливает один или несколько пакетов. Вывод выбирает ассет релиза, подходящий хосту (архитектура, ОС, libc); манифест или --asset говорят, что делать вместо этого.

ketch install BurntSushi/ripgrep  # любой репозиторий, публикующий релизы
ketch install rg                  # или имя, известное реестру
ketch install sharkdp/[email protected]  # или точная версия
ketch install --path ./mytool     # локальный бинарник, архив, симлинк или .app

Уже установленный пакет не обновляется у вас за спиной. Если есть более новый релиз, install спрашивает <pkg> <installed> is installed; update to <latest>? (по умолчанию нет) и при ответе «да» обновляет его так же, как ketch upgrade; --yes отвечает «да», а без терминала команда останавливается с кодом 5 и предлагает передать --yes или запустить ketch upgrade. Если ничего новее нет, она завершается с кодом 5: cannot install <pkg>: <version> is already installed and no update is available (--force переустанавливает). Точная версия ([email protected]) и закреплённый пакет ведут себя как раньше.

Опции: --path <PATH> устанавливает локальный файл (эквивалент local:<PATH>); --name <NAME> задаёт имя установки для одного пакета; --force/-f переустанавливает запрошенную версию, даже если она уже есть; --pre учитывает пре-релизы и оставляет пакет на них: дальше upgrade, outdated и list ищут пре-релизы без --pre, а info показывает channel: pre (точный тег пре-релиза, [email protected], делает то же; обычная установка возвращает пакет на stable); --draft учитывает и черновики релизов GitHub, вместе с пре-релизами, и оставляет пакет на черновиках (channel: draft); pkg@<tag> --draft находит черновик по тегу, который он получит. GitHub показывает черновики только токену с правом push в репозиторий (KETCH_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN или github_token), поэтому без него --draft останавливается с этой причиной; файлы черновика скачиваются через API с токеном и проверяются как любые другие. У других источников черновиков нет, и они отклоняют --draft; --no-link распаковывает без ссылок в PATH; --require-checksum отклоняет релизы без опубликованной контрольной суммы; --asset <NAME> берёт один файл релиза по точному имени (спрашивает подтверждение, потому что проверка платформы пропускается); -j/--jobs <N> и -y/--yes управляют параллелизмом и вопросами. Алиас — ketch i.

Тег, который не является версией (nightly, dev, canary, edge), — плавающий: проект переопубликует его под тем же именем. pkg@nightly устанавливает его на channel: dev и записывает полученную сборку — дайджест ассета и время публикации. Повторная установка того же тега даёт already installed, пока тег не укажет на другую сборку, а тогда берёт новую.

Когда релиз содержит несколько бинарников с именем пакета и ни один манифест не называет нужный, ссылка ставится только на один из них: тот, что назван в --bin <NAME>; иначе — бинарник, названный в точности как пакет; иначе — выбор, запомненный с прошлого раза (в state.json, а при ketch sync — в ketch.lock), или выбор по номеру в терминале. Бинарники с другими именами получают ссылки как обычно. С --yes или без терминала выбора нет, и установка завершается ошибкой со списком кандидатов — см. раздел bin в MANIFESTS.md.

--bin <NAME> (для одного пакета) отвечает на этот вопрос заранее, поэтому работает без терминала: ketch install owner/rtok --bin rtok-cli. Он сохраняется в state.json, как выбор из списка, и используется при последующих обновлениях. Он завершается ошибкой, если ни у одного бинарника релиза нет такого имени и если в манифесте пакета уже есть bin (тогда измените его).

`ketch uninstall <NAME>...`

Удаляет установленные пакеты. Имена разрешаются как в install (установленное имя, бинарник или owner/repo); опечатка останавливает команду до того, как что-либо будет удалено. Удаляется вся папка пакета в хранилище, включая всё, что там оставило прерванное обновление. Для неустановленного имени печатается <name>: not found и возвращается код 4; перечисляется каждое отсутствующее имя, и ничего не удаляется.

ketch uninstall rg
ketch uninstall fd ripgrep --yes  # пропустить подтверждение

Алиасы — ketch remove и ketch rm.

`ketch upgrade [NAME]...`

Обновляет установленные пакеты до последнего релиза. Без аргументов — все незакреплённые пакеты. Показывает таблицу from -> to, спрашивает, затем устанавливает.

Каждая версия распаковывается в собственную новую папку, так что ничто из поставки старой версии не может задержаться в новой, а остатки прерванного обновления сначала удаляются — или обновление останавливается и называет их. Папка предыдущей версии хранится рядом для ketch rollback до ketch prune.

ketch upgrade              # всё незакреплённое
ketch upgrade ripgrep fd   # только эти
ketch upgrade --dry-run    # показать план, ничего не меняя

Опции: --pre учитывает пре-релизы; --draft учитывает и черновики релизов GitHub (пакет, установленный с --draft, обходится без него). Опубликованный черновик — это обновление до релиза под его тегом; удалённый черновик — предупреждение. Пакет на плавающем теге (channel: dev) следует за этим тегом: обновление — это тег, указывающий на другую сборку, что решает дайджест ассета, а если источник его не даёт — время публикации релиза; более новая версия под другим тегом обновлением не является. --force обновляет и закреплённые пакеты; --bin <NAME> (ровно для одного пакета) выбирает, на какой бинарник ставить ссылку, когда новый релиз содержит несколько файлов с именем пакета, как в install; -j/--jobs <N>, -y/--yes. Закреплённые пакеты и пакеты local: пропускаются, если не указан --force.

`ketch rollback <PKG> [--to <VERSION>]`

Переключает пакет обратно на версию, которая ещё лежит на диске. Без --to восстанавливает предыдущую сохранённую версию.

ketch rollback ripgrep
ketch rollback rg --to 14.1.0

`ketch prune [NAME]... [--keep <N>]`

Удаляет сохранённые старые версии согласно политике хранения. Без аргументов — все установленные пакеты. --keep <N> обновляет сохранённую политику.

ketch prune
ketch prune ripgrep --keep 2

`ketch pin <NAME>...` / `ketch unpin <NAME>...`

Закрепляет пакет на текущей версии (pin) или снимает закрепление (unpin). Закреплённые пакеты пропускаются командой upgrade, если не передан --force.

ketch pin ripgrep
ketch upgrade --force        # обновляет и закреплённые пакеты
ketch unpin ripgrep

`ketch link <NAME>...` / `ketch unlink <NAME>...`

Заново создаёт (link) или удаляет (unlink) ссылки в каталоге bin для установленного пакета. unlink оставляет содержимое установленным; upgrade сохраняет состояние ссылок.

ketch unlink ripgrep   # оставить, но убрать из PATH
ketch link ripgrep     # вернуть обратно

`ketch import winget|brew|linux <NAME> [--dry-run] [--yes]`

Добавляет пакет, который уже знает другой пакетный менеджер. ketch читает его описание, превращает его в пользовательский манифест ~/.ketch/manifests/<name>.toml и устанавливает обычным путём, с ассетом и контрольной суммой из этого описания.

ketch import brew codex                    # cask Homebrew (или formula)
ketch import brew fly --cask               # искать только cask; --formula — только formula
ketch import winget BurntSushi.ripgrep.MSVC  # идентификатор winget, с учётом регистра
ketch import linux lazygit                 # Arch Linux, затем AUR
ketch import linux obsidian --dry-run      # напечатать манифест, ничего не меняя

Источник	Откуда берётся описание
`winget`	манифест установщика новейшей версии в winget-pkgs
`brew`	JSON cask или formula с formulae.brew.sh
`linux`	`.SRCINFO` пакета Arch Linux, либо пакета AUR с суффиксом `-bin`/`-appimage`, если Arch собирает его из исходников

Преобразуется только пакет, чьи загрузки — ассеты релиза GitHub (https://github.com/<owner>/<repo>/releases/download/...). Загрузка откуда-либо ещё — CDN вендора, SourceForge, исходный tarball, домашняя страница GitHub с файлами в другом месте или смесь — ничего не записывает и завершается с кодом 1 и сообщением <name> can't be converted: it is not distributed through GitHub Releases, and that is not supported yet. Так же и установщики, которые ketch не умеет запускать (.msi, .msix, Inno или NSIS .exe, .deb, .rpm), артефакты cask помимо приложения и бинарников (pkg, installer) и два файла на одну платформу.

Манифест хранит только то, что нужно ketch: name, source, kind для приложения, bin и по одному шаблону [asset.target] на платформу, где версия заменена на *, чтобы шаблон подходил и дальше. Он начинается со строки # Written by `ketch import …` ; файл с таким именем без этой строки — ваш, и import отказывается его заменять.

Повторный запуск безопасен: если преобразованный манифест и установленная версия уже совпадают с источником, печатается Everything is up to date и ничего не меняется. Новая версия выше по течению переписывает файл и обновляет пакет; изменившийся манифест при той же версии переустанавливает его.

Адреса каталогов можно перенаправить (зеркало или тестовый двойник) через KETCH_IMPORT_BREW, KETCH_IMPORT_WINGET_API, KETCH_IMPORT_WINGET_RAW, KETCH_IMPORT_ARCH, KETCH_IMPORT_ARCH_GITLAB и KETCH_IMPORT_AUR. Список winget идёт через GitHub API, поэтому используется токен GitHub, если он задан.

Просмотр

`ketch list`

ketch list [local|remote] [--json] [--names-only] [--pre] [--draft], алиас — ketch ls.

Показывает, что установлено, что предлагает реестр, или и то и другое в одной таблице с самой новой версией каждого пакета.

Команда	Показывает	Сеть
`ketch list local`	Установленные пакеты из записи об установке	Никогда
`ketch list remote`	Пакеты, которые предлагает реестр, с последней версией	Нужна; без неё ошибка
`ketch list`	И то и другое, по строке на пакет, с сортировкой по имени	Используется для `latest`; без неё — локальная часть

«Реестр» здесь — это локальная копия, которую загружает ketch update, плюс ваши собственные манифесты в ~/.ketch/manifests (ваши побеждают, если имя есть и там и там). Те немногие пакеты, что вкомпилированы в ketch как запасной вариант, не перечисляются; запустите ketch update, чтобы увидеть реестр, из которого они взяты.

Столбцы.

package — имя, по которому пакет устанавливают, обновляют или удаляют.
installed — установленная версия, а за ней канал, за которым следует пакет, если он не стабильный: (pre) — пре-релизы (установлен с --pre или из тега пре-релиза), (draft) — черновики GitHub (установлен с --draft), (dev) — плавающий тег вроде nightly; у пакета на стабильном канале по умолчанию пометки нет. (pinned) означает, что его удерживает ketch pin; (+N retained) означает, что N более ранних версий сохранены для ketch rollback. Пусто для неустановленного пакета.
latest — самый новый релиз источника пакета. За ним следует (update available), если это обновление для установленной версии. ? означает, что источник не ответил. Пусто для пакета, установленного из локального пути, у которого нет upstream, чтобы спросить.
source — откуда берётся пакет. Для установленного пакета это то, откуда он был установлен и откуда придёт его следующая версия.
description (только remote) — однострочное описание из реестра, обрезанное по ширине терминала (COLUMNS задаёт другую ширину; при выводе в пайп ничего не обрезается).

Маркеры. В ketch list у установленного пакета в первом столбце стоит *. В цветном терминале маркер — ●, имя выделено жирным, а (update available) — жёлтым. CLICOLOR_FORCE=1 включает цвет даже при выводе в пайп; --no-color и NO_COLOR выключают его.

Наличие обновления определяется тем же правилом, что в ketch outdated, для любого канала. latest — самый новый релиз, о котором сообщает источник пакета, из того же запроса, что делает ketch outdated: только стабильные релизы, если не указан --pre, не задано prerelease = true в config.toml или в манифесте пакета и пакет не установлен на канале pre; с --draft или на канале draft — ещё и черновики. Эта версия сравнивается с установленной, и учитывается только строго более новая; релиз с установленным тегом — нет, с двумя исключениями. Пакету на канале draft предлагается релиз, которым опубликован его черновик, под тем же тегом, а если черновик пропал, об этом выводится предупреждение. Пакет на канале dev ищется под своим собственным тегом, и latest показывает этот тег; новая сборка, опубликованная под ним, — это обновление. Закреплённому пакету обновление никогда не предлагается.

Закреплённые пакеты перечисляются с обеими версиями и (pinned), не получают (update available) и не попадают в итоговую строку. ketch unpin снова позволяет им обновляться.

Пакеты не из реестра — установленные из owner/repo или другой ссылки scheme:id — тоже перечисляются, и их latest берётся из их собственного источника. Пакет, установленный из локального пути (ketch install --path), показывается с пустым latest.

Под таблицей строка N updates available: ketch upgrade <names> называет каждый пакет с обновлением в виде команды, которая обновит их все.

Офлайн и пакеты, которые не отвечают. Последние версии запрашиваются параллельно (по jobs за раз, по умолчанию 4), а пока они загружаются, в stderr идёт счётчик. Источник, который не ответил, — упёрся в лимит, исчез, недоступен — показывает ? в latest, а под таблицей одна строка называет каждый такой пакет; все остальные строки всё равно печатаются, и команда всё равно завершается успешно. Когда не отвечает ни один источник, считается, что сети нет: ketch list печатает таблицу ketch list local, за ней latest: offline, и возвращает 0, а ketch list remote, которому без сети нечего показать, возвращает ненулевой код.

Ответы кешируются на 10 минут в ~/.ketch/cache/latest.json для каждого источника и каждого запрошенного канала (stable, pre, draft или собственный тег пакета dev), так что два вызова подряд обращаются к GitHub один раз. Файл кеша, записанный более старой версией ketch, игнорируется и заменяется. Кешируются только ответы, но не сбои. Удалите файл, чтобы спросить заново раньше; ketch outdated и ketch upgrade его никогда не читают.

--json печатает для каждого режима:

local — массив {"name", "installed", "channel", "pinned", "retained", "source"}, где retained — список версий, сохранённых для отката, а channel — канал релизов, за которым следует установка (stable, pre, draft или dev).
remote — массив {"name", "latest", "description", "source"}, где latest равно null для источника, который не ответил.
без режима — {"packages": [...], "unreachable": [...]}. Каждый пакет — {"name", "installed", "channel", "latest", "update_available", "pinned", "source"}; installed и channel равны null, если пакет не установлен, а latest равно null, если версия неизвестна. unreachable называет пакеты, чей latest неизвестен. Офлайн packages содержит только установленные пакеты.

--pre ищет пре-релизы при заполнении столбца latest для каждой строки, как ketch outdated --pre. В ketch list local он ничего не меняет: тот не спрашивает источники.

--draft ищет ещё и черновики релизов GitHub, а вместе с ними пре-релизы, в столбце latest установленных пакетов, как ketch outdated --draft. Строки реестра не затрагиваются: черновики видны только токену с правом push в репозиторий. Пакет, у источника которого черновиков нет, спрашивается без них, а без такого токена строка показывает ?.

--names-only печатает только имена, по одному на строку, для каждого режима; к сети он никогда не обращается.

Изменено в 0.7. Раньше ketch list показывал только установленные пакеты, а его --json был массивом записей об установке; теперь он показывает всё в описанном выше виде. Скриптам, которым нужны установленные пакеты, следует вызывать ketch list local. ketch list --installed — скрытый алиас ketch list local, сохранённый на один релиз.

$ ketch list local
package  installed        source
fd       v10.4.2          github:sharkdp/fd
ripgrep  14.1.1           github:BurntSushi/ripgrep
rtok     v0.9.0 (pinned)  github:pyrlyn/rtok

$ ketch list remote
package  latest   description
cox      v0.1.0   Modular terminal coding agent
ketch    v0.6.1   Catch releases straight from GitHub
ripgrep  15.2.0   Recursively search directories for a regex pattern
rtok     v0.10.0  Reduce the context AI coding agents must carry
runa     ?        Run AI models locally (GGUF via llama.cpp) or through the OpenAI and Anthropic APIs
swarfr   v0.1.0   Shrink Cargo target directories without slowing builds
? means the latest release could not be checked: runa

$ ketch list
   package  installed        latest                      source
   cox                       v0.1.0                      github:pyrlyn/cox
*  fd       v10.4.2          v10.5.0 (update available)  github:sharkdp/fd
   ketch                     v0.6.1                      github:pyrlyn/ketch
*  ripgrep  14.1.1           15.2.0 (update available)   github:BurntSushi/ripgrep
*  rtok     v0.9.0 (pinned)  v0.10.0                     github:pyrlyn/rtok
   runa                      ?                           github:pyrlyn/runa
   swarfr                    v0.1.0                      github:listepo/swarfr
2 updates available: ketch upgrade fd ripgrep
? means the latest release could not be checked: runa

Без сети:

$ ketch list
package  installed        source
fd       v10.4.2          github:sharkdp/fd
ripgrep  14.1.1           github:BurntSushi/ripgrep
rtok     v0.9.0 (pinned)  github:pyrlyn/rtok
latest: offline
$ ketch list remote
     error could not reach any package source to check the latest versions; `ketch list local` works offline

ketch list local --json      # установленные пакеты, для скриптов
ketch list --names-only      # все имена пакетов, по одному на строку
ketch list remote --json     # реестр с последними версиями

`ketch outdated [--json] [--pre] [--draft]`

Показывает установленные пакеты, у которых есть более новый релиз. Недоступный источник — это предупреждение, а не ошибка, если только вообще ничего не удалось проверить. --draft сравнивает и с черновиками релизов GitHub, как в upgrade. Пакет на плавающем теге устарел, когда его тег указывает на другую сборку.

ketch outdated
ketch outdated --json   # {"status","outdated","failed","unreachable"}

`ketch info <PKG> [--assets] [--releases [--draft]] [--json]`

Показывает подробности о пакете, установленном или нет: источник, описание, последнюю и установленную версии, ссылки, хранение, проверку.

ketch info BurntSushi/ripgrep
ketch info rg --assets     # каждый ассет релиза с оценкой и её причиной
ketch info rg --releases   # ниже — та же таблица, что печатает `ketch releases`

--releases добавляет под подробностями релизы пакета (20 самых новых) в формате ketch releases, а --draft перечисляет среди них черновики, как ketch releases --draft; с --json это массив releases. Недоступный источник — предупреждение, а раздел пропускается (в JSON — null).

Алиас — ketch show.

`ketch releases <PKG> [--pre] [--draft] [-n <LIMIT>] [--json]`

Перечисляет релизы, опубликованные источником пакета, от новых к старым — в порядке, в каком их отдаёт источник, — и отмечает установленный. Нужна сеть.

$ ketch releases fd -n 3
   tag      version  published   kind
   v10.5.0  10.5.0   2026-08-26  stable
*  v10.4.2  10.4.2   2026-03-10  stable
   v10.4.1  10.4.1   2026-03-08  stable

tag и version — тег релиза и версия, которую ketch читает из него и сравнивает, без написания тега (v10.4.2 читается как 10.4.2). У тега, который вообще не версия (nightly), в version стоит -.
published — день публикации по данным источника или -.
kind — stable; pre — релиз, который форж помечает как пре-релиз или у чьей версии есть пре-релизная часть (2.0.0-rc.1); dev — тег, не являющийся версией (плавающий nightly, даже если он помечен и как пре-релиз); draft — неопубликованный релиз GitHub, перечисляется только с --draft или для пакета, установленного на канале draft.
* в первом столбце (● в цветном терминале) отмечает релиз, из которого установлен пакет, если он есть среди перечисленных.

Без --pre перечисляются только стабильные релизы, если не задано prerelease = true в config.toml или манифесте пакета и пакет не установлен на канале pre или dev (GitHub помечает nightly как пре-релиз); репозиторий, в котором никогда не было стабильного релиза, перечисляет свои пре-релизы в любом случае. --draft перечисляет ещё и черновики GitHub, а вместе с ними пре-релизы; пакет, установленный с --draft, перечисляет их и без флага. Как и для ketch install --draft, нужен токен с правом push в репозиторий (KETCH_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN или github_token), а без него команда останавливается и называет, чего не хватает; у других источников черновиков нет, и они отклоняют флаг. -n (по умолчанию 20, не меньше 1) ограничивает список; источник может вернуть меньше. Пустой список печатает no releases.

--json печатает массив {"tag", "version", "published_at", "kind", "installed"}; version и published_at равны null, когда неизвестны.

ketch releases ripgrep
ketch releases sharkdp/fd --pre --json

`ketch why <PKG> [--json]`

Объясняет, как был бы разрешён пакет, не устанавливая его: какой уровень манифестов ответил, какой релиз и ассет были выбраны и почему.

ketch why sharkdp/[email protected]
ketch why rg --json

`ketch changelog <PKG> [--latest] [--file] [--release]`

Показывает, что изменилось: файл changelog, который поставляется с пакетом, или заметки к релизу, опубликованные вместе с ним. Для установленной версии предпочитает файл на диске; иначе использует заметки.

ketch changelog ripgrep            # установленная версия
ketch changelog ripgrep --latest   # вместо неё самый новый релиз
ketch changelog ripgrep --file     # только поставляемый файл
ketch changelog ripgrep --release  # только опубликованные заметки

`ketch search <QUERY>... [-n <LIMIT>]`

Ищет на GitHub (и в плагинах с поиском) репозитории, которые можно установить.

ketch search fuzzy finder
ketch search ripgrep -n 5

Воспроизведение

`ketch lock [--file <FILE>] [--check]`

Записывает ./ketch.lock по тому, что установлено, — воспроизводимую запись утилит машины, закреплённых на точных релизах. См. LOCKFILE.md.

ketch lock              # записать ./ketch.lock
ketch lock --check      # не разошлось ли дерево с ним?
ketch lock -f tools.lock

`ketch sync [--file <FILE>] [--prune] [--dry-run]`

Устанавливает всё, что названо в ketch.lock, в названных там версиях. Пакет, не упомянутый в lock-файле, не трогается, если не передан --prune (который сначала спрашивает, потому что может уничтожить чью-то работу).

ketch sync                 # только отсутствующие или разошедшиеся пакеты
ketch sync --dry-run       # показать план +/~/−, ничего не меняя
ketch sync --prune --yes   # также удалить лишнее, не спрашивая

История

`ketch history [PKG] [-n <LIMIT>] [--json]`

Показывает, что устанавливалось, обновлялось и удалялось, начиная с самого нового. Без пакета показывает всё дерево на одной временной шкале.

ketch history
ketch history ripgrep -n 10

`ketch stats [--json]`

Сводит всё, что ketch записал в stats.db.

ketch stats
ketch stats --json

Реестр и источники

`ketch update`

Обновляет реестр пакетов в ~/.ketch/registry. (Для установленных пакетов см. upgrade.)

ketch update

Запускается автоматически в начале install и upgrade, если auto_update не равно false в ~/.ketch/config.toml (KETCH_AUTO_UPDATE=false).

`ketch registry validate [DIR] [--fixture <DIR>] [--changed <NAME>] [--json]`

Проверяет дерево реестра так же, как pre-push хук: каждый ketch.toml разобран и проверен, плюс конфликты имён. --fixture в качестве дополнительного доказательства выполняет офлайн-установку записей из локальных файлов.

ketch registry validate
ketch registry validate ./ketch-registry --fixture ./fixtures

`ketch registry status [--json]`

Показывает возраст и источник локальной копии реестра, ничего не загружая.

ketch registry status

`ketch registry push [--file <FILE>] [--registry <REPO>] [--dry-run] [--yes]`

Сравнивает ketch.toml этого проекта с копией в реестре и открывает с ним пул-реквест. Для нового пакета открывает сразу; для обновления показывает дифф и спрашивает; если файлы идентичны, сообщает unchanged и ничего не открывает. См. REGISTRY.md.

KETCH_GITHUB_TOKEN=... ketch registry push
ketch registry push --dry-run

`ketch plugin list [--json]` / `ketch plugin dir`

Показывает обнаруженные плагины источников (ketch-source-<scheme> в ~/.ketch/plugins и в PATH) или печатает каталог плагинов. См. PLUGINS.md.

ketch plugin list
ketch plugin dir

Окружение

`ketch doctor [--fix] [--json]`

Проверяет окружение и дерево установки: версию, настройку PATH, проверки платформы, лог, возраст реестра, соответствие хранилища state.json. Возвращает ненулевой код, если проверка не прошла. В Windows также предупреждает о записях в пользовательском PATH, указывающих на каталог bin ketch, папки которого уже нет, — этого корня или любой .ketch\bin.

ketch doctor
ketch doctor --fix    # исправить то, что можно исправить (настройку PATH)

`ketch path [install|uninstall|status]`

Добавляет каталог bin ketch в PATH. Просто ketch path показывает таблицу состояния; это подкоманда по умолчанию.

ketch path                  # каталог bin, состояние PATH, таблица по оболочкам
ketch path install          # изменить файлы запуска оболочек (спрашивает для каждой)
ketch path install --print  # напечатать строку, чтобы добавить её вручную
ketch path install --all    # действовать для всех известных оболочек
ketch path uninstall        # снова убрать блок

`ketch config create [--file <FILE>] [--force] [--yes]`

Записывает конфигурацию пакета (ketch.toml) по ответам на вопросы — источник, имя, записи bin, шаблоны ассетов, — затем показывает и записывает файл. Пакет, который ставит ссылки на бинарники, должен называть команду, которую добавляет в PATH, поэтому первую запись bin команда запрашивает, а не предлагает; её имя по умолчанию — имя пакета. Ответы можно передать через stdin, по одному на строку. См. MANIFESTS.md.

ketch config create
ketch config create --file ./ketch.toml --yes

`ketch config reset [--yes]`

Записывает config.toml в корне ketch со скомпилированными значениями по умолчанию. Сначала спрашивает, если не передан --yes; сохраняет резервную копию существующего файла рядом с ним как config.toml.bak-<unix-seconds>, если файл есть и не совпадает с уже лежащей рядом резервной копией.

ketch config reset
ketch config reset --yes

`ketch completions <SHELL> [--install]`

Печатает скрипт автодополнения для оболочки или с --install устанавливает его в пользовательский каталог автодополнений оболочки.

ketch completions zsh > _ketch
ketch completions bash --install

Скрипты для bash и PowerShell также дополняют имена пакетов: установленных — после uninstall, upgrade, pin, unpin, link, unlink, info, releases, why, changelog и rollback, и имена из локальной копии реестра — после install и search. Скрипт запрашивает их у бинарника внутренней командой ketch __complete <installed|registry> [PREFIX], которая читает файл состояния и уже лежащий на диске реестр и никогда не обращается к сети. --root, указанный ранее в командной строке, учитывается.

--install записывает скрипт bash в ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/ketch, откуда bash-completion 2 загружает его при первом использовании. В macOS для этого системной оболочки мало: /bin/bash — это 3.2, а bash-completion 2 нужен bash 4.2 или новее. Установите свежий bash и bash-completion 2 (через Homebrew: brew install bash bash-completion@2), сделайте этот bash оболочкой входа и подключайте bash_completion из bash-completion в ~/.bashrc, как сказано в его примечаниях. Сам скрипт работает и под bash 3.2, так что eval "$(ketch completions bash)" в ~/.bashrc работает и без них.

В Windows --install (и ketch self install, который устанавливает скрипты для всех оболочек) также включает автодополнение, потому что ни одна из оболочек не загружает каталог автодополнений сама:

PowerShell. Скрипт помещается в Documents\PowerShell\Completions\ketch.ps1, а блок между # >>> ketch >>> и # <<< ketch <<< в профиле CurrentUserAllHosts для PowerShell 7 (Documents\PowerShell\profile.ps1) и Windows PowerShell 5.1 (Documents\WindowsPowerShell\profile.ps1) подключает его через dot-sourcing. Documents — это папка, о которой сообщает PowerShell, так что перенаправление в OneDrive учитывается. Ещё не существующий профиль создаётся, только если эта редакция установлена и её политика выполнения разрешает локальные скрипты; иначе ketch объясняет, почему не стал его трогать.
cmd. В cmd нет программируемого автодополнения, поэтому он получает макросы doskey: ki (ketch install), ku (ketch upgrade), kl (ketch list) и kun (ketch uninstall), каждый из которых передаёт свои аргументы дальше. Они лежат в <root>\share\ketch\ketch.doskey и загружаются командой doskey /macrofile="…", добавленной в HKCU\Software\Microsoft\Command Processor\AutoRun через & после того, что AutoRun уже выполняет.

ketch self uninstall убирает блоки из профилей (удаляя профиль, в котором больше ничего не было) и удаляет из AutoRun ровно свою команду, оставляя прежнее значение как было или удаляя значение, если в нём была только команда ketch.

Сам ketch

`ketch self install [--force] [--link-dir <DIR>]`

Устанавливает этот релиз ketch как пакет — в хранилище и каталог bin. Именно это запускают установщики curl/PowerShell/Homebrew.

ketch self install

`ketch self upgrade [--dry-run] [--force] [--pre] [--yes]`

Обновляет ketch до последнего релиза. Алиас — ketch self update. ketch, установленный через mise и ни разу не установленный через self install, обновляет mise: команда отказывается и называет mise upgrade.

--pre берёт самый новый релиз, включая пре-релизы, а не последний релиз по версии GitHub. Релизы macOS-приложения desktop-v* не берутся никогда. Тот же флаг принимают установщики: install.sh --pre и install.ps1 --pre. Без флага ничего не меняется.

ketch self upgrade
ketch self upgrade --dry-run
ketch self upgrade --pre

`ketch self version`

Печатает запущенную версию и где она находится (target, корень, бинарник, PATH).

ketch self version

`ketch self uninstall [--keep-packages] [--dry-run] [--yes]`

Удаляет ketch и всё, что он установил, безвозвратно. Перечисляет, что собирается удалить, и сначала спрашивает. --keep-packages удаляет только ketch. Для ketch, установленного через mise, также спрашивает, запустить ли mise unuse -g для его собственной копии; --yes отвечает и на это. В Windows запущенный ketch.exe не может удалить сам себя, поэтому остальная часть корня удаляется фоновым процессом после выхода ketch.

Собственные каталоги корня (bin, store, cache, …) очищаются, только если корень создал ketch — тогда в нём лежит метка .ketch-root — или корень стандартный, ~/.ketch. Корень, который существовал раньше, например ~/.local или /usr/local, и сам домашний каталог сохраняют всё, что ketch там не записывал.

В Windows он также удаляет то, что ketch записал в реестр Windows. Сейчас это только каталог bin в пользовательском PATH (HKCU\Environment\Path), записанный install.ps1 или ketch path install. Запись находится как бы она ни была написана: регистр, кавычки, / или \, завершающий разделитель или короткое имя 8.3. --keep-packages оставляет её, как и блоки в оболочках, потому что она нужна пакетам, которые остаются в каталоге bin. ketch никогда не регистрирует себя в «Приложениях и возможностях», так что удалять там нечего.

Он также удаляет блоки из профилей PowerShell и добавку в AutoRun cmd, которые включают автодополнение, — их и с --keep-packages, потому что оба загружают сам ketch.

ketch self uninstall --dry-run
ketch self uninstall --keep-packages

Установка и удаление

ketch install [PKG]... [options]

ketch uninstall <NAME>...

ketch upgrade [NAME]...

ketch rollback <PKG> [--to <VERSION>]

ketch prune [NAME]... [--keep <N>]

ketch pin <NAME>... / ketch unpin <NAME>...

ketch link <NAME>... / ketch unlink <NAME>...

ketch import winget|brew|linux <NAME> [--dry-run] [--yes]

Просмотр

ketch list

ketch outdated [--json] [--pre] [--draft]

ketch info <PKG> [--assets] [--releases [--draft]] [--json]

ketch releases <PKG> [--pre] [--draft] [-n <LIMIT>] [--json]

ketch why <PKG> [--json]

ketch changelog <PKG> [--latest] [--file] [--release]

ketch search <QUERY>... [-n <LIMIT>]

Воспроизведение

ketch lock [--file <FILE>] [--check]

ketch sync [--file <FILE>] [--prune] [--dry-run]

История

ketch history [PKG] [-n <LIMIT>] [--json]

ketch stats [--json]