Language / Idioma: English | Español

psc — Process Search & Control

A terminal tool to search, view, and kill processes quickly, with the same syntax on Linux and Windows. No external dependencies — native OS tools only.

Commands

Command	Description
psc	Show the colorful info banner
psc -a, psc --all	List all processes
psc -n <name>	Search by name (substring or regex)
psc -pid <pid>	Search by PID
psc -p <port>	Search by port
psc -ip <ip>	Search by IP address
psc -n X -p Y	Combined filters (AND)
psc -k <spec>	Kill by index: N, 1,3,5, 1-4, or all
psc -k <spec> -f	Kill without confirmation
psc -k <spec> -s <sig>	Custom signal (Linux: SIGINT/15; Windows: graceful vs force mapping)
psc -i	Interactive TUI (arrows, K/Delete to kill, q to quit)
psc -w [N], psc --watch [N]	Live refresh every N seconds (default 2)
psc -t, psc --tree	Process tree (PID/PPID hierarchy)
psc --info <n>	Deep details for result #n
psc --json / psc --csv	Structured output
psc -q	Quiet: print matching PIDs only
psc --uninstall	Uninstall psc and remove leftovers
psc --uninstall -f	Uninstall without confirmation
psc --help	Show help

Running psc with no arguments prints an ASCII banner with version, developer, release date, and quick tips. Process listings show: index, PID, name, user, %CPU, MEM, port(s), IP(s), and status.

Filters (-n, -pid, -p, -ip) can be chained and are applied with AND logic. -q, --json, and --csv are mutually exclusive.

---

Install from the repository (clone)

Linux

1. Clone the repository and enter it:

git clone https://github.com/ramarak/psc.git
cd psc

2. Run the installer (installs to ~/.local/bin/psc):

chmod +x install.sh linux/psc.sh
./install.sh

For a system-wide install (/usr/local/bin/psc):

./install.sh --system

3. If the installer warns that ~/.local/bin is not in your PATH, add this to ~/.bashrc or ~/.zshrc and reload the shell:

export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc

4. Verify:

psc --help
psc -n bash

Windows

1. Clone the repository and enter it (PowerShell or CMD):

git clone https://github.com/ramarak/psc.git
cd psc

2. Run the installer (copies files to %LOCALAPPDATA%\psc and adds that folder to the user PATH):

powershell -ExecutionPolicy Bypass -File .\install.ps1

3. Close and open a new terminal so the updated PATH applies everywhere.

4. Verify:

psc --help
psc -n powershell

---

Install from Releases

On the repository Releases page you will find per-platform assets (for example psc-linux.zip and psc-windows.zip).

Linux (from release)

1. Download the Linux asset (e.g. psc-linux.zip) from Releases.
2. Extract it:

unzip psc-linux.zip -d psc-linux
cd psc-linux

Expected contents: psc.sh (or linux/psc.sh, depending on how the release is packaged).

3. Install it on your PATH:

# Manual copy
mkdir -p ~/.local/bin
cp psc.sh ~/.local/bin/psc

# or, if nested in a subfolder:
# cp linux/psc.sh ~/.local/bin/psc
chmod +x ~/.local/bin/psc

4. Make sure ~/.local/bin is on your PATH (same as the clone install), then verify:

psc --help

Windows (from release)

1. Download the Windows asset (e.g. psc-windows.zip) from Releases.
2. Extract it to a temporary folder.
3. Copy psc.ps1 and psc.cmd to a permanent folder, for example:

$dest = Join-Path $env:LOCALAPPDATA 'psc'
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item .\psc.ps1, .\psc.cmd -Destination $dest -Force
# If they live under windows\:
# Copy-Item .\windows\psc.ps1, .\windows\psc.cmd -Destination $dest -Force

4. Add that folder to the user PATH:

$dest = Join-Path $env:LOCALAPPDATA 'psc'
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $dest) {
  [Environment]::SetEnvironmentVariable('Path', "$userPath;$dest", 'User')
}

5. Open a new terminal and verify:

psc --help

If the release includes install.ps1, you can run that instead after extracting the full repo zip.

---

Using -k and -f

-k kills a process by the index shown in the last search (not by PID directly).

psc -n node        # list matches and save the result
psc -k 2           # ask for confirmation, then kill #2
psc -k 2 -f        # kill #2 without asking
psc -k 1,3,5 -f    # kill several indices
psc -k 1-4 -f      # kill a range
psc -k all -f      # kill every result from the last search
psc -k 1 -s SIGINT # Linux: send SIGINT; Windows: graceful close mapping

If there is no previous search (missing or empty temp file), -k errors and asks you to run psc -a (or a filter) first.

Interactive, watch, tree, and info

psc -n node -i          # TUI: arrows + K/Delete to kill, q to quit
psc -n node -w 2        # refresh the filtered list every 2s
psc -a -t               # full process tree
psc -n node --info 1    # executable path, cmdline, open files/sockets

Structured output

psc -n nginx --json
psc -a --csv
psc -n nginx -q | xargs echo

Uninstall

psc --uninstall      # asks for confirmation
psc --uninstall -f   # no confirmation

This removes the installed binary/scripts, clears the last-search cache, and on Windows also removes the install folder from the user PATH.

---

Testing

Self-contained runners (no Pester/bats). They spawn short-lived fixtures and exercise the CLI.

Windows

powershell -ExecutionPolicy Bypass -File .\tests\windows\run-tests.ps1

Linux (native or WSL)

bash ./tests/linux/run-tests.sh

From Windows with WSL:

wsl -e bash ./tests/linux/run-tests.sh

---

Requirements

• Linux: bash, ps, and ss or netstat; kill to terminate processes. Optional: lsof for richer --info.
• Windows: PowerShell 5+; Get-Process; netstat (or Get-NetTCPConnection); Stop-Process.
• No external dependencies or extra package managers.

Repository layout

psc/
├── README.md
├── README.es.md
├── install.sh          # Linux installer
├── install.ps1         # Windows installer
├── linux/
│   └── psc.sh
├── windows/
│   ├── psc.ps1
│   └── psc.cmd         # wrapper so `psc` works from CMD/PowerShell
└── tests/
    ├── helpers/        # fixture spawners
    ├── linux/run-tests.sh
    └── windows/run-tests.ps1

The linux/ and windows/ folders are intended for packaging in each release.

License

This project is licensed under the MIT License.