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 on :3000,:8080,node        # multi-target: ports + name
proc by node --in . --min-cpu 5 # node in cwd using >5% CPU
proc kill :3000,:8080,node -y   # kill mixed targets at once
proc info :3000,1234            # info for port + PID

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`

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

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 -y

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
`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

Lifecycle

Command	Alias	Description
`kill <target>`	`k`	Force kill (SIGKILL)
`stop <target>`	`s`	Graceful stop (SIGTERM)
`stuck`	`x`	Find hung processes
`unstick`	`u`	Recover stuck processes

Filters

Filters can be combined with discovery commands:

Filter	Description
`--in <path>`	Filter by working directory
`--by <name>`	Filter by process name
`--path <path>`	Filter by executable path
`--min-cpu <n>`	Processes using >n% CPU
`--min-mem <n>`	Processes using >n MB memory
`--status <s>`	Filter by status: running, sleeping, stopped, zombie

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

Examples

# What's on port 3000?
proc on :3000

# What ports is node using?
proc on node

# 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 -y

# Process tree filtered by CPU usage
proc tree --min-cpu 5

# 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	✅

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

proc-cli 1.3.3