Metadata-Version: 2.4
Name: wtftools
Version: 0.0.1
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.8
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.8
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%)
[ OK ] zombie processes        0 zombies
[FAIL] failed systemd units    1 failed unit(s)
[ OK ] crontab syntax          14 cron line(s), no errors

  Summary: 12 ok · 1 warn · 1 fail · 2 skip
```

Green is fine, yellow needs a look, red needs fixing. That's it.

## Install

```bash
pipx install wtftools          # recommended — works on any modern distro
```

No `pipx`? Any of these works too:

```bash
pip install wtftools           # classic pip (core, no dependencies)
pip install wtftools[full]     # + psutil for richer process/socket info
sudo dpkg -i wtftools_*.deb    # Debian/Ubuntu package (see Releases)
```

After install you have the `wtf` command. Try it: `wtf`.

## The commands you will actually use

```bash
wtf              # full health check — start here
wtf problems     # show ONLY what is wrong (warnings + failures)
wtf explain      # what to do about each problem, step by step
```

Then ask about one resource at a time, like `show` commands on a switch:

```bash
wtf disk         # is there space? per-mount usage, inodes, read-only
wtf disk --tree  # WHAT is eating the space (largest directories)
wtf cpu          # load, iowait, top CPU consumers
wtf mem          # RAM/swap, OOM kills, top memory consumers
wtf net          # interfaces, IPs, gateway, DNS, listening ports
wtf io           # disk read/write rates, IO-stuck processes
wtf who          # who is logged in, recent logins, failed auth
```

Example — disk is filling up, find the culprit:

```
$ wtf disk --tree /var
────────────── DISK ──────────────
  /                [████████████████····]  79%  1.4TB / 1.8TB  ext4
  /var             [█████████████████···]  85%  17.0GB / 20.0GB  ext4

───────── LARGEST UNDER /var ─────────
      15.0GB  /var/lib
       3.1GB  /var/log
       1.8GB  /var/log/app
```

`wtf disk --tree` without a path picks the fullest mount automatically.

Learning Linux? Add `--show-commands` to any resource command and it also
prints the classic commands it replaces, so you can run them yourself:

```
$ wtf cpu --show-commands
  ...
  equivalent commands:
    $ uptime
    $ top -bn1 | head
    $ ps aux --sort=-%cpu | head
```

## When something is broken

```bash
wtf problems -v                 # every problem, with detail
wtf events --since 6            # timeline: reboots, OOM kills, failed units
wtf service nginx               # one service: state, restarts, ports, journal
wtf logs --since '2 hours ago'  # recent ERROR+ journal entries by service
wtf explain                     # actionable advice per finding
wtf explain --llm ollama        # or let a local LLM summarize it
```

## Output for scripts: grep, awk, jq

Colors disappear automatically when you pipe, so plain `grep` always works.
Every command also has machine-readable formats — `plain` (tab-separated,
no headers) and `json`. The flag works before the subcommand too:

```bash
wtf -f json disk                         # same as: wtf disk --format json
wtf disk --format plain                  # tab-separated, no headers
wtf disk --format json | jq .            # full JSON

# mounts above 80%:
wtf disk --format json | jq -r '.mounts[] | select(.percent > 80) | .target'

# failed checks only, names column:
wtf audit --format plain | awk -F'\t' '$1 == "fail" {print $2}'

# top directory eating /var, bytes and path:
wtf disk --tree /var --format plain | awk -F'\t' '$1 == "tree" {print $2, $3; exit}'
```

JSON payloads of the resource commands carry `schema_version` so your
scripts survive upgrades.

## Daily routine and monitoring

One command for the morning check — audit, what changed since the last run,
and the event timeline, with a one-line verdict on top:

```bash
wtf daily                       # audit + diff vs yesterday + events
```

It saves a snapshot on every run, so tomorrow's `wtf daily` shows the diff.
A crontab line for unattended use (mails only when something is wrong):

```cron
0 8 * * * wtf daily --format json > /var/log/wtf-daily.json 2>&1 || mail -s "wtf $(hostname)" you@example.com < /var/log/wtf-daily.json
```

The building blocks are also available separately:

```bash
wtf audit --brief               # one line — perfect for MOTD / SSH banner
wtf audit --save                # save a snapshot
wtf diff                        # what changed since the last snapshot
wtf history                     # list saved snapshots

