shimkit

A toolkit of developer utilities. Python tools, shimmed by bash.

$ shimkit --help
shimkit
  java          Manage OpenJDK installations.
  shell         Manage shell installations and upgrades.
  dns           macOS DNS resolver recovery.
  adguard       AdGuard Home port-conflict fixer (Linux).
  docker-clean  Docker resource cleanup.
  ports         Inspect / kill the process holding a TCP/UDP port.
  hosts         /etc/hosts editor with atomic-write + backups.
  ssh           SSH key + agent + known_hosts + perms hygiene.
  env           .env viewer + scaffolder with secret redaction.
  gpg           GPG key + git-signing hygiene.
  logs          System log tail / grep.
  cron          Manage shimkit-tagged entries in the user crontab.
  db            Container-first databases (6 engines).
  stack         Multi-container app recipes (LEMP today).
  web           Web-server tooling (nginx vhost generator).
  tls           TLS cert lifecycle via container-first certbot.
  framework     Framework-specific helpers (Laravel + Symfony + Django).
  config        Inspect and edit shimkit configuration.
  doctor        Print system diagnostics useful for bug reports.
  self-update   Update shimkit itself to the latest release.
  version       Print the shimkit version.

Install

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.

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] @ git+https://github.com/simtabi/shimkit@v0.19.0' for dns, adguard and docker-clean (the bare shimkit[extra-tools] form needs PyPI, which is not published yet).
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

shimkit ports show 5000              # who is holding the port
shimkit ports kill 5000 --dry-run    # show targets without signalling

shimkit db postgres up               # container-first Postgres

Every tool is listed under Tools, each with its own deep-dive; installation and configuration are in docs/installation.md and docs/configuration.md.

Tools

• shimkit java — OpenJDK version manager. Install / list / switch / upgrade / uninstall / remove-oracle on macOS and Linux (incl. WSL, Docker).
• shimkit shell — Upgrade bash / zsh / fish / ksh via brew, apt, dnf, yum, pacman, apk, or zypper.
• shimkit dns — macOS DNS resolver recovery. Diagnose, flush, fix (6-step escalation), test, rollback, and dump diagnostic bundles.
• shimkit adguard — AdGuard Home port-conflict fixer (Linux). API-first, yaml fallback, with systemd-resolved / NetworkManager handling.
• shimkit docker-clean — Docker resource cleanup (Linux + macOS + WSL). Status, quick, prune-*, nuke, schedule-snippet emit.
• shimkit ports — list / kill the process holding a TCP or UDP port (macOS + Linux). lsof on macOS, ss on Linux. MODERATE prompt on kill; severe token for system-tier PIDs.
• shimkit hosts — /etc/hosts editor with atomic-write + timestamped backups. add / remove / block / unblock / apply-list (severe) / rollback. macOS + Linux.
• shimkit ssh — SSH key + agent + known_hosts + perms hygiene. keys list/generate/rotate, agent status/add, known-hosts audit/prune, perms audit/fix, config show. No third-party deps; passphrases handled by ssh-keygen.
• shimkit env — .env viewer + scaffolder with default-deny secret redaction. show / list / scaffold / diff / redact. macOS + Linux.
• shimkit gpg — GPG key + git-signing hygiene. keys list/generate/export, agent status, git-signing show/configure. No third-party deps; passphrases handled by gpg.
• shimkit logs — system log tail / grep. macOS log show/stream, Linux journalctl. Read-only — no mutators, no prompts.
• shimkit cron — manage shimkit-tagged entries in your user crontab. add / list / remove / show / rollback. Atomic write + backup-on-mutate; never touches user-authored entries.

Server-class tools (Docker-first; opt-in to host install)

• shimkit db — container-first databases (mysql / mariadb / postgres / mongo / redis / phpmyadmin). up / down / shell / dump / reset (SEVERE) / status / ls
  • --on-host mode for mysql/mariadb/postgres. No host-install path; the container is the source of truth.
• shimkit web nginx vhost — hardened nginx vhost generator. File-only by default; apply and remove are SEVERE-tier. Three flavors: static / php / laravel.
• shimkit stack lemp — three-container LEMP recipe (db + php-fpm + nginx). Bind-mounts $cwd at /srv/app. up / down / status / logs / exec. Multiple projects side-by-side via --project.
• shimkit tls — TLS cert lifecycle helper via container-first certbot. request / list / status / renew / revoke (SEVERE) / cron-install. Three ACME methods: webroot (HTTP-01), dns-cloudflare, dns-route53 (DNS-01 — wildcards). State persists under ~/.shimkit/data/tls/; pair with shimkit cron for daily renewals.
• shimkit shell colors — 256-color ANSI palette diagnostic.

