yazeed/proc
Semantic CLI tool for process management. Target by port, PID, name or path.
Image
Developer tools
1
4.1K
yazeed/proc repository overview
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 for ./script.py # what's running this file?
proc by node --in . --min-cpu 5 # node in cwd using >5% CPU
proc kill :3000,:8080,node # kill mixed targets at once
proc info :3000,1234 # info for port + PID
Why proc?
| Task | proc | Without proc |
|---|---|---|
| What's on port 3000? | proc on :3000 | lsof -i :3000 -P -n |
| Kill it | proc kill :3000 | lsof -i :3000 -t | xargs kill -9 |
| Free port 3000 | proc free :3000 | lsof -i :3000 -t | xargs kill && sleep 1 && lsof -i :3000 |
| Why is port busy? | proc why :3000 | lsof -i :3000 + ps -o ppid= chain |
| Pause a process | proc freeze node | kill -STOP $(pgrep node) |
| Find orphans | proc orphans --in . | No standard tool |
| Wait for process | proc wait node | while ps aux | grep node | grep -v grep; do sleep 5; done |
| Ports used by node | proc on node | lsof -i -P -n | grep node |
| Node processes in cwd | proc by node --in . | ps aux | grep node + manual check |
| Kill mixed targets | proc kill :3000,:8080,node | Three separate commands |
| Watch in real-time | proc watch node | watch -n2 'ps aux | grep node' |
| What runs this file? | proc for ./app.js | lsof ./app.js or fuser ./app.js |
One syntax. One tool. Full comparison →
Install
| Platform | Command |
|---|---|
| macOS | brew install yazeed/proc/proc |
| Windows | scoop bucket add proc https://github.com/yazeed/scoop-bucket-proc && scoop install proc |
| Rust | cargo install proc-cli |
| npm/bun | npm install -g proc-cli |
| Nix | nix profile install github:yazeed/proc |
| Docker | docker run --rm -it --pid=host yazeed/proc |
| Shell | curl -fsSL https://raw.githubusercontent.com/yazeed/proc/main/install.sh | bash |
More options
| Platform | Method | Command |
|---|---|---|
| macOS/Linux | cargo-binstall | cargo binstall proc-cli |
| Arch Linux | AUR | yay -S proc (pending) |
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
Quick Start
What's using port 3000?
proc on :3000
Kill it:
proc kill :3000
What's running this script?
proc for ./script.py
Find all node processes in current directory using >5% CPU:
proc by node --in . --min-cpu 5
Kill multiple targets at once:
proc kill :3000,:8080,node
Watch processes in real-time:
proc watch node --in .
Target Syntax
All commands accept the same target syntax:
| Target | Example | Description |
|---|---|---|
| Port | :3000 | Process listening on port 3000 |
| PID | 1234 | Process with ID 1234 |
| Name | node | All processes named "node" |
| Multi | :3000,:8080,node | Comma-separated targets |
Commands
Discovery
| Command | Alias | Description |
|---|---|---|
on <target> | : | Bidirectional port/process lookup |
for <file> | f | Find processes by file path |
by <name> | b | Filter processes by name |
in <path> | Filter processes by working directory | |
list | l, ps | List all processes |
info <target> | i | Detailed process information |
ports | p | List all listening ports |
tree | t | Process hierarchy |
watch | w, top | Real-time process monitoring |
why <target> | Trace process ancestry (why is this port busy?) | |
orphans | o | Find orphaned processes |
stuck | x | Find hung processes |
Lifecycle
| Command | Alias | Description |
|---|---|---|
kill <target> | k | Force kill (SIGKILL) |
stop <target> | s | Graceful stop (SIGTERM, --signal for custom) |
freeze <target> | Pause process (SIGSTOP) | |
thaw <target> | Resume frozen process (SIGCONT) | |
free <:port> | Kill process and verify port freed | |
wait <target> | Block until process(es) exit | |
unstick | u | Recover stuck processes |
Filters
Filters can be combined with discovery and lifecycle commands:
| Filter | Description |
|---|---|
--in <path> | Filter by working directory |
--by <name> | Filter by process name |
--path <path> | Filter by executable path (list) |
--min-cpu <n> | Processes using >n% CPU |
--min-mem <n> | Processes using >n MB memory |
--min-uptime <s> | Processes running longer than s seconds |
--parent <pid> | Children of a specific parent PID |
--status <s> | Filter by status: running, sleeping, stopped, zombie |
--exposed | Only network-exposed ports (ports) |
--local | Only localhost ports (ports) |
--range <s-e> | Filter ports by range (e.g., 3000-9000) |
--sort/-s <key> | Sort by: cpu, mem, pid, name |
--limit/-n <n> | Limit number of results |
--ancestors/-a | Show ancestry path to root (tree) |
--depth/-d <n> | Maximum tree depth (default: 10) |
--compact/-C | Show PIDs only in compact view (tree) |
--timeout/-t <s> | Seconds before considered stuck (default: 300) |
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 termination if recovery fails (unstick) |
--graceful | -g | Send SIGTERM instead of SIGKILL (kill) |
--signal | -S | Custom signal: HUP, INT, USR1, etc. (stop) |
--kill | -k | Kill found processes (stuck, orphans) |
--wait | Max seconds to wait for port to free (free) | |
--interval | -n | Poll/refresh interval in seconds (wait, watch) |
--timeout | -t | Max seconds to wait before giving up (wait, stop) |
--quiet | -q | Suppress periodic status messages (wait) |
Examples
# What's on port 3000?
proc on :3000
# What ports is node using?
proc on node
# What's running this file?
proc for ./script.py
# What has this file open?
proc for /var/log/app.log
# Node processes in current directory
proc by node --in .
# Processes using >10% CPU
proc list --min-cpu 10
# Kill everything on ports 3000 and 8080
proc kill :3000,:8080
# Kill only node processes in current directory
proc kill node --in . --dry-run
# Process tree filtered by CPU usage
proc tree --min-cpu 5
# Watch all processes sorted by CPU (alias: proc top)
proc watch
# Watch node processes with 1s refresh
proc watch node -n 1
# Watch process on port 3000
proc watch :3000
# Watch processes in cwd sorted by memory
proc watch --in . --sort mem
# Freeze/thaw (pause and resume)
proc freeze node # Pause all node processes
proc thaw node # Resume them
# Free a port (kill + verify available)
proc free :3000 # Kill and confirm port 3000 is free
proc free :3000,:8080 --yes # Free multiple ports
# Why is port 3000 busy?
proc why :3000 # Show ancestry chain with port context
# Find orphaned processes
proc orphans # List orphans
proc orphans --in . --kill # Kill orphans in current directory
# Wait for processes to exit
proc wait node # Block until all node processes exit
proc wait :3000 --timeout 60 # Wait up to 60s for port process to exit
proc wait node -n 10 -q # Check every 10s, quiet mode
# Send custom signal
proc stop nginx --signal HUP # Reload config (SIGHUP)
# Find and recover stuck processes
proc stuck
proc unstick --force
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 | ✅ |
Shell Completions
Generate completions for your shell:
# Bash
proc completions bash > /etc/bash_completion.d/proc
# Zsh
proc completions zsh > ~/.zsh/completions/_proc
# Fish
proc completions fish > ~/.config/fish/completions/proc.fish
Man Page
Generate and install the man page:
proc manpage | sudo tee /usr/local/share/man/man1/proc.1 > /dev/null
Building from Source
git clone https://github.com/yazeed/proc
cd proc
cargo build --release
The binary will be at target/release/proc.
Contributing
See CONTRIBUTING.md.
License
MIT
Tag summary
Content type
Image
Digest
sha256:eaba61210…
Size
31.3 MB
Last updated
5 months ago
docker pull yazeed/proc