Skip to content

Add a Quick start guide and usage section #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
imanimanyara merged 2 commits into from
Oct 4, 2026
Merged

Add a Quick start guide and usage section #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a95d644
Add a Quick start guide and usage section
imanimanyara Oct 4, 2026
b21458c
Correct publish tags, config paths and keys to what the package regis…
imanimanyara Oct 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 30 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 5 additions & 5 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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)
Expand Down
Loading