witr-process-inspector

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

witr — Why Is This Running?

witr — 这个进程为什么在运行？

Skill by ara.so — Daily 2026 Skills collection.

witr is a Go CLI/TUI tool that answers "why is this running?" for any process, service, or port. Instead of leaving you to correlate

ps

lsof

ss

systemctl

, and

docker ps

manually, witr makes the causality chain explicit — showing where a running thing came from, how it was started, and what chain of supervisors/containers/shells is responsible.

来自ara.so的技能工具 — 2026每日技能合集。

witr是一款基于Go语言开发的CLI/TUI工具，用于解答“这个进程为什么在运行？”的问题，适用于任意进程、服务或端口。它无需你手动关联

ps

、

lsof

、

ss

、

systemctl

和

docker ps

等命令的输出，而是直接明确展示因果链——包括运行中的程序来源、启动方式，以及负责的监控程序/容器/Shell层级。

Installation

安装

Quickest (Unix)

最快安装方式（Unix系统）

bash

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

bash

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

Quickest (Windows PowerShell)

最快安装方式（Windows PowerShell）

powershell

irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

powershell

irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

Package Managers

包管理器安装

bash

undefined

bash

undefined

Homebrew (macOS/Linux)

Homebrew（macOS/Linux）

brew install witr

Conda

conda install -c conda-forge witr

Arch Linux (AUR)

Arch Linux（AUR）

yay -S witr-bin

Windows winget

winget install -e --id PranshuParmar.witr

Windows Scoop

scoop install main/witr

Alpine / apk

sudo apk add --allow-untrusted ./witr-*.apk

Go source install

Go源码安装

go install github.com/pranshuparmar/witr/cmd/witr@latest

---

go install github.com/pranshuparmar/witr/cmd/witr@latest

---

Key Commands & Flags

核心命令与参数

Basic Usage

基础用法

bash

undefined

bash

undefined

Inspect a process by PID

通过PID检查进程

witr <pid>

Inspect by process name (substring match)

通过进程名检查（子串匹配）

witr <name>

Inspect what's bound to a port

检查绑定到指定端口的进程

witr --port <port> witr -p <port>

Launch interactive TUI dashboard

启动交互式TUI仪表盘

witr --interactive witr -i

Show all running processes with causality info

显示所有运行中进程及因果链信息

witr --all witr -a

Output as JSON (for scripting)

以JSON格式输出（用于脚本）

witr --json <pid>

Follow/watch mode — refresh automatically

跟踪/监控模式 — 自动刷新

witr --watch <pid> witr -w <pid>

Verbose output — show full environment and metadata

详细输出 — 显示完整环境变量和元数据

witr --verbose <pid> witr -v <pid>

Filter processes by user

按用户筛选进程

witr --user <username>

Show version

显示版本

witr --version

undefined

witr --version

undefined

Common Flag Reference

常用参数参考

Flag	Short	Description
`--port`	`-p`	Inspect by port number
`--interactive`	`-i`	Launch TUI dashboard
`--all`	`-a`	Show all processes
`--json`		Output as JSON
`--watch`	`-w`	Auto-refresh/follow
`--verbose`	`-v`	Full metadata output
`--user`		Filter by OS user
`--version`		Print version

参数	缩写	描述
`--port`	`-p`	通过端口号检查
`--interactive`	`-i`	启动TUI仪表盘
`--all`	`-a`	显示所有进程
`--json`		以JSON格式输出
`--watch`	`-w`	自动刷新/跟踪
`--verbose`	`-v`	输出完整元数据
`--user`		按系统用户筛选
`--version`		打印版本信息

Interactive TUI Mode

交互式TUI模式

Launch the full dashboard:

bash

witr -i

启动完整仪表盘：

bash

witr -i

or

或

witr --interactive


**TUI Keybindings:**
| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate process list |
| `Enter` | Expand process detail / causality chain |
| `f` | Filter/search processes |
| `s` | Sort by column |
| `r` | Refresh |
| `j` | Toggle JSON view |
| `q` / `Ctrl+C` | Quit |

---

witr --interactive


**TUI快捷键：**
| 按键 | 操作 |
|-----|--------|
| `↑` / `↓` | 导航进程列表 |
| `Enter` | 展开进程详情/因果链 |
| `f` | 筛选/搜索进程 |
| `s` | 按列排序 |
| `r` | 刷新 |
| `j` | 切换JSON视图 |
| `q` / `Ctrl+C` | 退出 |

---

Example Outputs

示例输出

Inspect a PID

检查指定PID

bash

witr 1234

PID: 1234
Name: node
Binary: /usr/local/bin/node
Started: 2026-03-18 09:12:44
User: ubuntu

Why is this running?
  └─ Started by: npm (PID 1200)
       └─ Started by: bash (PID 1180)
            └─ Started by: sshd (PID 980)
                 └─ Started by: systemd (PID 1) [service: sshd.service]

bash

witr 1234

