WITR(1)

okay so welcome to WITR(1) — that's section 1 of the manual, bestie 💖 — aka the little tool that answers the question every sysadmin screams at 3am: "WHY is this thing running?!" Let's get into it. 🫶

---

🎀 NAME 🎀

witr — Why is this running? 💅

That's it, that's the whole name. Short, iconic, does exactly what it says on the tin. ✨

---

🌸 SYNOPSIS 🌸

witr [process name...] [flags]

So you give it a process name (or a bunch of them, she's flexible 🌈) and then whatever flags your heart desires. Simple as. 🦋

---

🦋 DESCRIPTION 🦋

Okay so here's the vibe: witr tells you why a process or a port is running, by tracing its ancestry 👑. Like, it goes up the family tree — who started this, who started them, all the way back — so you can finally figure out where this random daemon came from. It's giving detective energy 🔍✨. No more squinting at ps output wondering who's your daddy. Periodt.

---

💅 OPTIONS 💅

The menu, mwah 😘 — every single one, no skipping:

• --env[=false] — spills the tea on the process's environment variables 🍵 (all the env stuff it's running with).
• -x, --exact[=false] — match the name exactly, no substring search. So if you say bun, she looks for bun, not bunny or bundle 🙈.
• -f, --file=[] — hand her a file path (or several — she's repeatable 💫) and she'll hunt down the process holding it.
• -h, --help[=false] — the help, for witr. Your girl's got you 🫶.
• -i, --interactive[=false] — interactive mode, aka a whole TUI. Main character energy, you get to poke around 💅.
• --json[=false] — hand the result back as JSON, machine-readable and clean. For the script girlies 🤖✨.
• --no-color[=false] — kills the colorized output. Perfect for CI or when you're piping things around 🚫🌈.
• -p, --pid=[] — look stuff up by pid(s). Repeatable, so stack 'em up 📚.
• -o, --port=[] — look up port(s). Also repeatable bestie, go wild 🌊.
• -s, --short[=false] — just the ancestry, nothing else. Short king output 👑.
• -t, --tree[=false] — the ancestry, but as a tree 🌳. Aesthetic and informative.
• --verbose[=false] — the extended process info: she says more, she shows more 💬.
• --warnings[=false] — only the warnings, nothing but the warnings. Sometimes that's all you need 🚨.

---

🔥 EXAMPLE 🔥

Okay the receipts, let's go — every single one, verbatim:

# Inspect a running process by name
witr nginx

# Look up a process by PID
witr --pid 1234

# Find the process listening on a specific port
witr --port 5432

# Find the process holding a lock on a file
witr --file /var/lib/dpkg/lock

# Inspect a process by name with exact matching (no fuzzy search)
witr bun --exact

# Show the full process ancestry (who started whom)
witr postgres --tree

# Show only warnings (suspicious env, arguments, parents)
witr docker --warnings

# Display only environment variables of the process
witr node --env

# Short, single-line output (useful for scripts)
witr sshd --short

# Disable colorized output (CI or piping)
witr redis --no-color

# Output machine-readable JSON
witr chrome --json

# Show extended process information (memory, I/O, file descriptors)
witr mysql --verbose

# Combine flags: inspect port, show environment variables, output JSON
witr --port 8080 --env --json

# Multiple inputs
witr nginx node
witr --port 8080 --port 3000
witr --pid 1234 --pid 5678

# Mixed inputs
witr nginx --pid 1234 --port 8080

See how she just gets it? Names, pids, ports, files, all mixed together like a little charcuterie board of debugging 🧀🍓. Slay.

---

and that's the whole page, bestie 🦋 — this was WITR(1), dropped Apr 2026, and yeah we're still section 1 because some things never change 💜. Go find out why that process is running. You've got this. ✨👑💖