{"id":35140295,"url":"https://github.com/pranshuparmar/witr","last_synced_at":"2026-02-21T19:22:45.685Z","repository":{"id":330606981,"uuid":"1120195677","full_name":"pranshuparmar/witr","owner":"pranshuparmar","description":"Why is this running?","archived":false,"fork":false,"pushed_at":"2026-01-13T12:43:41.000Z","size":4356,"stargazers_count":10831,"open_issues_count":13,"forks_count":244,"subscribers_count":22,"default_branch":"main","last_synced_at":"2026-01-13T15:39:49.044Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pranshuparmar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-20T17:26:59.000Z","updated_at":"2026-01-13T14:54:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pranshuparmar/witr","commit_stats":null,"previous_names":["pranshuparmar/witr"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/pranshuparmar/witr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranshuparmar%2Fwitr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranshuparmar%2Fwitr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranshuparmar%2Fwitr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranshuparmar%2Fwitr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pranshuparmar","download_url":"https://codeload.github.com/pranshuparmar/witr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pranshuparmar%2Fwitr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-28T11:00:48.337Z","updated_at":"2026-02-21T19:22:45.674Z","avatar_url":"https://github.com/pranshuparmar.png","language":"Go","funding_links":[],"categories":["Go","Table of Contents","others","Go程序设计","Linux","📈 Operations"],"sub_categories":["Tools","资源传输下载","Terminal utils","☸️ Kubernetes"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# witr\n\n### Why is this running?\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/pranshuparmar/witr?style=flat-square)](https://github.com/pranshuparmar/witr/blob/main/go.mod) [![Go Report Card](https://goreportcard.com/badge/github.com/pranshuparmar/witr?style=flat-square)](https://goreportcard.com/report/github.com/pranshuparmar/witr) [![Release](https://img.shields.io/github/actions/workflow/status/pranshuparmar/witr/release.yml?style=flat-square)](https://github.com/pranshuparmar/witr/actions/workflows/release.yml) [![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows%20%7C%20freebsd-blue?style=flat-square)](https://github.com/pranshuparmar/witr) \u003cbr\u003e\n[![Latest Release](https://img.shields.io/github/v/release/pranshuparmar/witr?label=Latest%20Release\u0026style=flat-square)](https://github.com/pranshuparmar/witr/releases/latest) [![Package Managers](https://img.shields.io/badge/Package%20Managers-brew%20|%20conda%20|%20aur%20|%20winget%20|%20choco%20|%20scoop%20|%20ports%20|%20aosc%20|%20guix%20|%20uniget%20|%20brioche%20|%20aqua%20-blue?style=flat-square)](https://repology.org/project/witr/versions)\n\n✨ *Introducing the new* [**Interactive TUI Mode**](#3-interactive-mode-tui)\n\n\u003cimg width=\"1232\" height=\"693\" alt=\"witr_banner\" src=\"https://github.com/user-attachments/assets/e9c19ef0-1391-4a5f-a015-f4003d3697a9\" /\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n[**Purpose**](#1-purpose) • [**Installation**](#2-installation) • [**TUI**](#3-interactive-mode-tui) \u003csup\u003e✨\u003c/sup\u003e • [**Flags**](#4-flags--options) • [**Examples**](#5-example-outputs) • [**Platforms**](#6-platform-support)\n\u003cbr\u003e\n[**Goals**](#7-goals) • [**Core Concept**](#8-core-concept) • [**Output Behavior**](#9-output-behavior) • [**Success Criteria**](#10-success-criteria)\n\n\u003c/div\u003e\n\n---\n\n## 1. Purpose\n\n**witr** exists to answer a single question:\n\n\u003e **Why is this running?**\n\nWhen 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.\n\nExisting 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.\n\n**witr** makes that causality explicit.\n\nIt 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**.\n\n---\n\n## 2. Installation\n\nwitr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.\n\nwitr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on [Repology](https://repology.org/project/witr/versions). Please note that community packages may lag GitHub releases due to independent review and validation.\n\n\u003e [!TIP]\n\u003e 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.\n\n---\n\n### 2.1 Quick Install\n\n#### Unix (Linux, macOS \u0026 FreeBSD)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eScript Details\u003c/summary\u003e\n\nThe script will:\n- Detect your operating system (`linux`, `darwin` or `freebsd`)\n- Detect your CPU architecture (`amd64` or `arm64`)\n- Download the latest released binary and man page\n- Install it to `/usr/local/bin/witr`\n- Install the man page to `/usr/local/share/man/man1/witr.1`\n- Pass INSTALL_PREFIX to override default install path\n\n\u003c/details\u003e\n\n#### Windows (PowerShell)\n\n```powershell\nirm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eScript Details\u003c/summary\u003e\n\nThe script will:\n- Download the latest release (zip) and verify checksum.\n- Extract `witr.exe` to `%LocalAppData%\\witr\\bin`.\n- Add the bin directory to your User `PATH`.\n\n\u003c/details\u003e\n\n---\n\n### 2.2 Package Managers\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHomebrew (macOS \u0026 Linux)\u003c/strong\u003e \u003ca href=\"https://formulae.brew.sh/formula/witr\"\u003e\u003cimg src=\"https://img.shields.io/homebrew/v/witr?style=flat-square\" alt=\"Homebrew\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** using [Homebrew](https://brew.sh/) on macOS or Linux:\n\n```bash\nbrew install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConda (macOS, Linux \u0026 Windows)\u003c/strong\u003e \u003ca href=\"https://anaconda.org/conda-forge/witr\"\u003e\u003cimg src=\"https://img.shields.io/conda/vn/conda-forge/witr?style=flat-square\" alt=\"Conda\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** using [conda](https://docs.conda.io/en/latest/), [mamba](https://mamba.readthedocs.io/en/latest/), or [pixi](https://pixi.prefix.dev/latest/) on macOS, Linux, and Windows:\n\n```bash\nconda install -c conda-forge witr\n# alternatively using mamba\nmamba install -c conda-forge witr\n# alternatively using pixi\npixi global install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eArch Linux (AUR)\u003c/strong\u003e \u003ca href=\"https://aur.archlinux.org/packages/witr-bin\"\u003e\u003cimg src=\"https://img.shields.io/aur/version/witr-bin?style=flat-square\" alt=\"AUR\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nOn Arch Linux and derivatives, install from the [AUR package](https://aur.archlinux.org/packages/witr-bin):\n\n```bash\nyay -S witr-bin\n# alternatively using paru\nparu -S witr-bin\n# or use your preferred AUR helper\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWinget (Windows)\u003c/strong\u003e \u003ca href=\"https://winstall.app/apps/PranshuParmar.witr\"\u003e\u003cimg src=\"https://img.shields.io/winget/v/PranshuParmar.witr?style=flat-square\" alt=\"Winget\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** via [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):\n\n```powershell\nwinget install -e --id PranshuParmar.witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eChocolatey (Windows)\u003c/strong\u003e \u003ca href=\"https://community.chocolatey.org/packages/witr\"\u003e\u003cimg src=\"https://img.shields.io/chocolatey/v/witr?style=flat-square\" alt=\"Chocolatey\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** using [Chocolatey](https://community.chocolatey.org):\n\n```powershell\nchoco install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eScoop (Windows)\u003c/strong\u003e \u003ca href=\"https://scoop.sh/#/apps?q=witr\"\u003e\u003cimg src=\"https://img.shields.io/scoop/v/witr?bucket=main\u0026style=flat-square\" alt=\"Scoop\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** using [Scoop](https://scoop.sh):\n\n```powershell\nscoop install main/witr\n```\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFreeBSD Ports\u003c/strong\u003e \u003ca href=\"https://www.freshports.org/sysutils/witr/\"\u003e\u003cimg src=\"https://repology.org/badge/version-for-repo/freebsd/witr.svg?style=flat-square\" alt=\"FreeBSD Port\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** on FreeBSD from the [FreshPorts port](https://www.freshports.org/sysutils/witr/):\n\n```bash\npkg install witr\n# or\npkg install sysutils/witr\n```\n\nOr build from Ports:\n\n```bash\ncd /usr/ports/sysutils/witr/\nmake install clean\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAOSC OS\u003c/strong\u003e \u003ca href=\"https://packages.aosc.io/packages/witr\"\u003e\u003cimg src=\"https://repology.org/badge/version-for-repo/aosc/witr.svg?style=flat-square\" alt=\"AOSC OS\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** from the [AOSC OS repository](https://packages.aosc.io/packages/witr):\n\n```bash\noma install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGNU Guix\u003c/strong\u003e \u003ca href=\"https://packages.guix.gnu.org/packages/witr/\"\u003e\u003cimg src=\"https://repology.org/badge/version-for-repo/gnuguix/witr.svg?style=flat-square\" alt=\"GNU Guix\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n\nYou can install **witr** from the [GNU Guix repository](https://packages.guix.gnu.org/packages/witr/):\n\n```bash\nguix install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUniget (Linux)\u003c/strong\u003e \u003ca href=\"https://github.com/uniget-org/tools/tree/main/tools/witr\"\u003e\u003cimg src=\"https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Funiget-org%2Ftools%2Fmain%2Ftools%2Fwitr%2Fmanifest.yaml\u0026query=%24.version\u0026label=uniget\u0026style=flat-square\u0026color=blue\" alt=\"Uniget\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nYou can install **witr** using [uniget](https://uniget.dev/):\n\n```bash\nuniget install witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBrioche (Linux)\u003c/strong\u003e \u003ca href=\"https://github.com/brioche-dev/brioche-packages/tree/main/packages/witr\"\u003e\u003cimg src=\"https://img.shields.io/static/v1?label=brioche\u0026message=v0.2.7\u0026color=blue\u0026style=flat-square\" alt=\"Brioche\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nYou can install **witr** using [brioche](https://brioche.dev/):\n\n```bash\nbrioche install -r witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAqua (macOS, Linux \u0026 Windows)\u003c/strong\u003e \u003ca href=\"https://github.com/aquaproj/aqua-registry/blob/main/pkgs/pranshuparmar/witr\"\u003e\u003cimg src=\"https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Faquaproj%2Faqua-registry%2Fmain%2Fpkgs%2Fpranshuparmar%2Fwitr%2Fpkg.yaml\u0026query=%24.packages%5B0%5D.name\u0026label=aqua\u0026style=flat-square\u0026color=blue\" alt=\"Aqua\"\u003e\u003c/a\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nYou can install **witr** using [aqua](https://aquaproj.github.io/):\n\n```bash\n# Add package\naqua g -i pranshuparmar/witr\n\n# Install package\naqua i pranshuparmar/witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePrebuilt Packages (deb, rpm, apk)\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n**witr** provides native packages for major Linux distributions. You can download the latest `.deb`, `.rpm`, or `.apk` package from the [GitHub releases page](https://github.com/pranshuparmar/witr/releases/latest).\n\n- Generic download command using `curl`:\n  ```bash\n  # Replace \u003cpackage name with the actual package that you need\u003e\n  curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/\u003cpackage-name\u003e\n  ```\n\n- **Debian/Ubuntu (.deb):**\n  ```bash\n  sudo dpkg -i ./witr-*.deb\n  # Or, using apt for dependency resolution:\n  sudo apt install ./witr-*.deb\n  ```\n- **Fedora/RHEL/CentOS (.rpm):**\n  ```bash\n  sudo rpm -i ./witr-*.rpm\n  ```\n- **Alpine Linux (.apk):**\n  ```bash\n  sudo apk add --allow-untrusted ./witr-*.apk\n  ```\n\u003c/details\u003e\n\n---\n\n### 2.3 Source \u0026 Manual Installation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGo (cross-platform)\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nYou can install the latest version directly from source:\n\n```bash\ngo install github.com/pranshuparmar/witr/cmd/witr@latest\n```\n\nThis will place the `witr` binary in your `$GOPATH/bin` or `$HOME/go/bin` directory. Make sure this directory is in your `PATH`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eManual Installation\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIf you prefer manual installation, follow these simple steps for your platform:\n\n**Unix (Linux, macOS, FreeBSD)**\n\n```bash\n# 1. Determine OS and Architecture\nOS=$(uname -s | tr '[:upper:]' '[:lower:]')\nARCH=$(uname -m)\n[ \"$ARCH\" = \"x86_64\" ] \u0026\u0026 ARCH=\"amd64\"\n[ \"$ARCH\" = \"aarch64\" ] \u0026\u0026 ARCH=\"arm64\"\n\n# 2. Download the binary\ncurl -fsSL \"https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}\" -o witr\n\n# 3. Verify checksum (Optional)\ncurl -fsSL \"https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS\" -o SHA256SUMS\ngrep \"witr-${OS}-${ARCH}\" SHA256SUMS | (sha256sum -c - 2\u003e/dev/null || shasum -a 256 -c - 2\u003e/dev/null)\nrm SHA256SUMS\n\n# 4. Rename and install\nchmod +x witr\nsudo mkdir -p /usr/local/bin\nsudo mv witr /usr/local/bin/witr\n\n# 5. Install man page (Optional)\nsudo mkdir -p /usr/local/share/man/man1\nsudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1\n```\n\n**Windows (PowerShell)**\n\n```powershell\n# 1. Determine Architecture\nif ($env:PROCESSOR_ARCHITECTURE -eq \"AMD64\") {\n    $ZipName = \"witr-windows-amd64.zip\"\n} elseif ($env:PROCESSOR_ARCHITECTURE -eq \"ARM64\") {\n    $ZipName = \"witr-windows-arm64.zip\"\n} else {\n    Write-Error \"Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)\"\n    exit 1\n}\n\n# 2. Download the zip\nInvoke-WebRequest -Uri \"https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName\" -OutFile \"witr.zip\"\n# 3. Extract the binary\nExpand-Archive -Path \"witr.zip\" -DestinationPath \".\" -Force\n\n# 4. Verify checksum (Optional)\nInvoke-WebRequest -Uri \"https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS\" -OutFile \"SHA256SUMS\"\n$hash = Get-FileHash -Algorithm SHA256 .\\witr.zip\n$expected = Select-String -Path .\\SHA256SUMS -Pattern $ZipName\nif ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) { Write-Host \"Checksum OK\" } else { Write-Host \"Checksum Mismatch\" }\n\n# 5. Install to local bin directory\n$InstallDir = \"$env:LocalAppData\\witr\\bin\"\nNew-Item -ItemType Directory -Path $InstallDir -Force | Out-Null\nMove-Item .\\witr.exe $InstallDir\\witr.exe -Force\n\n# 6. Add to User Path (Persistent)\n$UserPath = [Environment]::GetEnvironmentVariable(\"Path\", \"User\")\nif ($UserPath -notlike \"*$InstallDir*\") {\n    [Environment]::SetEnvironmentVariable(\"Path\", \"$UserPath;$InstallDir\", \"User\")\n    $env:Path += \";$InstallDir\"\n    Write-Host \"Added to Path. You may need to restart PowerShell.\"\n}\n\n# 7. Cleanup\nRemove-Item witr.zip\nRemove-Item SHA256SUMS\n```\n\u003c/details\u003e\n\n---\n\n### 2.4 Run Without Installation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNix Flake\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIf you use Nix, you can build **witr** from source and run without installation:\n\n```bash\nnix run github:pranshuparmar/witr -- --help\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePixi\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIf you use [pixi](https://pixi.prefix.dev/latest/), you can run without installation on Linux or macOS:\n\n```bash\npixi exec witr --help\n```\n\u003c/details\u003e\n\n---\n\n### 2.5 Other Operations\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVerify Installation\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```bash\nwitr --version\nman witr\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUninstallation\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIf you installed via a package manager (Homebrew, Conda, etc.), please use the respective uninstall command (e.g., `brew uninstall witr`).\n\nTo completely remove script/manual installation of **witr**:\n\n**Unix (Linux, macOS, FreeBSD)**\n\n```bash\nsudo rm -f /usr/local/bin/witr\nsudo rm -f /usr/local/share/man/man1/witr.1\n```\n\n**Windows**\n\n```powershell\nRemove-Item -Recurse -Force \"$env:LocalAppData\\witr\"\n```\n\u003c/details\u003e\n\n---\n \n## 3. Interactive Mode (TUI)\n\nRunning `witr` without any arguments or with the `-i` flag launches the **Interactive Mode (TUI)**. This provides a real-time, terminal-based dashboard for exploring processes and ports.\n\n### Key Features:\n- **Live Process List**: Real-time view of all running processes with sorting and filtering.\n- **Port View**: Explore open ports and immediately see which processes are holding them.\n- **Process Details**: Deep-dive into a specific process to see its full ancestry tree, child processes, environment variables, working directory, and more.\n- **Process Actions**: Send signals (Kill, Terminate, Pause, Resume) or Renice processes directly from the UI.\n- **Mouse Support**: Navigate, sort columns, and click rows using your mouse.\n\n---\n\n## 4. Flags \u0026 Options\n\n```\n      --env           show environment variables for the process\n  -x, --exact         use exact name matching (no substring search)\n  -f, --file string   file path to find process for\n  -h, --help          help for witr\n  -i, --interactive   interactive mode (TUI)\n      --json          show result as JSON\n      --no-color      disable colorized output\n  -p, --pid string    pid to look up\n  -o, --port string   port to look up\n  -s, --short         show only ancestry\n  -t, --tree          show only ancestry as a tree\n      --verbose       show extended process information\n  -v, --version       version for witr\n      --warnings      show only warnings\n```\n\nA single positional argument (without flags) is treated as a process or service name. By default, name matching uses substring matching (fuzzy search). Use `--exact` to match only processes with the exact name.\n\nThe TUI is launched if no arguments or relevant flags (`--pid`, `--port`, `--file`) are provided, or if the `--interactive` flag is explicitly used.\n\n---\n\n## 5. Example Outputs\n\n### 5.1 Name Based Query\n\n```bash\nwitr node\n```\n\n```\nTarget      : node\n\nProcess     : node (pid 14233)\nUser        : pm2\nCommand     : node index.js\nStarted     : 2 days ago (Mon 2025-02-02 11:42:10 +05:30)\nRestarts    : 1\n\nWhy It Exists :\n  systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)\n\nSource      : pm2\n\nWorking Dir : /opt/apps/expense-manager\nGit Repo    : expense-manager (main)\nListening   : 127.0.0.1:5001\n```\n\n---\n\n### 5.2 Short Output\n\n```bash\nwitr --port 5000 --short\n```\n\n```\nsystemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060)\n```\n\n---\n\n### 5.3 Tree Output\n\n```bash\nwitr --pid 143895 --tree\n```\n\n```\nsystemd (pid 1)\n  └─ init-systemd(Ub (pid 2)\n    └─ SessionLeader (pid 143858)\n      └─ Relay(143860) (pid 143859)\n        └─ bash (pid 143860)\n          └─ sh (pid 143886)\n            └─ node (pid 143895)\n              ├─ node (pid 143930)\n              ├─ node (pid 144189)\n              └─ node (pid 144234)\n```\n\nNote: _Tree view includes child processes (up to 10) and highlights the target process._\n\n---\n\n### 5.4 Multiple Matches\n\n```bash\nwitr ng\n```\n\n```\nMultiple matching processes found:\n\n[1] nginx (pid 2311)\n    nginx -g daemon off;\n[2] nginx (pid 24891)\n    nginx -g daemon off;\n[3] ngrok (pid 14233)\n    ngrok http 5000\n\nRe-run with:\n  witr --pid \u003cpid\u003e\n```\n\nTo avoid substring matching and only find processes with an exact name, use the `--exact` flag:\n\n```bash\nwitr nginx -x\n```\n\n---\n\n### 5.5 File Based Query\n\n```bash\nwitr --file /var/lib/dpkg/lock\n```\n\nExplains the process holding a file open.\n\n---\n\n## 6. Platform Support\n\n- **Linux** (x86_64, arm64) - Full feature support (`/proc`).\n- **macOS** (x86_64, arm64) - Uses `ps`, `lsof`, `sysctl`, `pgrep`.\n- **Windows** (x86_64, arm64) - Uses `Get-CimInstance`, `tasklist`, `netstat`.\n- **FreeBSD** (x86_64, arm64) - Uses `procstat`, `ps`, `lsof`.\n\n---\n\n### 5.1 Feature Compatibility Matrix\n\n| Feature | Linux | macOS | Windows | FreeBSD | Notes |\n|---------|:-----:|:-----:|:-------:|:-------:|-------|\n| **Process Selection** |\n| By Name | ✅ | ✅ | ✅ | ✅ | |\n| By PID | ✅ | ✅ | ✅ | ✅ | |\n| By Port | ✅ | ✅ | ✅ | ✅ | |\n| By File | ✅ | ✅ | ❌ | ✅ | |\n| Exact Match | ✅ | ✅ | ✅ | ✅ | |\n| Full command line | ✅ | ✅ | ✅ | ✅ | |\n| Process start time | ✅ | ✅ | ✅ | ✅ | |\n| Working directory | ✅ | ✅ | ✅ | ✅ | |\n| Environment variables | ✅ | ⚠️ | ❌ | ✅ | macOS: Partial support due to SIP restrictions. |\n| **Network** |\n| Listening ports | ✅ | ✅ | ✅ | ✅ | |\n| Bind addresses | ✅ | ✅ | ✅ | ✅ | |\n| Port → PID resolution | ✅ | ✅ | ✅ | ✅ | |\n| **Service Detection** |\n| Service Manager | ✅ | ✅ | ✅ | ✅ | Linux: systemd, macOS: launchd, Windows: Services, FreeBSD: rc.d |\n| Service Description | ✅ | ✅ | ✅ | ✅ | Linux: `Description`, macOS: `Comment`, Windows: `Display Name`, FreeBSD: `rc` header |\n| Configuration Source | ✅ | ✅ | ✅ | ✅ | Linux: Unit File, macOS: Plist, Windows: Registry Key, FreeBSD: Rc Script |\n| Supervisor | ✅ | ✅ | ✅ | ✅ | |\n| Containers | ✅ | ✅ | ✅ | ✅ | Docker (plus Compose mappings), Podman, K8s (Kubepods), Containerd. Colima on macOS/Linux. Jails on FreeBSD. |\n| **Health \u0026 Diagnostics** |\n| CPU usage detection | ✅ | ✅ | ✅ | ✅ | |\n| Memory usage detection | ✅ | ✅ | ✅ | ✅ | |\n| Health status detection | ✅ | ✅ | ✅ | ✅ | |\n| Open Files / Handles | ✅ | ✅ | ⚠️ | ✅ | Windows: count only. |\n| Deleted binary detection | ✅ | ✅ | ✅ | ✅ | Warns if executable is missing. |\n| **Context** |\n| Git repo/branch detection | ✅ | ✅ | ✅ | ✅ | |\n| **Interactive Mode (TUI)** |\n| Process Dashboard | ✅ | ✅ | ✅ | ✅ | |\n| Port Dashboard | ✅ | ✅ | ✅ | ✅ | |\n| Process Details | ✅ | ✅ | ✅ | ✅ | |\n| Process Actions | ✅ | ✅ | ❌ | ✅ | |\n\n**Legend:** ✅ Full support | ⚠️ Partial/limited support | ❌ Not available\n\n---\n\n### 5.2 Permissions Note\n\n#### Linux/FreeBSD\n\nwitr inspects system directories which may require elevated permissions.\n\nIf you are not seeing the expected information, try running witr with sudo:\n\n```bash\nsudo witr [your arguments]\n```\n\n#### macOS\n\nOn macOS, witr uses `ps`, `lsof`, and `launchctl` to gather process information. Some operations may require elevated permissions:\n\n```bash\nsudo witr [your arguments]\n```\n\nNote: Due to macOS System Integrity Protection (SIP), some system process details may not be accessible even with sudo.\n\n#### Windows\n\nOn Windows, witr uses `Get-CimInstance`, `tasklist`, and `netstat`. To see details for processes owned by other users or system services, you must run the terminal as **Administrator**.\n\n```powershell\n# Run in Administrator PowerShell\n.\\witr.exe [your arguments]\n```\n\n---\n\n## 7. Goals\n\n### Primary goals\n\n- Explain **why a process exists**, not just that it exists\n- Reduce time‑to‑understanding during debugging and outages\n- Work with zero configuration\n- Be safe, read‑only, and non‑destructive\n- Prefer clarity over completeness\n\n### Non‑goals\n\n- Not a monitoring tool\n- Not a performance profiler\n- Not a replacement for systemd/docker tooling\n- Not a remediation or auto‑fix tool\n\n---\n\n## 8. Core Concept\n\nwitr treats **everything as a process question**.\n\nPorts, services, containers, and commands all eventually map to **PIDs**. Once a PID is identified, witr builds a causal chain explaining _why that PID exists_.\n\nAt its core, witr answers:\n\n1. What is running?\n2. How did it start?\n3. What is keeping it running?\n4. What context does it belong to?\n\n---\n\n## 9. Output Behavior\n\n### 9.1 Output Principles\n\n- Single screen by default (best effort)\n- Deterministic ordering\n- Narrative-style explanation\n- Best-effort detection with explicit uncertainty\n\n---\n\n### 9.2 Standard Output Sections\n\n#### Target\n\nWhat the user asked about.\n\n#### Process\n\nExecutable, PID, user, command, start time and restart count.\n\n#### Why It Exists\n\nA causal ancestry chain showing how the process came to exist.\nThis is the core value of witr.\n\n#### Source\n\nThe primary system responsible for starting or supervising the process (best effort).\n\nExamples:\n\n- systemd unit (Linux)\n- launchd service (macOS)\n- docker container\n- pm2\n- cron\n- interactive shell\n\nOnly **one primary source** is selected.\n\n#### Context (best effort)\n\n- Working directory\n- Git repository name and branch\n- Container name / image (docker, podman, kubernetes, colima, containerd)\n- Public vs private bind\n\n#### Warnings\n\nNon‑blocking observations such as:\n\n- Process is running as root\n- Process is listening on a public interface (0.0.0.0 / ::)\n- Restarted multiple times (warning only if above threshold)\n- Process is using high memory (\u003e1GB RSS)\n- Process has been running for over 90 days\n\n---\n\n## 10. Success Criteria\n\nwitr is successful if:\n\n- A user can answer \"why is this running?\" within seconds\n- It reduces reliance on multiple tools\n- Output is understandable under stress\n- Users trust it during incidents\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpranshuparmar%2Fwitr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpranshuparmar%2Fwitr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpranshuparmar%2Fwitr/lists"}