wtftools 0.0.0__tar.gz → 0.0.2__tar.gz

{wtftools-0.0.0 → wtftools-0.0.2}/CHANGELOG.md

@@ -6,12 +6,148 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.2] - 2026-07-01
+
+### Docs
+- README is now a concise landing page (what it is, capabilities, install, a
+  linked command reference). The detailed per-command examples moved into
+  `docs/AUDIT.md`, `docs/RESOURCES.md`, `docs/OUTPUT.md` and `docs/CONFIG.md`,
+  linked from the command tables. Translations mirror the landing README;
+  the deep reference pages are English.
+
+### Added
+- `wtf completion [bash|zsh]` — print a shell-completion script to enable
+  `<Tab>` completion (`eval "$(wtf completion bash)"`); bare `wtf completion`
+  prints setup instructions. The bash script lives in `wtftools/completion.py`
+  as the single source of truth; `completions/wtf` is a generated mirror
+  (a test guards against drift), installed to bash-completion's system dir.
+
+### Changed — `wtf disk` folder usage
+- `wtf disk <path>` now breaks a directory down by folder size, biggest first
+  (like `du -sh <path>/* | sort`), as `# DISK USAGE <path>` rows of
+  `path/  size  % of analysed root  depth` (the depth index is the last
+  column). `wtf disk` with no path still shows the per-mount overview, now laid
+  out as `full path  used/total  percent  bar` (full mount paths, no
+  truncation).
+- `--tree [N]` drills into the N largest folders at each level (bare `--tree` =
+  1 → a single dominant chain); `--depth D` sets how deep (default 3). Output
+  is parse-first: `plain` is `bytes<TAB>percent<TAB>abspath<TAB>depth`, `json`
+  is a flat `entries` list with absolute `path` + relative `rel`.
+- **Breaking:** `--tree` used to take a PATH (`wtf disk --tree /var`); the path
+  is now the positional argument (`wtf disk /var --tree`) and `--tree` is the
+  expansion count. The `du` scan timeout was raised (30→120s) so large
+  filesystems no longer return an empty result.
+
+### Fixed
+- `wtf ports` and `wtf top` JSON is now an object carrying `schema_version`
+  (was a bare array), consistent with `disk`/`net`; `wtf audit` JSON carries
+  `schema_version` too.
+- README documentation links are absolute so they resolve on the PyPI project
+  page; the translated READMEs no longer link to a non-existent `docs/docs/`
+  path.
+- `.deb` install instructions use the actual package name
+  (`python3-wtftools_*.deb`).
+- Unexpected errors now print a one-line message instead of dumping a raw
+  Python traceback; set `WTFTOOLS_DEBUG=1` or pass `--verbose` for the trace.
+- `requirements.txt` no longer pulls `psutil` — the core install stays
+  dependency-free; use `pip install "wtftools[full]"` for psutil.
+- The packaged bash-completion installs as `completions/wtf`, so it is
+  auto-loaded system-wide (the previous file name prevented auto-loading; the
+  `eval "$(wtf completion bash)"` path was unaffected).
+- The Docker base image is pinned by digest for reproducible builds.
+- Minimum Python raised to 3.9 (`requires-python`): the build needs
+  setuptools>=77, which dropped the EOL Python 3.8. The source stays
+  3.8-compatible in style; only the packaged build floor moved.
+
+### Security
+- `wtf explain --llm claude|openai` discloses (to stderr) that the host name
+  and audit findings are sent to the vendor, and asks for confirmation on an
+  interactive terminal (`--yes` / `WTFTOOLS_LLM_YES=1` to skip). `--llm auto`
+  no longer silently escalates to a remote model — it uses local `ollama` only.
+- `wtf audit --format csv` escapes cells beginning with `= + - @` to prevent
+  spreadsheet formula injection.
+- Snapshot files and their directory are created `0600`/`0700`, so root's audit
+  history is not world-readable on a multi-user host.
+- `wtf crontab -u <user>` validates the username (same rule as positional
+  targets) before shelling out to `crontab -l -u`, avoiding argument injection.
+
+## [0.0.1] - 2026-06-14
+
+### Added — port, docker and temperature views
+- `wtf port <N>` (alias of `wtf ports <N>`) — drill into a single port:
+  which process holds it (PID, user, command), the exact executable file
+  behind it and its working directory, via `lsof` with `/proc` enrichment
+  and psutil/`ss` fallbacks. text/plain/json output.
+- `wtf docker [NAME]` — where a container was started from: the compose
+  project working directory and config files read from the container's
+  labels, plus on-disk sizes (image layers, writable container layer and
+  json log). With no name it lists running containers as a table with
+  image/container/log size columns and a TOTAL row. Sizes use decimal units
+  (1GB = 1000MB) to match `docker container ls --size`. The image total
+  dedupes by image id (one image shared by many containers counted once); it is
+  the logical unique-images size, and since different images still share base
+  layers on disk, the real layer-deduplicated disk is shown alongside it from
+  `docker system df`. Container (writable layer) and log totals are exact. Log
+  sizes need read access under `/var/lib/docker` (run with `sudo`); otherwise
+  the column and its total show `?`, not a misleading `0B`.
+- `wtf temp` (aliases `temps`, `temperature`) — hardware temperatures from
+  `/sys/class/hwmon` sensors, sorted hottest-first and colored against the
+  configured warn/fail thresholds. text/plain/json output.
+
+### Changed — output
+- Section headers are now plain `# TITLE` lines instead of full-width
+  centered box-drawing rules, so the output greps cleanly (`grep '^#'`).
+
+### CI
+- Bumped GitHub Actions to the Node.js 24 majors (checkout v6,
+  setup-python v6, action-gh-release v3).
+
+### Added — per-resource subcommands
+- `wtf disk` — per-mount usage with inode percent and read-only flags;
+  `--tree [PATH]` lists the largest directories (du-based, `--depth`,
+  `--top`); without PATH it picks the fullest mount automatically.
+- `wtf cpu` — model, loadavg (+per-cpu), iowait, PSI, top-5 by CPU.
+- `wtf mem` — RAM/swap, PSI, OOM kills in the look-back window, top-5 by RSS.
+- `wtf net` — interfaces, default gateway, DNS servers, interface error
+  counters, listening TCP ports summary.
+- `wtf io` — PSI io, iowait, per-device read/write rates and utilization
+  (sampled from `/proc/diskstats`), D-state processes.
+- `wtf who` — logged-in users, recent logins, failed-auth count.
+- All six support `--format text|plain|json`; `plain` is tab-separated for
+  awk/grep, JSON includes `schema_version`.
+- New module `wtftools/sections.py`; new sysinfo helpers:
+  `get_default_gateway`, `get_dns_servers`, `get_logged_in_users`,
+  `get_du_tree`, `get_disk_io_per_device`.
+
+### Added — teaching mode
+- `--show-commands` on `disk`/`cpu`/`mem`/`net`/`io`/`who` prints the
+  classic commands each view replaces (`df -h`, `ss -tlnp`, …), so the
+  output can be learned from and double-checked by hand.
+
+### Added — daily routine and pipeline output
+- `wtf daily` — the morning check as one command: one-line verdict, diff
+  vs the previous snapshot, event timeline and the full audit; saves a
+  snapshot on every run so the next day diffs against it.
+- `--format plain` for `top`, `ports`, `events`, `logs`, `services` and
+  `info` — every command now has a tab-separated twin for grep/awk.
+- Global `-f/--format` flag: `wtf -f json disk` works; a `--format` given
+  after the subcommand still wins.
+- `schema_version` added to the JSON payloads of `info`, `events`, `logs`,
+  `services` and `daily`.
+
+### Changed
+- `wtf ports` no longer fails without psutil — it falls back to an
+  `ss`-based TCP listing (no PID/user info; UDP still needs psutil).
+- `wtf service` is now an alias for `wtf services`.
+- README restructured for first-time users: install + the most-used
+  commands up top, scripting (grep/awk/jq) cookbook, advanced flags below.
+- Bash completion covers the new subcommands.
+
 ### Removed — plugin infrastructure
 - `wtftools/plugin_sdk.py` — Python helper for plugin authors.
 - `wtftools/checks/plugins.py` — discovery / executor / parser for
   `/etc/wtf/checks.d/` scripts (bash + Python).
 - `_plugin_to_check` + `_all_check_callables` glue in `wtftools/audit.py`.
