Metadata-Version: 2.4
Name: psinfo
Version: 0.1.0
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 -e .
# or, to install as an isolated CLI tool:
pipx install .
```

`pipx` is recommended for CLI tools — it installs into an isolated environment and puts `psinfo` on your PATH. Install it with `brew install pipx` or `pip install pipx`.

## Usage

```
psinfo <name>            search by process name or command
psinfo -u <username>     all processes owned by a user
psinfo -p <port>         process listening on a port
psinfo -P <pid>          single process by PID
```

### Flags

| Flag | Short | Description |
|---|---|---|
| `--watch [N]` | `-w` | Live refresh every N seconds (default: 2) |
| `--sort cpu\|mem` | `-s` | Sort order (default: cpu) |
| `--tree` | `-t` | Group results by process tree hierarchy |

Flags compose freely:

```bash
psinfo nginx -w
psinfo python -w 5 -s mem
psinfo slack -t -w
```

## Output

### Card view (default)

Each matching process is shown as a panel. The highest-CPU process gets a green border. Metrics are colour-coded: green (< 10%), orange (≥ 10%), red (≥ 50%).

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

### Tree view (`-t`)

Results are grouped by parent/child relationships. Parent nodes show their own CPU plus a `∑` total across the whole subtree.

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

## Requirements

- Python 3.9+
- psutil >= 5.9
- rich >= 13.0

## Platform support

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

## License

MIT — see [LICENSE](LICENSE).