# cron alerting without any monitoring stack:
wtf audit --alert 'mail -s "wtf $WTF_HOST" you@example.com'
wtf audit --alert-on warn --alert 'curl -X POST $SLACK_WEBHOOK -d @-'
```

Exit codes are CI/cron-friendly:

| code | meaning                                          |
|------|--------------------------------------------------|
| 0    | everything OK                                    |
| 1    | warnings with `--strict`, or crontab errors      |
| 2    | audit found a `[FAIL]`                           |
| 130  | interrupted (Ctrl-C)                             |

## All subcommands

| command             | what it does                                                |
|---------------------|-------------------------------------------------------------|
| `wtf` / `wtf audit` | green/yellow/red checklist: what is OK and what is not      |
| `wtf problems`      | only WARN+FAIL rows                                         |
| `wtf daily`         | morning check: audit + diff vs last run + events            |
| `wtf explain`       | per-check actionable advice; `--llm` to pipe to an LLM      |
| `wtf disk`          | per-mount usage; `--tree` shows largest directories         |
| `wtf cpu`           | load, iowait, pressure, top CPU consumers                   |
| `wtf mem`           | RAM/swap, OOM kills, top memory consumers                   |
| `wtf net`           | interfaces, gateway, DNS, errors, listening ports           |
| `wtf io`            | per-device IO rates, pressure, stuck processes              |
| `wtf who`           | logged-in users, recent logins, failed auth                 |
| `wtf info`          | one-page snapshot: all of the above at once                 |
| `wtf top`           | focused process top: sort by cpu/rss, filter user/name      |
| `wtf ports`         | listening sockets with owning PID/user/command              |
| `wtf service NAME`  | drilldown one service: state, restarts, mem, ports, journal |
| `wtf logs`          | recent ERROR+ journal entries grouped by service            |
| `wtf events`        | chronological timeline: reboots, OOM, failed units, …       |
| `wtf history`       | list saved audit snapshots (`wtf audit --save` to create)   |
| `wtf diff`          | compare current state to a saved snapshot                   |
| `wtf crontab`       | validate all standard crontab locations + per-user crontabs |
| `wtf doctor`        | self-diagnostic: which tools wtftools can actually use      |
| `wtf config`        | show effective config / print example                       |

`wtftools` absorbs and supersedes
[`checkcrontab`](https://github.com/wachawo/checkcrontab) — the same cron
validator now lives at `wtf crontab`.

## Advanced audit options

```bash
wtf audit -v             # show extra detail (failed units, OOM events)
wtf audit --strict       # exit 1 on warnings (CI-friendly)
wtf audit --check memory --check disks    # run named checks only
wtf audit --list-checks  # show all available check short-names
wtf audit --since 1      # look-back window for OOM/auth/kernel (default 24h)
wtf audit --ignore swap --ignore "disk /mnt/Backup"   # silence checks
wtf audit --format csv > audit.csv        # spreadsheet-friendly
wtf audit --format html -o report.html    # self-contained HTML for tickets
wtf audit --format prometheus             # metrics for node_exporter textfile
```

### Built-in checks

uptime · system state · load average · CPU iowait · PSI cpu/memory/io ·
TCP retransmits · memory · swap · disk (per mount) · inodes ·
read-only mounts · failed systemd units · enabled-but-down services ·
restart loops · network errors · conntrack · journal disk usage · zombies ·
D-state processes · OOM kills · kernel errors · kernel taint · cert expiry ·
open file descriptors · process count · failed auth · time sync ·
pending updates · reboot required · cron daemon · crontab syntax · docker ·
hw temperatures · disk SMART · DNS · HTTP/TCP probes · fail2ban.

## Config

Thresholds and ignores live in an INI file at any of:

- `/etc/wtftools/config.ini`
- `/etc/wtf/config.ini`
- `~/.config/wtftools/config.ini`

Run `wtf config --example` for a fully-commented template. Headlines:

```ini
[thresholds]
disk_warn = 85
disk_fail = 95
swap_warn = 50
swap_fail = 90

[ignore]
checks = swap, updates
result_names =
    disk /mnt/Backup
```

## Compatibility

- Python 3.8+
- 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: `wtf explain --llm claude/openai`, `wtf doctor --check-updates`

## From source

```bash
git clone https://github.com/wachawo/wtftools
cd wtftools
pip install -e .
# or test without installing:
python3 wtf.py audit
```

## License

MIT
