witr
Why is this running?
Trace any process, port, container, or file back to the exact chain that started it —
one command, machine-readable JSON, or an interactive TUI.
Investigate a simulated Linux box — a guided tutorial and free-play sandbox, no install required.
1. Purpose
witr exists to answer a single question:
Why is this running?
When something is running on a system, whether it is a process, a service, or something bound to a port, there is always a cause. That cause is often indirect, non-obvious, or spread across multiple layers such as supervisors, containers, services, or shells.
Existing tools (ps, top, lsof, ss, systemctl, docker ps) expose state and metadata. They show what is running, but leave the user to infer why by manually correlating outputs across tools.
witr makes that causality explicit.
It explains where a running thing came from, how it was started, and what chain of systems is responsible for it existing right now, in a single, human-readable output or an interactive TUI dashboard.
📖 Curious how witr came to be? Read the story or browse the Hacker News discussion.
2. Installation
witr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.
witr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on Repology. Please note that community packages may lag GitHub releases due to independent review and validation.
[!TIP]
If you use a package manager (Homebrew, Conda, Winget, etc.), we recommend installing via that for easier updates. Otherwise, the install script is the quickest way to get started.
2.1 Quick Install
Unix (Linux, macOS & FreeBSD)
curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash
Script Details
The script will:
- Detect your operating system (
linux, darwin or freebsd)
- Detect your CPU architecture (
amd64 or arm64)
- Download the latest released binary and man page
- Install it to
/usr/local/bin/witr
- Install the man page to
/usr/local/share/man/man1/witr.1
- Pass INSTALL_PREFIX to override default install path
Windows (PowerShell)
irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex
Script Details
The script will:
- Download the latest release (zip) and verify checksum.
- Extract
witr.exe to %LocalAppData%\witr\bin.
- Add the bin directory to your User
PATH.
2.2 Package Managers
APT (Debian, Ubuntu & Derivatives) 
You can install witr from the official Debian and Ubuntu repositories (Ubuntu 26.04+, Debian sid and later), as well as derivative distributions like Kali Linux, Devuan, and Raspbian:
sudo apt install witr
Note: The apt-shipped version may lag the latest GitHub release. For the newest features, use the install script or another installation method.
Homebrew (macOS & Linux) 
You can install witr using Homebrew on macOS or Linux:
brew install witr
MacPorts (macOS) 
You can install witr using MacPorts on macOS:
sudo port install witr
Conda (macOS, Linux & Windows) 
You can install witr using conda, mamba, or pixi on macOS, Linux, and Windows:
conda install -c conda-forge witr
# alternatively using mamba
mamba install -c conda-forge witr
# alternatively using pixi
pixi global install witr
Arch Linux (AUR) 
On Arch Linux and derivatives, install from the AUR package:
yay -S witr-bin
# alternatively using paru
paru -S witr-bin
# or use your preferred AUR helper
Winget (Windows) 
You can install witr via winget:
winget install -e --id PranshuParmar.witr
NPM (Cross-platform) 
You can install witr using npm:
npm install -g @pranshuparmar/witr
FreeBSD Ports 
You can install witr on FreeBSD from the FreshPorts port:
pkg install witr
# or
pkg install sysutils/witr
Or build from Ports:
cd /usr/ports/sysutils/witr/
make install clean
Chocolatey (Windows) 
You can install witr using Chocolatey:
choco install witr
Scoop (Windows) 
You can install witr using Scoop:
scoop install main/witr
AOSC OS 
You can install witr from the AOSC OS repository:
oma install witr
GNU Guix 
You can install witr from the GNU Guix repository:
guix install witr
Uniget (Linux) 
You can install witr using uniget:
uniget install witr
Aqua (macOS, Linux & Windows) 
You can install witr using aqua:
# Add package
aqua g -i pranshuparmar/witr
# Install package
aqua i pranshuparmar/witr
Brioche (Linux) 
You can install witr using brioche:
brioche install -r witr
Mise (macOS, Linux & Windows) 
You can install witr using mise:
mise use github:pranshuparmar/witr
Prebuilt Packages (deb, rpm, apk)
witr provides native packages for major Linux distributions. You can download the latest .deb, .rpm, or .apk package from the GitHub releases page.
Generic download command using curl:
# Replace <package name with the actual package that you need>
curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/<package-name>
Debian/Ubuntu (.deb):
sudo dpkg -i ./witr-*.deb
# Or, using apt for dependency resolution:
sudo apt install ./witr-*.deb
Fedora/RHEL/CentOS (.rpm):
sudo rpm -i ./witr-*.rpm
Alpine Linux (.apk):
sudo apk add --allow-untrusted ./witr-*.apk
2.3 Source & Manual Installation
Go (cross-platform)
You can install the latest version directly from source:
go install github.com/pranshuparmar/witr/cmd/witr@latest
This will place the witr binary in your $GOPATH/bin or $HOME/go/bin directory. Make sure this directory is in your PATH.
Manual Installation
If you prefer manual installation, follow these simple steps for your platform:
Unix (Linux, macOS, FreeBSD)
# 1. Determine OS and Architecture
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
[ "$ARCH" = "x86_64" ] && ARCH="amd64"
[ "$ARCH" = "aarch64" ] && ARCH="arm64"
# 2. Download the binary
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr
# 3. Verify checksum (Optional)
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -o SHA256SUMS
grep "witr-${OS}-${ARCH}" SHA256SUMS | (sha256sum -c - 2>/dev/null || shasum -a 256 -c - 2>/dev/null)
rm SHA256SUMS
# 4. Rename and install
chmod +x witr
sudo mkdir -p /usr/local/bin
sudo mv witr /usr/local/bin/witr
# 5. Install man page (Optional)
sudo mkdir -p /usr/local/share/man/man1
sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1
Windows (PowerShell)
# 1. Determine Architecture
if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
$ZipName = "witr-windows-amd64.zip"
} elseif ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
$ZipName = "witr-windows-arm64.zip"
} else {
Write-Error "Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)"
exit 1
}
# 2. Download the zip
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"
# 3. Extract the binary
Expand-Archive -Path "witr.zip" -DestinationPath "." -Force
# 4. Verify checksum (Optional)
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -OutFile "SHA256SUMS"
$hash = Get-FileHash -Algorithm SHA256 .\witr.zip
$expected = Select-String -Path .\SHA256SUMS -Pattern $ZipName
if ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) { Write-Host "Checksum OK" } else { Write-Host "Checksum Mismatch" }
# 5. Install to local bin directory
$InstallDir = "$env:LocalAppData\witr\bin"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Move-Item .\witr.exe $InstallDir\witr.exe -Force
# 6. Add to User Path (Persistent)
$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($UserPath -notlike "*$InstallDir*") {
[Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
$env:Path += ";$InstallDir"
Write-Host "Added to Path. You may need to restart PowerShell."
}
# 7. Cleanup
Remove-Item witr.zip
Remove-Item SHA256SUMS
2.4 Run Without Installation
Nix Flake
If you use Nix, you can build witr from source and run without installation:
nix run github:pranshuparmar/witr -- --help
Pixi
If you use pixi, you can run without installation on Linux or macOS:
pixi exec witr --help
2.5 Other Operations
Verify Installation
witr --version
man witr
Shell Completions
witr supports tab completion for all flags. To enable it, add the appropriate line to your shell configuration:
Bash
echo 'eval "$(witr completion bash)"' >> ~/.bashrc
source ~/.bashrc
Zsh
echo 'eval "$(witr completion zsh)"' >> ~/.zshrc
source ~/.zshrc
Fish
witr completion fish | source
# To make it permanent:
witr completion fish > ~/.config/fish/completions/witr.fish
PowerShell
witr completion powershell | Out-String | Invoke-Expression
# To make it permanent, add the above line to your $PROFILE
Uninstallation
If you installed via a package manager (Homebrew, Conda, etc.), please use the respective uninstall command (e.g., brew uninstall witr).
To completely remove script/manual installation of witr:
Unix (Linux, macOS, FreeBSD)
sudo rm -f /usr/local/bin/witr
sudo rm -f /usr/local/share/man/man1/witr.1
Windows
Remove-Item -Recurse -Force "$env:LocalAppData\witr"
3. Interactive Mode (TUI)
Running witr without any arguments or with the -i flag launches the Interactive Mode (TUI). This provides a real-time, terminal-based dashboard with four tabs for exploring processes, ports, containers, and file locks.
Key Features:
- Processes Tab: Live, sortable, filterable list of all running processes with a side panel showing the ancestry tree of the highlighted process.
- Ports Tab: Open/listening ports with the owning processes attached in a side panel. Toggle between LISTEN-only and ALL with
a.
- Containers Tab: All running containers across Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails in one list - name, image, status, ports, command, plus a per-container detail view with mounts, networks, and compose project metadata.
- Locks Tab: System-wide file locks (POSIX/FLOCK on Linux, lsof-derived on macOS/FreeBSD). Press
a to switch into "all open files" mode, where locked entries are merged with every interesting open fd; type into / to search across the merged set.
- Process Details: Deep-dive into a process to see its full ancestry tree, child processes, environment variables, working directory, sockets, file context, and more.
- Process Actions: Send signals (Kill, Terminate, Pause, Resume) or Renice processes directly from the UI (Unix only).
- Mouse Support: Navigate, sort columns, and click rows using your mouse.
- Adaptive Theme: Colors adapt automatically to light and dark terminal backgrounds.
- Auto-Refresh: The process, port, container, and lock lists refresh automatically on an adaptive cadence (starts at 3 seconds, backing off under load).
4. Flags & Options
-c, --container strings container(s) to look up (repeatable)
--env show environment variables for the process
-x, --exact use exact name matching (no substring search)
-f, --file strings file(s) held open by a process (repeatable)
-h, --help help for witr
-i, --interactive interactive mode (TUI)
--json show result as JSON
--no-color disable colorized output
-p, --pid strings pid(s) to look up (repeatable)
-o, --port strings port(s) to look up (repeatable)
-s, --short show only ancestry
-t, --tree show only ancestry as a tree
--verbose show extended process information
-v, --version version for witr
--warnings show only warnings
Positional argument
witr answers one question: 'why is this running?' Point it at a process, port, container, or file, and it traces the exact chain of supervisors, services, and shells that started it.