Metadata-Version: 2.4
Name: shervinsights
Version: 0.1.2
Summary: Read-only Mac/Linux triage CLI for debugging interviews and SadServers-style scenarios.
Author: Shervin Ghasemlou
License: MIT
Project-URL: Homepage, https://github.com/shervinghasemlou/shervinsights
Project-URL: Repository, https://github.com/shervinghasemlou/shervinsights
Keywords: linux,bash,debugging,triage,sre,interview,sadservers
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# shervinsights

`shervinsights` is a read-only Mac/Linux system triage CLI.

It provides a compact summary of common machine-level issues and offers follow-up commands for deeper inspection. It is designed to be safe by default: it does not kill processes, delete files, restart services, or modify system state.

## What it checks

- system load
- disk and inode usage
- high CPU and memory processes
- zombie and uninterruptible-sleep processes
- deleted-but-open files
- actively growing log-like files
- listening TCP ports
- Python and model-serving-like processes
- shell script syntax errors
- Linux-specific services, logs, timers, and GPU state when available

## Install

```bash
pip install shervinsights
```

If your Python environment blocks direct installs, use a virtual environment:

```bash
python3 -m venv ~/.venvs/shervinsights
~/.venvs/shervinsights/bin/pip install shervinsights
~/.venvs/shervinsights/bin/shervinsights --hints
```

## Usage

```bash
shervinsights
shervinsights --hints
shervinsights --sample 10 --hints
```

Show more detail for a specific area:

```bash
shervinsights --details disk
shervinsights --details proc
shervinsights --details logs
shervinsights --details ports
shervinsights --details scripts
shervinsights --details ml
shervinsights --details linux
```

## Examples

Compact summary:

```bash
shervinsights --hints
```

Check log growth over a longer window:

```bash
shervinsights --details logs --sample 10 --hints
```

Inspect process pressure:

```bash
shervinsights --details proc --hints
```

Inspect ports:

```bash
shervinsights --details ports --hints
```

## Safety

`shervinsights` is read-only. It prints observations and suggested next commands, but it does not apply fixes automatically.

Typical follow-up commands include:

```bash
ps -p PID -o pid,ppid,user,stat,pcpu,pmem,command
lsof -p PID
lsof FILE
tail -n 100 FILE
curl -v localhost:PORT
bash -n SCRIPT
bash -x SCRIPT
```

## Platform notes

On macOS, `shervinsights` primarily uses:

- `ps`
- `lsof`
- `df`
- `du`
- `find`
- `tail`
- `bash`
- `curl`

On Linux, it also uses available tools such as:

- `systemctl`
- `journalctl`
- `ss`
- `nvidia-smi`
- `/proc`

Output depends on the current user's permissions. Without elevated privileges, some process, file, service, or log details may be hidden by the operating system.

## License

MIT
