ferman

Inspect busy ports, identify the owning process, and release them with predictable output for humans and automation.

---

Overview

ferman is a cross-platform CLI for inspecting busy ports, identifying the owning process, and releasing the port safely when needed.

It is built for:

• interactive terminal use with explicit confirmation
• local debugging of blocked development ports
• scripts, CI, and agent workflows that need stable machine-readable output
• MCP integrations over stdio

Quick Start

Run without installing:

npx ferman 3000

Install globally:

npm install -g ferman
ferman 3000

Common Commands

Inspect a port:

npx ferman 3000

Release a port without confirmation:

npx ferman 3000 --force

Inspect without terminating anything:

npx ferman 3000 --dry

Inspect multiple ports:

npx ferman 3000 5173 5432

List active listening ports:

npx ferman --list

List active Node.js processes:

npx ferman --node

List active Node.js processes with listening ports:

npx ferman --node-ports

Kill all matching processes by pattern:

npx ferman --kill-all --name vite

Automation and MCP

Structured JSON output:

npx ferman 3000 --json

LLM-oriented TOON output:

npx ferman 3000 --toon

Plan mode without termination:

npx ferman 3000 --plan --json

Watch mode:

npx ferman 3000 --watch --json

MCP wrapper over stdio:

npx -p ferman ferman-mcp

Exposed MCP tools:

• inspect_ports
• release_ports
• doctor_ports
• list_node_processes
• list_node_ports
• get_output_schema

Capabilities

• inspect and release ports on macOS, Linux, and Windows
• inspect without termination using --dry and recommendation-oriented --plan
• list active listening ports with --list
• scan common local development ports with --common and --doctor
• list active Node.js processes and their listening ports
• target matching processes by name or command pattern with --kill-all --name
• emit stable JSON and TOON output for scripts, CI, and LLM-oriented workflows
• expose CLI operations through ferman-mcp
• keep exit codes and machine-readable error shapes predictable

When to Use It

Use ferman when:

• a local port is busy and you need to see what owns it
• you want an explicit way to release a blocked port
• you need structured output for tooling or agents
• you want a small CLI instead of platform-specific command chains

Do not use ferman when:

• you need container orchestration or deployment automation
• you want implicit destructive cleanup across an entire environment
• the problem is remote TLS, proxying, or infrastructure rather than local listeners

Example Output

JSON:

{
  "ok": true,
  "code": "PORT_RELEASED",
  "port": 3000,
  "busy": true,
  "action": "killed",
  "message": "Port released."
}

TOON:

ok: true
code: PORT_RELEASED
port: 3000
busy: true
processes[1]{pid,name}:
  1234,node
action: killed
message: Port released.

Philosophy

Dev tools should be fast, predictable, and boring.

ferman keeps local ports and processes observable and manageable without hiding destructive actions behind ambiguous automation.

Support

If ferman saves you time:

• Star the repo
• Support via GitHub Sponsors

https://github.com/sponsors/borakilicoglu

Links

• GitHub: https://github.com/borakilicoglu/ferman
• npm: https://www.npmjs.com/package/ferman
• Docs: https://borakilicoglu.github.io/ferman/