-- `tests/test_plugins.py`, `tests/test_iteration16.py`.
 - README's «Plugins» section and QUICKSTART's «Custom checks (plugins)»
   section.
 
@@ -84,7 +220,7 @@ Initial public release. Highlights:
   release workflow.
 - **724 tests, 92.6 % coverage.**
 
-### Added — Plugin SDK & docs (final iteration)
+### Added — Plugin SDK & docs
 - **`wtftools.plugin_sdk`** — tiny helper module so Python plugins don't have
   to remember exit codes or hand-roll JSON:
 

{wtftools-0.0.0 → wtftools-0.0.2}/MANIFEST.in

@@ -2,4 +2,5 @@ include README.md
 include LICENSE
 include CHANGELOG.md
 recursive-include wtftools *.py
-recursive-include scripts *.sh *.bash-completion
+recursive-include scripts *.sh
+include completions/wtf

wtftools-0.0.2/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: wtftools
+Version: 0.0.2
+Summary: One command to see what is going on with your Linux server right now.
+Author-email: Aleksandr Pimenov <wachawo@gmail.com>
+Maintainer-email: Aleksandr Pimenov <wachawo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wachawo/wtftools
+Project-URL: Repository, https://github.com/wachawo/wtftools.git
+Project-URL: Documentation, https://github.com/wachawo/wtftools#readme
+Project-URL: Bug Reports, https://github.com/wachawo/wtftools/issues
+Keywords: devops,sre,linux,diagnostics,monitoring,cron,system,audit,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: full
+Requires-Dist: psutil>=5.9.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: coverage>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: stdeb>=0.10.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# wtftools
+
+[![CI](https://github.com/wachawo/wtftools/actions/workflows/ci.yml/badge.svg)](https://github.com/wachawo/wtftools/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wtftools.svg)](https://pypi.org/project/wtftools/)
+[![Downloads](https://img.shields.io/pypi/dm/wtftools.svg)](https://pypi.org/project/wtftools/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wachawo/wtftools/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/wtftools.svg)](https://pypi.org/project/wtftools/)
+
+> One command to see what is going on with your Linux server right now.
+
+**English** | [Español](https://github.com/wachawo/wtftools/blob/main/docs/README_ES.md) | [Português](https://github.com/wachawo/wtftools/blob/main/docs/README_PT.md) | [Français](https://github.com/wachawo/wtftools/blob/main/docs/README_FR.md) | [Deutsch](https://github.com/wachawo/wtftools/blob/main/docs/README_DE.md) | [Italiano](https://github.com/wachawo/wtftools/blob/main/docs/README_IT.md) | [Русский](https://github.com/wachawo/wtftools/blob/main/docs/README_RU.md) | [中文](https://github.com/wachawo/wtftools/blob/main/docs/README_ZH.md) | [日本語](https://github.com/wachawo/wtftools/blob/main/docs/README_JA.md) | [हिन्दी](https://github.com/wachawo/wtftools/blob/main/docs/README_HI.md) | [한국어](https://github.com/wachawo/wtftools/blob/main/docs/README_KR.md)
+
+You log in to a server and something feels wrong. Instead of running ten
+commands (`htop`, `df -h`, `journalctl`, `systemctl --failed`, …) you run one:
+
+```
+$ wtf
+# AUDIT
+[ OK ] uptime                  3d 4h 12m
+[ OK ] load average            0.42 0.51 0.55 / 8 CPU
+[ OK ] memory                  4.1GB / 16.0GB used (25%)
+[WARN] disk /var               17.0GB / 20.0GB used (85%)
+[FAIL] failed systemd units    1 failed unit(s)
+
+  Summary: 12 ok · 1 warn · 1 fail · 2 skip
+```
+
+Green is fine, yellow needs a look, red needs fixing. `wtftools` is a
+**read-only, dependency-free CLI** (Python standard library only; `psutil`
+optional) that turns a pile of diagnostic commands into one readable answer —
+and a machine-readable one when you pipe it.
+
+## What it can do
+
+- **Health audit** — 35+ checks (disk, memory, swap, load, PSI, OOM kills,
+  failed units, cert expiry, SMART, temperatures, DNS, …) as a
+  green / yellow / red checklist.
+- **Per-resource views** — ask about one thing at a time, like `show` commands
+  on a switch: `wtf disk`, `wtf cpu`, `wtf mem`, `wtf net`, `wtf docker`, …
+- **Incident triage** — `wtf problems`, `wtf events`, `wtf logs`,
+  `wtf services <unit>`, `wtf explain` (optionally through a local or hosted LLM).
+- **Trends & alerting** — `wtf daily`, snapshots + `wtf diff`, cron alerts —
+  no monitoring stack required.
+- **Scriptable** — `-f json` on every command and `-f plain` (tab-separated) on
+  the resource and audit views; the JSON carries a `schema_version` so scripts
+  survive upgrades — for grep / awk / jq.
+- **Beginner-friendly** — `--show-commands` prints the classic commands each
+  view replaces, so you can learn them by hand.
+
+## Install
+
+```bash
+pipx install wtftools          # recommended — works on any modern distro
+pip install wtftools           # or classic pip (core, no dependencies)
+pip install wtftools[full]     # + psutil for richer process/socket info
+sudo dpkg -i python3-wtftools_*.deb    # Debian/Ubuntu package (see Releases)
+```
+
+After install you have the `wtf` command. Enable `<Tab>` completion by adding
+one line to your shell rc:
+
+```bash
+echo 'eval "$(wtf completion bash)"' >> ~/.bashrc   # bash
+echo 'eval "$(wtf completion zsh)"'  >> ~/.zshrc    # zsh
+```
+
+New here? Start with the [5-minute quickstart](https://github.com/wachawo/wtftools/blob/main/docs/QUICKSTART.md).
+
+## Commands
+
+Run `wtf <command> --help` for flags. Each command links to its reference page
+with examples.
+
+### Health & monitoring — [docs/AUDIT.md](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md)
+
+| command | what it does |
+|---------|--------------|
+| [`wtf` / `wtf audit`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-audit) | green/yellow/red checklist of what is OK and what is not |
+| [`wtf problems`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-problems) | only the WARN+FAIL rows |
+| [`wtf daily`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-daily) | morning check: audit + diff vs last run + events |
+| [`wtf explain`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-explain) | actionable advice per finding; `--llm` to pipe to an LLM |
+| [`wtf events`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-events) | timeline: reboots, OOM kills, failed units, … |
+| [`wtf logs`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-logs) | recent ERROR+ journal entries grouped by service |
+| [`wtf services`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-services) | drill into one unit: state, restarts, ports, journal |
+| [`wtf diff`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-diff) | compare current state to a saved snapshot |
+| [`wtf history`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-history) | list saved audit snapshots |
+| [`wtf crontab`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-crontab) | validate system + per-user crontabs |
+| [`wtf doctor`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-doctor) | self-diagnostic: which tools/files wtf can use |
+
+### Resource views — [docs/RESOURCES.md](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md)
+
+| command | what it does |
+|---------|--------------|
+| [`wtf disk [PATH]`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-disk) | mounts overview; with a PATH, the largest folders; `--tree` drills in |
+| [`wtf cpu`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-cpu) | load, iowait, pressure, top CPU consumers |
+| [`wtf mem`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-mem) | RAM/swap, OOM kills, top memory consumers |
+| [`wtf net`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-net) | interfaces, gateway, DNS, errors, listening ports |
+| [`wtf io`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-io) | per-device IO rates, pressure, stuck processes |
+| [`wtf who`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-who) | logged-in users, recent logins, failed auth |
+| [`wtf temp`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-temp) | hardware temperatures from /sys/class/hwmon |
+| [`wtf info`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-info) | one-page snapshot: all of the above at once |
+| [`wtf top`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-top) | focused process top: sort by cpu/rss, filter by user/name |
+| [`wtf ports` / `wtf port N`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-ports) | listening sockets; drill one port to PID, exe, cwd |
+| [`wtf docker [NAME]`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-docker) | container compose dir + image/container/log sizes |
+
+### Output & configuration
+
+| command | what it does |
+|---------|--------------|
+| [`wtf config`](https://github.com/wachawo/wtftools/blob/main/docs/CONFIG.md#wtf-config) | show effective config / print a commented example |
+| [`wtf completion`](#install) | print a bash/zsh `<Tab>`-completion script |
+| [machine output](https://github.com/wachawo/wtftools/blob/main/docs/OUTPUT.md) | `plain`/`json` formats and a grep·awk·jq cookbook |
+
+`wtftools` absorbs and supersedes
+[`checkcrontab`](https://github.com/wachawo/checkcrontab) — the same cron
+validator now lives at `wtf crontab`.
+
+## Documentation
+
+- [QUICKSTART.md](https://github.com/wachawo/wtftools/blob/main/docs/QUICKSTART.md) — 5-minute onboarding and a cheat sheet
+- [AUDIT.md](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md) — health checks, monitoring, exit codes, the full check list
+- [RESOURCES.md](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md) — per-resource views with examples
+- [OUTPUT.md](https://github.com/wachawo/wtftools/blob/main/docs/OUTPUT.md) — `plain`/`json` formats and the scripting cookbook
+- [CONFIG.md](https://github.com/wachawo/wtftools/blob/main/docs/CONFIG.md) — config file, thresholds, ignoring checks
+
+## Compatibility
+
+- Python 3.9+
+- Linux (systemd distributions are the happy path; the tool degrades
+  gracefully when `systemctl` / `journalctl` / `psutil` are missing)
+- No network access required for the core CLI; optional network only for
+  `wtf explain --llm …` and `wtf doctor --check-updates`
+
+## From source
+
+```bash
+git clone https://github.com/wachawo/wtftools
+cd wtftools
+pip install -e .
+python3 wtf.py audit       # or run it without installing
+```
+
+## License
+
+MIT

wtftools-0.0.2/README.md

@@ -0,0 +1,145 @@
+# wtftools
+
+[![CI](https://github.com/wachawo/wtftools/actions/workflows/ci.yml/badge.svg)](https://github.com/wachawo/wtftools/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wtftools.svg)](https://pypi.org/project/wtftools/)
+[![Downloads](https://img.shields.io/pypi/dm/wtftools.svg)](https://pypi.org/project/wtftools/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wachawo/wtftools/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/wtftools.svg)](https://pypi.org/project/wtftools/)
+
+> One command to see what is going on with your Linux server right now.
+
+**English** | [Español](https://github.com/wachawo/wtftools/blob/main/docs/README_ES.md) | [Português](https://github.com/wachawo/wtftools/blob/main/docs/README_PT.md) | [Français](https://github.com/wachawo/wtftools/blob/main/docs/README_FR.md) | [Deutsch](https://github.com/wachawo/wtftools/blob/main/docs/README_DE.md) | [Italiano](https://github.com/wachawo/wtftools/blob/main/docs/README_IT.md) | [Русский](https://github.com/wachawo/wtftools/blob/main/docs/README_RU.md) | [中文](https://github.com/wachawo/wtftools/blob/main/docs/README_ZH.md) | [日本語](https://github.com/wachawo/wtftools/blob/main/docs/README_JA.md) | [हिन्दी](https://github.com/wachawo/wtftools/blob/main/docs/README_HI.md) | [한국어](https://github.com/wachawo/wtftools/blob/main/docs/README_KR.md)
+
+You log in to a server and something feels wrong. Instead of running ten
+commands (`htop`, `df -h`, `journalctl`, `systemctl --failed`, …) you run one:
+
+```
+$ wtf
+# AUDIT
+[ OK ] uptime                  3d 4h 12m
+[ OK ] load average            0.42 0.51 0.55 / 8 CPU
+[ OK ] memory                  4.1GB / 16.0GB used (25%)
+[WARN] disk /var               17.0GB / 20.0GB used (85%)
+[FAIL] failed systemd units    1 failed unit(s)
+
+  Summary: 12 ok · 1 warn · 1 fail · 2 skip
+```
+
+Green is fine, yellow needs a look, red needs fixing. `wtftools` is a
+**read-only, dependency-free CLI** (Python standard library only; `psutil`
+optional) that turns a pile of diagnostic commands into one readable answer —
+and a machine-readable one when you pipe it.
+
+## What it can do
+
+- **Health audit** — 35+ checks (disk, memory, swap, load, PSI, OOM kills,
+  failed units, cert expiry, SMART, temperatures, DNS, …) as a
+  green / yellow / red checklist.
+- **Per-resource views** — ask about one thing at a time, like `show` commands
+  on a switch: `wtf disk`, `wtf cpu`, `wtf mem`, `wtf net`, `wtf docker`, …
+- **Incident triage** — `wtf problems`, `wtf events`, `wtf logs`,
+  `wtf services <unit>`, `wtf explain` (optionally through a local or hosted LLM).
+- **Trends & alerting** — `wtf daily`, snapshots + `wtf diff`, cron alerts —
+  no monitoring stack required.
+- **Scriptable** — `-f json` on every command and `-f plain` (tab-separated) on
+  the resource and audit views; the JSON carries a `schema_version` so scripts
+  survive upgrades — for grep / awk / jq.
+- **Beginner-friendly** — `--show-commands` prints the classic commands each
+  view replaces, so you can learn them by hand.
+
+## Install
+
+```bash
+pipx install wtftools          # recommended — works on any modern distro
+pip install wtftools           # or classic pip (core, no dependencies)
+pip install wtftools[full]     # + psutil for richer process/socket info
+sudo dpkg -i python3-wtftools_*.deb    # Debian/Ubuntu package (see Releases)
+```
+
+After install you have the `wtf` command. Enable `<Tab>` completion by adding
+one line to your shell rc:
+
+```bash
+echo 'eval "$(wtf completion bash)"' >> ~/.bashrc   # bash
+echo 'eval "$(wtf completion zsh)"'  >> ~/.zshrc    # zsh
+```
+
+New here? Start with the [5-minute quickstart](https://github.com/wachawo/wtftools/blob/main/docs/QUICKSTART.md).
+
+## Commands
+
+Run `wtf <command> --help` for flags. Each command links to its reference page
+with examples.
+
+### Health & monitoring — [docs/AUDIT.md](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md)
+
+| command | what it does |
+|---------|--------------|
+| [`wtf` / `wtf audit`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-audit) | green/yellow/red checklist of what is OK and what is not |
+| [`wtf problems`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-problems) | only the WARN+FAIL rows |
+| [`wtf daily`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-daily) | morning check: audit + diff vs last run + events |
+| [`wtf explain`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-explain) | actionable advice per finding; `--llm` to pipe to an LLM |
+| [`wtf events`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-events) | timeline: reboots, OOM kills, failed units, … |
+| [`wtf logs`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-logs) | recent ERROR+ journal entries grouped by service |
+| [`wtf services`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-services) | drill into one unit: state, restarts, ports, journal |
+| [`wtf diff`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-diff) | compare current state to a saved snapshot |
+| [`wtf history`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-history) | list saved audit snapshots |
+| [`wtf crontab`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-crontab) | validate system + per-user crontabs |
+| [`wtf doctor`](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md#wtf-doctor) | self-diagnostic: which tools/files wtf can use |
+
+### Resource views — [docs/RESOURCES.md](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md)
+
+| command | what it does |
+|---------|--------------|
+| [`wtf disk [PATH]`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-disk) | mounts overview; with a PATH, the largest folders; `--tree` drills in |
+| [`wtf cpu`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-cpu) | load, iowait, pressure, top CPU consumers |
+| [`wtf mem`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-mem) | RAM/swap, OOM kills, top memory consumers |
+| [`wtf net`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-net) | interfaces, gateway, DNS, errors, listening ports |
+| [`wtf io`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-io) | per-device IO rates, pressure, stuck processes |
+| [`wtf who`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-who) | logged-in users, recent logins, failed auth |
+| [`wtf temp`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-temp) | hardware temperatures from /sys/class/hwmon |
+| [`wtf info`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-info) | one-page snapshot: all of the above at once |
+| [`wtf top`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-top) | focused process top: sort by cpu/rss, filter by user/name |
+| [`wtf ports` / `wtf port N`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-ports) | listening sockets; drill one port to PID, exe, cwd |
+| [`wtf docker [NAME]`](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md#wtf-docker) | container compose dir + image/container/log sizes |
+
+### Output & configuration
+
+| command | what it does |
+|---------|--------------|
+| [`wtf config`](https://github.com/wachawo/wtftools/blob/main/docs/CONFIG.md#wtf-config) | show effective config / print a commented example |
+| [`wtf completion`](#install) | print a bash/zsh `<Tab>`-completion script |
+| [machine output](https://github.com/wachawo/wtftools/blob/main/docs/OUTPUT.md) | `plain`/`json` formats and a grep·awk·jq cookbook |
+
+`wtftools` absorbs and supersedes
+[`checkcrontab`](https://github.com/wachawo/checkcrontab) — the same cron
+validator now lives at `wtf crontab`.
+
+## Documentation
+
+- [QUICKSTART.md](https://github.com/wachawo/wtftools/blob/main/docs/QUICKSTART.md) — 5-minute onboarding and a cheat sheet
+- [AUDIT.md](https://github.com/wachawo/wtftools/blob/main/docs/AUDIT.md) — health checks, monitoring, exit codes, the full check list
+- [RESOURCES.md](https://github.com/wachawo/wtftools/blob/main/docs/RESOURCES.md) — per-resource views with examples
+- [OUTPUT.md](https://github.com/wachawo/wtftools/blob/main/docs/OUTPUT.md) — `plain`/`json` formats and the scripting cookbook
+- [CONFIG.md](https://github.com/wachawo/wtftools/blob/main/docs/CONFIG.md) — config file, thresholds, ignoring checks
+
+## Compatibility
+
+- Python 3.9+
+- Linux (systemd distributions are the happy path; the tool degrades
+  gracefully when `systemctl` / `journalctl` / `psutil` are missing)
+- No network access required for the core CLI; optional network only for
+  `wtf explain --llm …` and `wtf doctor --check-updates`
+
+## From source
+
+```bash
+git clone https://github.com/wachawo/wtftools
+cd wtftools
+pip install -e .
+python3 wtf.py audit       # or run it without installing
+```
+
+## License
+
+MIT

wtftools-0.0.0/scripts/wtf.bash-completion → wtftools-0.0.2/completions/wtf

@@ -1,5 +1,6 @@
 # bash completion for `wtf` / `wtftools`
-# Install: copy to /etc/bash_completion.d/ or `source` from your bashrc.
+# Enable:  eval "$(wtf completion bash)"   (add that line to ~/.bashrc),
+#          or copy this script to /etc/bash_completion.d/wtf
 
 _wtf_complete() {
     local cur prev cmd
@@ -7,8 +8,8 @@ _wtf_complete() {
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-    local subcommands="info audit problems crontab doctor services config logs explain history diff top ports events"
-    local global_opts="-h --help -V --version --no-color -v --verbose -q --quiet --config"
+    local subcommands="info disk cpu mem net io who temp temps temperature daily audit problems crontab doctor services service config logs explain history diff top ports port docker events completion"
+    local global_opts="-h --help -V --version -f --format --no-color -v --verbose -q --quiet --config"
 
     if [[ $COMP_CWORD -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "$subcommands $global_opts" -- "$cur") )
@@ -20,8 +21,36 @@ _wtf_complete() {
     case "$cmd" in
         info)
             COMPREPLY=( $(compgen -W "--format" -- "$cur") )
+            [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text plain json" -- "$cur") )
+            ;;
+        daily)
+            COMPREPLY=( $(compgen -W "--since --ignore --strict --exit-zero --format" -- "$cur") )
             [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text json" -- "$cur") )
             ;;
+        disk)
+            local opts="--tree --depth --top --format --show-commands"
+            case "$prev" in
+                --format)        COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
+                --tree|--depth|--top) return 0 ;;
+            esac
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -d -- "$cur") )   # a PATH to break down
+            fi
+            ;;
+        cpu|net|io)
+            COMPREPLY=( $(compgen -W "--format --show-commands" -- "$cur") )
+            [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text plain json" -- "$cur") )
+            ;;
+        mem|who)
+            COMPREPLY=( $(compgen -W "--since --format --show-commands" -- "$cur") )
+            [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text plain json" -- "$cur") )
+            ;;
+        temp|temps|temperature)
+            COMPREPLY=( $(compgen -W "--format" -- "$cur") )
+            [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text plain json" -- "$cur") )
+            ;;
         audit|problems)
             local opts="--format --strict --exit-zero --check --only --since --list-checks --brief -b --ignore --serial --check-timeout --alert --alert-on --save --output -o"
             case "$prev" in
@@ -72,23 +101,30 @@ updates reboot cron-daemon crontab docker hw-temp smart dns http-probes tcp-prob
             local opts="--sort --limit --user --name --format"
             case "$prev" in
                 --sort)   COMPREPLY=( $(compgen -W "cpu rss" -- "$cur") ); return 0 ;;
-                --format) COMPREPLY=( $(compgen -W "text json" -- "$cur") ); return 0 ;;
+                --format) COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
                 --user)   COMPREPLY=( $(compgen -u -- "$cur") ); return 0 ;;
             esac
             COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
             ;;
-        ports)
+        ports|port)
             local opts="--proto --public-only --format"
             case "$prev" in
                 --proto)  COMPREPLY=( $(compgen -W "tcp udp all" -- "$cur") ); return 0 ;;
-                --format) COMPREPLY=( $(compgen -W "text json" -- "$cur") ); return 0 ;;
+                --format) COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
             esac
             COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
             ;;
-        services)
+        docker)
+            case "$prev" in
+                --format) COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
+            esac
+            local names=$(docker ps --format '{{.Names}}' 2>/dev/null)
+            COMPREPLY=( $(compgen -W "--format $names" -- "$cur") )
+            ;;
+        services|service)
             local opts="-n --lines --format"
             case "$prev" in
-                --format) COMPREPLY=( $(compgen -W "text json" -- "$cur") ); return 0 ;;
+                --format) COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
             esac
             local units=$(systemctl list-units --type=service --no-legend --plain 2>/dev/null \
                           | awk '{ sub(/\.service$/, "", $1); print $1 }')
@@ -98,14 +134,14 @@ updates reboot cron-daemon crontab docker hw-temp smart dns http-probes tcp-prob
             local opts="--since --kind --limit --format"
             case "$prev" in
                 --kind)   COMPREPLY=( $(compgen -W "reboot oom failed-unit kernel-err auth-fail login" -- "$cur") ); return 0 ;;
-                --format) COMPREPLY=( $(compgen -W "text json" -- "$cur") ); return 0 ;;
+                --format) COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
             esac
             COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
             ;;
         logs)
             local opts="--since --priority -p --units --lines -n --format"
             case "$prev" in
-                --format)      COMPREPLY=( $(compgen -W "text json" -- "$cur") ); return 0 ;;
+                --format)      COMPREPLY=( $(compgen -W "text plain json" -- "$cur") ); return 0 ;;
                 --priority|-p) COMPREPLY=( $(compgen -W "emerg alert crit err warning notice info debug" -- "$cur") ); return 0 ;;
             esac
             COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
@@ -127,6 +163,9 @@ updates reboot cron-daemon crontab docker hw-temp smart dns http-probes tcp-prob
             COMPREPLY=( $(compgen -W "--example --format" -- "$cur") )
             [[ "$prev" == "--format" ]] && COMPREPLY=( $(compgen -W "text json" -- "$cur") )
             ;;
+        completion)
+            COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
+            ;;
     esac
 }