proc

Semantic CLI tool for process management. Target by port, process id (PID), name or path.

proc on :3000       # what's on port 3000?
proc kill :3000     # kill it
proc list node      # list node processes
proc stop node      # stop them gracefully

Install

Package Managers

Platform	Method	Command
macOS	Homebrew	brew install yazeed/proc/proc
macOS/Linux	cargo	cargo install proc-cli
macOS/Linux	cargo-binstall	cargo binstall proc-cli
Windows	Scoop	scoop install proc ¹
Arch Linux	AUR	yay -S proc ²
NixOS	Nix Flakes	nix profile install github:yazeed/proc
Any	npm	npm install -g proc-cli ³
Any	Docker	docker run --rm -it --pid=host yazeed/proc

_{¹ Requires bucket: scoop bucket add yazeed https://github.com/yazeed/scoop-bucket
² Package pending AUR submission
³ Package pending npm publish}

Shell Script

curl -fsSL https://raw.githubusercontent.com/yazeed/proc/main/install.sh | bash

Manual download

# macOS (Apple Silicon)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-aarch64.tar.gz | tar xz
sudo mv proc-darwin-aarch64 /usr/local/bin/proc

# macOS (Intel)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-x86_64.tar.gz | tar xz
sudo mv proc-darwin-x86_64 /usr/local/bin/proc

# Linux (x86_64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-x86_64.tar.gz | tar xz
sudo mv proc-linux-x86_64 /usr/local/bin/proc

# Linux (ARM64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-aarch64.tar.gz | tar xz
sudo mv proc-linux-aarch64 /usr/local/bin/proc

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/yazeed/proc/releases/latest/download/proc-windows-x86_64.exe.zip -OutFile proc.zip
Expand-Archive proc.zip -DestinationPath .
Move-Item proc-windows-x86_64.exe C:\Windows\System32\proc.exe

Usage

Targets

Every command accepts the same target syntax:

Target	Example	Meaning
:port	:3000	Process using port 3000
PID	12345	Process with ID 12345
name	node	All processes named "node"

Discovery

proc on :3000          # what's using port 3000?
proc on 12345          # what ports is PID 12345 using?
proc on node           # what ports are node processes using?

proc ports             # all listening ports
proc list              # all processes
proc list node         # filter by name
proc list --in .       # processes started in current directory
proc list --path /usr  # processes from /usr/*
proc list --min-cpu 10 # processes using >10% CPU

proc info :3000        # detailed info for process on port 3000
proc tree              # process hierarchy
proc tree --min-cpu 5  # tree filtered by CPU

proc stuck             # find hung processes

Lifecycle

proc kill :3000        # SIGKILL process on port 3000
proc kill node         # SIGKILL all node processes
proc stop :3000        # SIGTERM, then SIGKILL after timeout
proc stop node         # graceful stop for all node processes

proc unstick           # attempt to recover stuck processes
proc unstick --force   # terminate if recovery fails

Reference

Commands

Command	Alias	Description
on	:	Bidirectional port/process lookup
ports	p	List listening ports
list	l, ps	List processes
info	i	Detailed process info
tree	t	Process hierarchy
kill	k	Force kill (SIGKILL)
stop	s	Graceful stop (SIGTERM)
stuck	x	Find hung processes
unstick	u	Recover stuck processes

Options

Option	Short	Description
--json	-j	JSON output
--verbose	-v	Show paths, cwd, full commands
--yes	-y	Skip confirmation
--dry-run		Preview without executing
--force	-f	Force action

Filters

Option	list	tree	Description
--in <path>	✓		Filter by working directory
--path <path>	✓		Filter by executable path
--min-cpu <n>	✓	✓	Processes using >n% CPU
--min-mem <n>	✓	✓	Processes using >n MB memory
--status <s>	✓	✓	running, sleeping, stopped, zombie

Examples

$ proc on :3000
✓ Port 3000 is used by:
  Process: node (PID 12345)
  Path: /usr/local/bin/node
  Listening: TCP on 0.0.0.0
  Resources: 2.3% CPU, 156.4 MB
  Uptime: 2h 34m

$ proc list --in /my/project
✓ Found 3 processes

PID      NAME        CPU%   MEM (MB)   STATUS
──────────────────────────────────────────────
12345    node        2.3    156.4      Running
12346    npm         0.1    45.2       Sleeping

$ proc tree --min-cpu 5
✓ 2 processes matching filters:
├── ● node [12345] 12.3% 256.4MB
└── ● python [12400] 8.1% 128.2MB

$ proc kill :3000
Kill node [PID 12345]? [y/N]: y
✓ Killed 1 process

$ proc list node --json | jq '.processes[].pid'
12345
12346

Platform Support

Platform	Architecture	Status
macOS	Apple Silicon (ARM64)	✅
macOS	Intel (x86_64)	✅
Linux	x86_64	✅
Linux	ARM64	✅
Windows	x86_64	✅
Docker	linux/amd64, linux/arm64	✅

Building

git clone https://github.com/yazeed/proc
cd proc
cargo build --release
./target/release/proc --help

Contributing

See CONTRIBUTING.md.

License

MIT