proc

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

proc on :3000                   # what's on port 3000?
proc for ./server               # what's running this program?
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?

One syntax. One tool. Full comparison →

Install

Manual download:

# macOS (Apple Silicon)
curl -fsSL https://github.com/yazeed/proc-cli/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-cli/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-cli/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-cli/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-cli/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

Agent Skill

Teach your coding agent (Claude Code, Codex, Cursor, Gemini CLI and others) to use proc with structured JSON output:

npx skills add yazeed/proc-cli

In Claude Code you can also install it as a plugin:

/plugin marketplace add yazeed/proc-cli
/plugin install proc-cli@proc-cli

The skill lives in skills/proc-cli/ and follows the Agent Skills standard. What it teaches, how to update it, and prompts to try →

Quick Start

What's using port 3000?

proc on :3000

Kill it:

proc kill :3000

What's running this program?

proc for ./server

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:

Give several targets as separate arguments, and mix the three kinds freely: proc kill 1234 :3000 node. A process named twice is handled once, except by the read-only on and why, which answer each target under its own header. Comma-separated targets (:3000,:8080,node) still work but are deprecated, and will be removed in a future major release: a command that gets one prints a note: on stderr with the separate-argument form (human output only; --json is unchanged).

A name matches the whole process name, ignoring case, the way killall and pkill read it. proc kill node stops the processes named node and leaves Claude Helper alone, and --by follows the same rule. The file name of the executable and of the first argument count as names too, so a long name that Linux cuts to 15 characters still matches, and on Windows a trailing .exe is optional. Add --cmd to match any part of the name or the full command line instead, like pkill -f: proc kill serve --cmd. A path is not a name: proc kill ./server finds nothing, so use --cmd, or proc for <file> for an executable. proc doesn't expand wildcards; an unquoted node* is expanded by your shell into file names; use --cmd for partial matches.

--in takes the next word as its directory unless that word starts with -, so put it after the targets (proc kill 1234 5678 --in .) or write --in=DIR.

Commands

Discovery

Lifecycle

Filters

Filters can be combined with discovery and lifecycle commands:

Options

Scripting

With --json, every command prints one JSON document with action (the command name) and success. proc watch --json streams one per refresh. Errors, including invalid flags, are JSON too: {"action", "success": false, "error", "exit_code"}. Exit 4 means nothing was done, and its error adds "reason": "invalid_input" (a wrong flag, value or argument), "needs_confirmation" or "not_supported" (this OS cannot do it). A command that changes processes run with --json but without --yes exits 4 and adds "needs_confirmation": true and "processes" (the ones it would have changed), so a script can show them before running it again with --yes. Every command that takes targets also has a "not_found" array in its JSON (the targets that matched nothing, empty when all were found), and it appears in that exit 4 output too.

"success": false always comes with a non-zero exit code. Full schemas: skills/proc-cli/reference.md.

Examples

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

# What ports is node using?
proc on node

# What's running this program?
proc for ./server

# 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 worker --signal INT  # Ask with SIGINT instead of SIGTERM (force-killed after --timeout)

# Find and recover stuck processes
proc stuck
proc unstick --force

Platform Support

The Linux binaries are statically linked (musl) and need no particular glibc version, so they also run on Alpine and on older releases such as Debian 10, Ubuntu 20.04 and Amazon Linux 2.

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-cli
cd proc-cli
cargo build --release

The binary will be at target/release/proc.

Contributing

See CONTRIBUTING.md.

License

MIT