PID: 1234
名称: node
二进制路径: /usr/local/bin/node
启动时间: 2026-03-18 09:12:44
运行用户: ubuntu

运行原因:
  └─ 由以下进程启动: npm (PID 1200)
       └─ 由以下进程启动: bash (PID 1180)
            └─ 由以下进程启动: sshd (PID 980)
                 └─ 由以下进程启动: systemd (PID 1) [服务: sshd.service]

Inspect by Port

检查指定端口

bash

witr --port 8080

Port: 8080 (TCP, LISTEN)
Process: python3 (PID 4512)
Binary: /usr/bin/python3
User: deploy

Why is this running?
  └─ Started by: gunicorn (PID 4490)
       └─ Started by: systemd (PID 1) [service: myapp.service]
            Unit file: /etc/systemd/system/myapp.service
            ExecStart: /usr/bin/gunicorn app:app --bind 0.0.0.0:8080

bash

witr --port 8080

端口: 8080 (TCP, LISTEN)
进程: python3 (PID 4512)
二进制路径: /usr/bin/python3
运行用户: deploy

运行原因:
  └─ 由以下进程启动: gunicorn (PID 4490)
       └─ 由以下进程启动: systemd (PID 1) [服务: myapp.service]
            单元文件: /etc/systemd/system/myapp.service
            启动命令: /usr/bin/gunicorn app:app --bind 0.0.0.0:8080

JSON Output (for scripting)

JSON格式输出（用于脚本）

bash

witr --json 4512

json

{
  "pid": 4512,
  "name": "python3",
  "binary": "/usr/bin/python3",
  "user": "deploy",
  "started_at": "2026-03-18T09:00:00Z",
  "causality_chain": [
    {"pid": 4490, "name": "gunicorn", "type": "parent"},
    {"pid": 1,    "name": "systemd",  "type": "supervisor", "service": "myapp.service"}
  ]
}

bash

witr --json 4512

json

{
  "pid": 4512,
  "name": "python3",
  "binary": "/usr/bin/python3",
  "user": "deploy",
  "started_at": "2026-03-18T09:00:00Z",
  "causality_chain": [
    {"pid": 4490, "name": "gunicorn", "type": "parent"},
    {"pid": 1,    "name": "systemd",  "type": "supervisor", "service": "myapp.service"}
  ]
}

Watch/Follow a Process

跟踪/监控进程

bash

undefined

bash

undefined

Refresh every 2 seconds

每2秒刷新一次

witr --watch 4512

---

witr --watch 4512

---

Common Patterns

常见使用场景

Find Who Started a Port Listener

查找端口监听进程的启动来源

bash

undefined

bash

undefined

Quick check: who owns port 5432 (Postgres)?

快速检查：谁占用了端口5432（Postgres）？

witr --port 5432

Get machine-readable output for automation

获取机器可读输出用于自动化

witr --json --port 5432 | jq '.causality_chain[-1].service'

undefined

witr --json --port 5432 | jq '.causality_chain[-1].service'

undefined

Audit All Running Services

审计所有运行中的服务

bash

undefined

bash

undefined

List everything with causality, pipe to less

列出所有进程及因果链，通过less查看

witr --all | less

Export full audit to JSON

将完整审计结果导出为JSON

witr --all --json > audit.json

undefined

witr --all --json > audit.json

undefined

Inspect a Docker/Container Process

检查Docker/容器化进程

bash

undefined

bash

undefined

witr understands container boundaries

witr可以识别容器边界

witr <pid-of-containerized-process>

witr <容器化进程的PID>

Output will show: container → container runtime → systemd chain

输出会显示：容器 → 容器运行时 → systemd层级

undefined

undefined

Use in a Shell Script

在Shell脚本中使用

bash

#!/usr/bin/env bash

bash

#!/usr/bin/env bash

Check if port 8080 is in use and why

检查端口8080是否被占用及原因

if witr --json --port 8080 > /tmp/witr_out.json 2>/dev/null; then SERVICE=$(jq -r '.causality_chain[-1].service // "unknown"' /tmp/witr_out.json) echo "Port 8080 is owned by service: $SERVICE" else echo "Port 8080 is not in use" fi

undefined

if witr --json --port 8080 > /tmp/witr_out.json 2>/dev/null; then SERVICE=$(jq -r '.causality_chain[-1].service // "unknown"' /tmp/witr_out.json) echo "端口8080被以下服务占用: $SERVICE" else echo "端口8080未被占用" fi

undefined

Filter Processes by User

按用户筛选进程

bash

undefined

bash

undefined

Show only processes owned by www-data and why they're running

仅显示www-data用户的进程及其运行原因

witr --all --user www-data

---

witr --all --user www-data

---

Platform Support

平台支持

Platform	Architectures	Notes
Linux	amd64, arm64	Full support
macOS	amd64, arm64 (Apple Silicon)	Full support
Windows	amd64	Full support
FreeBSD	amd64, arm64	Full support

