Metadata-Version: 2.4
Name: psinfo
Version: 1.1.5
Summary: Rich terminal process viewer
License: MIT
Project-URL: Homepage, https://github.com/dblore/psinfo
Project-URL: Repository, https://github.com/dblore/psinfo
Project-URL: Issues, https://github.com/dblore/psinfo/issues
Keywords: process,ps,terminal,cli,rich
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=13.0
Dynamic: license-file

# psinfo

A rich terminal process viewer. Search, filter, and watch running processes with colour-coded output.

psinfo is for when you have a specific question — _"what's on port 8080"_, _"how much memory is Chrome using across all its helpers"_, _"is nginx running and what's it doing"_ — and want a clean answer without launching a full process manager or constructing a `ps aux | grep | awk` pipeline.

---

## Install

```bash
pip install psinfo
```

Or install as an isolated CLI tool with [pipx](https://pypa.github.io/pipx/):

```bash
pipx install psinfo
```

---

## Quick Start

```bash
psinfo nginx               # search by process name
psinfo -u jdoe             # all processes owned by a user
psinfo -p 8080             # process listening on a port
psinfo -P 1234             # single process by PID
psinfo nginx -w            # watch nginx processes
psinfo nginx -w 5 -s mem   # watch nginx, sort by memory, 5s interval
psinfo nginx -t            # group by process tree
```

| Flag                  | Short | Description                                 |
| --------------------- | ----- | ------------------------------------------- |
| `name`                |       | Search by process name or command           |
| `-u, --user USERNAME` | `-u`  | Filter by username                          |
| `-p, --port PORT`     | `-p`  | Find process listening on port              |
| `-P, --pid PID`       | `-P`  | Show process by PID                         |
| `-w, --watch [N]`     | `-w`  | Live refresh every N seconds (default: 2)   |
| `-s, --sort cpu\|mem` | `-s`  | Sort order (default: cpu)                   |
| `-t, --tree`          | `-t`  | Group results by process tree hierarchy     |
| `-T, --top N`         | `-T`  | Show only the top N results                 |
| `-e, --expand`        | `-e`  | Expand command line arguments to full width |

---

## Output

Metrics are colour-coded: green (< 10%), orange (≥ 10%), red (≥ 50%). Tree view groups processes by parent/child with `∑` totals for subtrees.

![Card view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/card-view.svg)

![Tree view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/tree-view.svg)

![User view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/user-view.svg)

![Port view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/port-view.svg)

![PID view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/pid-view.svg)

![Top view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/top-view.svg)

![Expand view](https://raw.githubusercontent.com/dblore/psinfo/main/assets/expand-view.svg)

---

## Requirements

- Python 3.9+

---

## Platform Support

| Platform | Status | Notes                                     |
| -------- | ------ | ----------------------------------------- |
| macOS    | ✓      | `--port` requires `sudo`                  |
| Linux    | ✓      |                                           |
| Windows  | ✓      | Shows handles instead of file descriptors |

---

## License

MIT — see [LICENSE](LICENSE).
