nettop 0.1.1

# nettop

> **CLI network usage monitor by application — like NetLimiter, but for your terminal.**

```
 ┌─ nettop ─────────────────────────────────────────────────────────────────────────┐
 │ ▲ 2.3 MB/s  ▼ 18.7 MB/s  │  procs: 12  │  sort: TOTAL/s  │  mode: RATE           │
 └──────────────────────────────────────────────────────────────────────────────────┘
 ┌── processes ─────────────────────────────────────────────────────────────────────┐
 │ PID     PROCESS              EXE PATH              ▲ SENT/s  ▼ RECV/s  TOTAL/s   │
 │▶ 3821   firefox              /usr/lib/firefox/f…   142 KiB   8.1 MiB   8.2 MiB   │
 │  1204   spotify              /opt/spotify/spotif…   88 KiB   4.3 MiB   4.4 MiB   │
 │  9012   curl                 /usr/bin/curl          12 KiB   1.1 MiB   1.1 MiB   │
 │  512    systemd-resolved     /usr/lib/systemd/s…    3 KiB    44 KiB    47 KiB    │
 └──────────────────────────────────────────────────────────────────────────────────┘
 │ [q] Quit  [r] Reset  [s] Sort  [p] Pause  [f] Filter  [Tab] Rate/Cum  [↑↓] Scroll│
```

## Features

- **Per-process network I/O** — sent/recv rates and cumulative totals
- **Live TUI** — auto-refreshing table powered by [ratatui](https://github.com/ratatui-org/ratatui)
- **Color-coded rates** — green → yellow → red based on throughput
- **Sort** by any column (rate, total, name, PID) — cycle with `s`
- **Filter** by process name — press `f`, type, press Enter
- **Toggle** between rate view (bytes/sec) and cumulative totals — press `Tab`
- **Pause / resume** — press `p`
- **JSON output** — `--json` flag for scripting / pipelines
- **Single static binary** — no runtime, no dependencies
- Cross-platform: **Linux** (reads `/proc/<pid>/net/dev`), **macOS**, **Windows**

## Install

### From source

```bash
git clone https://github.com/cumulus13/nettop
cd nettop
cargo build --release
sudo cp target/release/nettop /usr/local/bin/
```

### cargo install (once published)

```bash
cargo install nettop
```

## Usage

```
nettop [OPTIONS]

Options:
  -i, --interval <MS>      Refresh interval in milliseconds [default: 1000]
  -n, --top <N>            Show only top N processes (0 = all) [default: 0]
  -s, --sort <COLUMN>      Sort column [default: total-rate]
                           Values: pid | name | sent | recv | total-rate | sent-total | recv-total
  -f, --filter <NAME>      Filter by process name (case-insensitive substring)
      --json               Output one snapshot as JSON and exit
      --no-color           Disable colors
      --cumulative         Start in cumulative mode
      --count <COUNT>      Exit after N refreshes (0 = run forever) [default: 0]
  -h, --help               Print help
  -V, --version            Print version
```

### Examples

```bash
# Default: live TUI, 1s refresh
nettop

# Top 10 processes, 500ms refresh
nettop -n 10 -i 500

# Watch only browser traffic
nettop -f firefox

# JSON snapshot for scripting
nettop --json | jq '.[] | select(.recv_rate > 1000000)'

# Pipe to file every 5 seconds, 12 times (1 minute log)
nettop --json --count 12 --interval 5000 > net_log.json
```

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` / `Ctrl+C` | Quit |
| `p` | Pause / resume |
| `r` | Reset cumulative counters |
| `s` | Cycle sort column |
| `f` | Open filter input |
| `Tab` | Toggle rate ↔ cumulative view |
| `↑` / `k` | Scroll up |
| `↓` / `j` | Scroll down |

## How it works

On **Linux**, nettop reads `/proc/<pid>/net/dev` for each process to get true per-process
network byte counters at the kernel level — no BPF required, no root required for most
processes. It calculates per-second rates by diffing successive snapshots.

On **macOS** and **Windows**, it falls back to sysinfo's disk I/O counters as a proxy for
process activity (full cross-platform net-per-process support is on the roadmap via libproc
and iphlpapi respectively).

## Platform support

| Platform | Net I/O source | Root required |
|----------|---------------|---------------|
| Linux    | `/proc/<pid>/net/dev` | No (own processes only) |
| macOS    | `sysinfo` disk proxy | No |
| Windows  | `sysinfo` disk proxy | No |

## License

MIT © [Hadi Cahyadi](mailto:cumulus13@gmail.com)

## 👤 Author
        
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
    

[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)

[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
 
[Support me on Patreon](https://www.patreon.com/cumulus13)