Your first trace

The fastest way to understand witr is to point it at something that is already running on your machine.

Ask about a process by name

witr node

Names use substring matching by default, so witr ng will find both nginx and ngrok. Add --exact (or -x) when you want only exact matches.

Read the answer

Target      : node

Process     : node (pid 14233)
User        : pm2
Command     : node index.js
Started     : 2 days ago (Mon 2025-02-02 11:42:10 +05:30)

Why It Exists :
  systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)

Source      : pm2

Working Dir : /opt/apps/expense-manager
Git Repo    : expense-manager (main)
Sockets     : 127.0.0.1:5001 (TCP | LISTENING)

The Why It Exists line is the point of the tool. Everything else is context around it. See Output Sections for what each block means.

Handle multiple matches

When several processes match, witr lists them instead of guessing:

Multiple matching processes found:

[1] nginx (pid 2311)
    nginx -g daemon off;
[2] ngrok (pid 14233)
    ngrok http 5000

Re-run with:
  witr --pid <pid>

Narrow the output

Once you know which process you care about, choose how much you want to see:

witr --pid 14233 --short    # just the ancestry chain, one line
witr --pid 14233 --tree     # ancestry plus children, as a tree
witr --pid 14233 --verbose  # extended process information
witr --pid 14233 --warnings # only the warnings

Ask about something that is not a process

Ports, files and containers all resolve to a PID, then take the same path:

witr --port 8000
witr --file /var/lib/dpkg/lock
witr --container redis

Mixing targets in one command#

Every target flag is repeatable and they can be combined. Results appear in the order you typed them, with labeled dividers.

witr nginx --port 5432 --pid 1234

All output modes work with multiple inputs, including --json.

Next: the Why It Exists chain explained, or query by port for the most common real-world case.