process-tree

# process-tree

CLI tool for visualizing the system process hierarchy with resource usage.

## Quick Start

```bash
# Full process tree
ptree

# Find what is running on port 3000
ptree --port 3000

# Find all node processes
ptree --name node

# Detailed info for a process
ptree info 8421

# Watch mode (refreshes every 2 seconds)
ptree watch
```

## Tree View

```bash
ptree                    # full process tree
ptree --root 8421        # subtree from specific PID
ptree --compact          # collapse identical-name siblings
ptree --sort cpu         # sort by CPU usage
ptree --sort mem         # sort by memory usage
```

## Filter

```bash
ptree --name node        # processes named "node"
ptree --port 3000        # process on port 3000
ptree --user deploy      # processes owned by user
ptree --min-cpu 5        # processes using more than 5% CPU
ptree --min-mem 200      # processes using more than 200MB
```

## Find (flat table)

```bash
ptree find node          # all matching processes in table
ptree find --port 5432   # find by port
ptree find --user www    # find by user
```

## Process Info

```bash
ptree info 8421          # all details including subtree aggregates
```

## Kill

```bash
ptree kill 8421              # send SIGTERM (with confirmation)
ptree kill 8421 --yes        # skip confirmation
ptree kill 8421 --signal SIGKILL   # force kill
ptree kill 8421 --subtree    # kill process and all children
```

## Watch Mode

```bash
ptree watch                  # refresh every 2 seconds
ptree watch --interval 5     # refresh every 5 seconds
ptree watch --name node      # filter in real time
```

Press `q` or `Ctrl-C` to exit watch mode.

## CLI Reference

| Command/Flag | Description |
|---|---|
| (default) | Show full process tree |
| `find <name>` | Flat table of matching processes |
| `info <pid>` | Detailed info for one process |
| `kill <pid>` | Send SIGTERM to process |
| `watch` | Continuously refresh tree |
| `--name <text>` | Filter by process name |
| `--port <N>` | Filter by listening port |
| `--user <name>` | Filter by user |
| `--root <pid>` | Show subtree from PID |
| `--min-cpu <N>` | Minimum CPU % threshold |
| `--min-mem <N>` | Minimum memory MB threshold |
| `--sort cpu\|mem` | Sort children by resource |
| `--compact` | Collapse same-name siblings |
| `--interval <N>` | Watch refresh interval (seconds) |
| `--subtree` | Apply kill to whole subtree |
| `--signal <name>` | Signal to send (SIGTERM or SIGKILL) |
| `--yes` | Skip confirmation prompts |
| `--no-color` | Disable ANSI color |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PTREE_NO_COLOR` | `0` | Disable ANSI color (1 to disable) |
| `PTREE_INTERVAL` | `2` | Watch mode refresh interval (seconds) |
| `PTREE_DEBUG` | `0` | Enable debug logging (1 to enable) |

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | No processes matched |
| 2 | Permission denied |
| 3 | Runtime error |

## Platform Support

Supported: macOS, Linux. Not supported: Windows (exits with clear error message).