proc

proc is a command-line tool for developers who are tired of arcane incantations for simple process tasks.

Why proc?

Every developer knows this pain:

# What's on port 3000?
lsof -i :3000 | grep LISTEN | awk '{print $2}'

# Kill it
lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Find all node processes
ps aux | grep node | grep -v grep

With proc:

proc on :3000      # What's on port 3000?
proc kill :3000    # Kill it
proc ps node       # List node processes

Commands that mean what they say.

Install

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

Or via package managers:

brew install yazeed/proc/proc   # Homebrew
cargo install proc-cli          # Cargo

# macOS (Apple Silicon)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-aarch64 -o proc
chmod +x proc && sudo mv proc /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-darwin-x86_64 -o proc
chmod +x proc && sudo mv proc /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-x86_64 -o proc
chmod +x proc && sudo mv proc /usr/local/bin/

# Linux (ARM64)
curl -fsSL https://github.com/yazeed/proc/releases/latest/download/proc-linux-aarch64 -o proc
chmod +x proc && sudo mv proc /usr/local/bin/

Commands

All commands accept targets: :port, PID, or name.

Discovery

proc on :3000          # What's using port 3000?
proc on 1234           # What ports is PID 1234 using?
proc on node           # What ports are node processes using?
proc ports             # List all listening ports
proc ps                # List all processes
proc ps node           # Filter by name
proc ps --in .        # Processes in current directory
proc ps --min-cpu 10   # Processes using >10% CPU
proc info :3000        # Info for process on port 3000
proc info 1234         # Info for PID 1234
proc tree              # Full process hierarchy
proc tree :3000        # Tree for process on port 3000
proc tree --min-cpu 5  # Tree filtered by CPU usage
proc stuck             # Find processes that appear hung

Lifecycle

proc kill :3000        # Kill process on port 3000
proc kill node         # Kill all node processes (SIGKILL)
proc stop :3000        # Stop gracefully (SIGTERM, then SIGKILL)
proc stop node         # Stop all node processes gracefully
proc unstick           # Attempt to recover stuck processes
proc unstick --force   # Terminate if recovery fails

Command Reference

Common Options

Filter Options

Available on ps and tree:

Examples

Port lookup

$ 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 on 12345
✓ node (PID 12345) is listening on:
  → :3000 (TCP on 0.0.0.0)
  → :3001 (TCP on 127.0.0.1)

Process discovery

$ proc ps --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

Lifecycle management

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

$ proc unstick
! Found 1 stuck process:
  → node [PID 12345] - 98.2% CPU, running for 2h 15m
Unstick 1 process? [y/N]: y
  → node [PID 12345]... recovered
✓ 1 process recovered

Scripting with JSON

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

Platform Support

Building from Source

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

Roadmap

See ROADMAP.md for planned features.

Contributing

Contributions welcome. See CONTRIBUTING.md.

License

MIT - see LICENSE.

proc: Process management for humans.