平台	架构	说明
Linux	amd64, arm64	完全支持
macOS	amd64, arm64（Apple Silicon）	完全支持
Windows	amd64	完全支持
FreeBSD	amd64, arm64	完全支持

Go Integration (Embedding witr Logic)

Go语言集成（嵌入witr逻辑）

If you want to use witr programmatically in a Go project:

bash

go get github.com/pranshuparmar/witr

package main

import (
    "fmt"
    "github.com/pranshuparmar/witr/pkg/inspector"
)

func main() {
    // Inspect a process by PID
    result, err := inspector.InspectPID(1234)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Process: %s\n", result.Name)
    for _, link := range result.CausalityChain {
        fmt.Printf("  └─ %s (PID %d)\n", link.Name, link.PID)
    }
}

// Inspect by port
result, err := inspector.InspectPort(8080, "tcp")
if err != nil {
    panic(err)
}
fmt.Printf("Port 8080 owned by PID %d (%s)\n", result.PID, result.Name)

如果你想在Go项目中以编程方式使用witr：

bash

go get github.com/pranshuparmar/witr

package main

import (
    "fmt"
    "github.com/pranshuparmar/witr/pkg/inspector"
)

func main() {
    // 通过PID检查进程
    result, err := inspector.InspectPID(1234)
    if err != nil {
        panic(err)
    }

    fmt.Printf("进程: %s\n", result.Name)
    for _, link := range result.CausalityChain {
        fmt.Printf("  └─ %s (PID %d)\n", link.Name, link.PID)
    }
}

// 通过端口检查
result, err := inspector.InspectPort(8080, "tcp")
if err != nil {
    panic(err)
}
fmt.Printf("端口8080被PID %d (%s)占用\n", result.PID, result.Name)

Troubleshooting

故障排查

Permission Denied on Some PIDs

部分PID提示权限不足

bash

undefined

bash

undefined

witr needs read access to /proc (Linux) or equivalent

witr需要读取/proc目录（Linux）或对应系统资源的权限

Run with sudo for system-level processes

排查系统级进程时请使用sudo

sudo witr <pid> sudo witr --port 80

undefined

sudo witr <pid> sudo witr --port 80

undefined

Binary Not Found After Install

安装后找不到二进制文件

bash

undefined

bash

undefined

Ensure install location is in PATH

确保安装路径已加入PATH

export PATH="$PATH:/usr/local/bin" # Unix default install

export PATH="$PATH:/usr/local/bin" # Unix默认安装路径

or for Go installs:

或Go源码安装的情况:

export PATH="$PATH:$(go env GOPATH)/bin"

undefined

export PATH="$PATH:$(go env GOPATH)/bin"

undefined

Port Not Found / No Output

端口未找到/无输出

bash

undefined

bash

undefined

Confirm port is actually listening first

先确认端口是否真的在监听

ss -tlnp | grep <port> # Linux netstat -an | grep <port> # macOS/Windows

Then retry

然后重试

witr --port <port>

undefined

witr --port <port>

undefined

TUI Not Rendering Correctly

TUI无法正常渲染

bash

undefined

bash

undefined

Ensure terminal supports 256 colors

确保终端支持256色

export TERM=xterm-256color witr --interactive

If on Windows, use Windows Terminal for best TUI experience

Windows系统请使用Windows Terminal以获得最佳TUI体验

undefined

undefined

Process Exited Before Inspection

进程在检查前已退出

bash

undefined

bash

undefined

witr can only inspect currently running processes

witr仅能检查当前运行中的进程

Use --watch on a long-running process to monitor it

对长期运行的进程使用--watch参数进行监控

witr --watch <pid>

undefined

witr --watch <pid>

undefined

macOS: Requires Elevated Access for Some Processes

macOS: 部分进程需要提升权限

bash

undefined

bash

undefined

System Integrity Protection may restrict some process metadata

系统完整性保护可能会限制部分进程元数据的访问

sudo witr <pid>

---

sudo witr <pid>

---

Quick Reference Card

快速参考卡片

witr <pid>              # Why is PID X running?
witr <name>            # Why is process "nginx" running?
witr -p <port>         # What's on port 8080 and why?
witr -i                # Interactive TUI dashboard
witr -a                # Show all processes + causality
witr --json <pid>      # Machine-readable output
witr -w <pid>          # Watch/follow a process
witr -v <pid>          # Verbose: full env + metadata
witr --user <user>     # Filter by OS user

witr <pid>              # PID X为什么在运行？
witr <name>            # 进程"nginx"为什么在运行？
witr -p <port>         # 端口8080被什么占用及原因？
witr -i                # 启动交互式TUI仪表盘
witr -a                # 显示所有进程及因果链
witr --json <pid>      # 机器可读格式输出
witr -w <pid>          # 跟踪/监控进程
witr -v <pid>          # 详细输出：完整环境变量+元数据
witr --user <user>     # 按系统用户筛选