Framework recipes

• shimkit framework laravel — Laravel-specific helpers: perms (cross-distro storage + bootstrap/cache fixer), env (.env scaffold with generated APP_KEY), cron-install (wraps shimkit cron with php artisan schedule:run), and artisan (host or LEMP-container passthrough).
• shimkit framework symfony — Symfony helpers: perms (var/), env (.env.local scaffold with APP_SECRET), cache-clear, and bin/console passthrough.
• shimkit framework django — Django helpers: perms (media/ + staticfiles/), env (.env scaffold with SECRET_KEY + django-environ-style DATABASE_URL), migrate, and manage.py passthrough.

Plus three utilities:

• shimkit config — inspect, edit, validate user configuration (details)
• shimkit doctor — system diagnostics for bug reports
• shimkit self-update — keep shimkit current (details)

Version requirements

shimkit declares minimum versions for the external binaries it shells out to (docker / nginx / git / gpg / python). The registry lives under tools.versions in the JSON config and is consulted at three points:

1. Each tool's boot() runs a preflight; out-of-range / missing tools exit 69 with a platform-specific install hint.
2. shimkit doctor prints the full versions table.
3. The same registry is rendered into the install docs.

Override per-install in ~/.config/shimkit/shimkit.json. Full spec: .design/version-constraints-spec.md.

Architecture

Quick overview at docs/architecture.md. Deep reference under .design/:

• .design/architecture-current.md — pre-migration snapshot (the five load-bearing rules, JSON configurator, MODERATE/SEVERE prompt model, EX_* exit codes).
• .design/architecture-target.md — post-migration layout (adds core/docker.py, core/version.py, and the db / stack / web sub-trees).
• .design/version-constraints-spec.md — the constraints subsystem in detail.
• .design/plans/migration-plan.md — the v0.5.0 work-item plan; useful for understanding why a given module exists.

Documentation

The repo root has the short version. The long version lives under docs/. For a single annotated map of every doc — including the full per-version release-notes index — see docs/overview.md.

Topic	Doc
Annotated index of all docs + release notes	docs/overview.md
Install methods, the one-liner, updates, uninstall	docs/installation.md
Config layer, schema, examples	docs/configuration.md
Architecture, the load-bearing rules, how to add a new tool	docs/architecture.md
Onboarding: setup, the 5 rules, recipe for adding a tool, debugging	docs/onboarding.md
Cutting a release, what each CI job does, release readiness (what's done vs pending)	docs/release.md
Validation scope: what's gated, what's deliberately out of scope	docs/validation-scope.md
Known issues + pending items (un-automatable checks, deferrals)	docs/plans/known-issues.md
Future additions (no-demand, naturally-extensible surface)	docs/plans/future-additions.md
Shipping audit (2026-05-16): shipped-vs-pending walk	docs/plans/shipping-audit.md
Per-version release notes (newest first)	docs/release-notes/
shimkit java deep-dive	docs/tools/java.md
shimkit shell deep-dive	docs/tools/shell.md
shimkit dns deep-dive	docs/tools/dns.md
shimkit adguard deep-dive	docs/tools/adguard.md
shimkit docker-clean deep-dive	docs/tools/docker-clean.md
shimkit ports deep-dive	docs/tools/ports.md
shimkit hosts deep-dive	docs/tools/hosts.md
shimkit ssh deep-dive	docs/tools/ssh.md
shimkit env deep-dive	docs/tools/env.md
shimkit gpg deep-dive	docs/tools/gpg.md
shimkit logs deep-dive	docs/tools/logs.md
shimkit cron deep-dive	docs/tools/cron.md
shimkit db deep-dive	docs/tools/db.md
shimkit stack deep-dive	docs/tools/stack.md
shimkit web nginx deep-dive	docs/tools/web.md
shimkit tls deep-dive	docs/tools/tls.md
shimkit framework laravel deep-dive	docs/tools/framework-laravel.md
shimkit framework symfony deep-dive	docs/tools/framework-symfony.md
shimkit framework django deep-dive	docs/tools/framework-django.md

Project files:

• CONTRIBUTING.md — coding conventions, test patterns, PR expectations
• SECURITY.md — vulnerability disclosure
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1
• CHANGELOG.md — release history

Development

git clone https://github.com/simtabi/shimkit
cd shimkit
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
ruff check src tests
mypy src/shimkit

CI runs the same four commands on macOS + Ubuntu × Python 3.10/3.11/3.12/3.13. Coverage for each run (total, the enforced floor, and the lowest-covered files) is in the run's job summary for the Ubuntu / Python 3.12 job, with coverage.xml kept as a run artifact for seven days. See CONTRIBUTING.md.

License

MIT — see LICENSE.