From a95d6446ac355663a865a5db843a35753c96ae8d Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sun, 4 Oct 2026 07:13:28 -0400 Subject: [PATCH 1/2] Add a Quick start guide and usage section The README standard now splits the section into Getting started, the setup a fresh install needs before the first call, and Usage. Every command, tag and env key shown was checked against the package's own provider, config or CLI. --- README.md | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3b49340..62b9850 100644 --- a/README.md +++ b/README.md @@ -33,15 +33,41 @@ shimkit ## Install ```bash -uv tool install shimkit -pipx install shimkit -brew install simtabi/tap/shimkit -pip install --user shimkit +uv tool install git+https://github.com/simtabi/shimkit@v0.19.0 +pipx install git+https://github.com/simtabi/shimkit@v0.19.0 +pip install --user git+https://github.com/simtabi/shimkit@v0.19.0 ``` +PyPI and Homebrew channels (`uv tool install shimkit`, `brew install simtabi/tap/shimkit`) are not +published yet. + Full install matrix, optional dependency extras, and self-update behaviour: [`docs/installation.md`](docs/installation.md). +## Quick start guide and usage + +### Getting started + +1. Verify the install: `shimkit version`, then `shimkit doctor` (platform, shell, package + manager and config validity). +2. Optional: add the extras for the tools that need them, e.g. + `uv tool install 'shimkit[extra-tools]'` for `dns`, `adguard` and `docker-clean`. +3. Optional: override the bundled defaults with `shimkit config edit`, which opens + `~/.config/shimkit/shimkit.json` in `$EDITOR`; `shimkit config show` prints the resolved config. + +### Usage + +```bash +shimkit ports show 5000 # who is holding the port +shimkit ports kill 5000 --dry-run # show targets without signalling +``` + +```bash +shimkit db postgres up # container-first Postgres +``` + +Every tool is listed under [Tools](#tools), each with its own deep-dive; installation and configuration are in [`docs/installation.md`](docs/installation.md) and [`docs/configuration.md`](docs/configuration.md). + ## Tools - **[`shimkit java`](docs/tools/java.md)** — OpenJDK version manager. From b21458cda82182a1f61a8999f1979d5e18b5cefb Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sun, 4 Oct 2026 07:13:28 -0400 Subject: [PATCH 2/2] Correct publish tags, config paths and keys to what the package registers Each value was confirmed by booting the provider under testbench and reading its publish groups and merged config. --- docs/installation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 6114df2..61df452 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,6 +1,6 @@ # Installation -> **As of v0.2.2:** shimkit ships via the wheel + sdist attached to +> **As of v0.19.0:** shimkit ships via the wheel + sdist attached to > each [GitHub Release](https://github.com/simtabi/shimkit/releases). > Publishing to PyPI is deferred — the trusted-publisher setup is in > place on the GitHub side (`release.yml` + `pypi` environment) but @@ -15,12 +15,12 @@ ```bash # 1. Wheel from the GitHub Release page (works with any Python ≥ 3.10). pip install --user \ - https://github.com/simtabi/shimkit/releases/download/v0.2.2/shimkit-0.2.2-py3-none-any.whl + https://github.com/simtabi/shimkit/releases/download/v0.19.0/shimkit-0.19.0-py3-none-any.whl # 2. Direct from a tag (no release-page step). -pip install --user git+https://github.com/simtabi/shimkit@v0.2.2 -uv tool install git+https://github.com/simtabi/shimkit@v0.2.2 -pipx install git+https://github.com/simtabi/shimkit@v0.2.2 +pip install --user git+https://github.com/simtabi/shimkit@v0.19.0 +uv tool install git+https://github.com/simtabi/shimkit@v0.19.0 +pipx install git+https://github.com/simtabi/shimkit@v0.19.0 ``` ## PyPI-style channels (pending)