ferman

Appearance

fermanInspect ports. Free them fast.

A cross-platform CLI for identifying and releasing busy ports with predictable output for humans and AI agents.

Get Started
GitHub
ferman logo

Human and agent friendly

Use interactive prompts when you want safety, or use JSON, TOON, and stable exit codes when you need automation.

Cross-platform

Supports macOS, Linux, and Windows with platform-specific process inspection behind a single CLI interface.

Release-ready workflow

Ships with linting, tests, smoke checks, trusted publishing, and GitHub Pages docs.

Overview ​

ferman is a small cross-platform DevOps CLI for identifying which process is using a port and releasing it safely when needed.

It is designed to work well for both humans and AI agents:

  • interactive confirmation for safe termination
  • --force for direct action
  • --dry for inspection only
  • --json for scripts, CI, and agents
  • --toon for compact LLM-oriented structured output
  • --list for active listening port inventory
  • multi-port support for batch inspection
  • --common for common local development ports
  • --plan for recommendations without termination
  • --doctor for environment-level diagnosis
  • --node for active Node.js process listing
  • --filter for focused Node.js and node-port listings
  • --node-ports for active Node.js processes with listening ports
  • --kill-all --name for process targeting by name or command pattern
  • --self to include the current ferman invocation in node-oriented listings
  • --signal for explicit termination signals on Unix-like systems
  • --json-schema for integration-safe contracts
  • --watch for continuous re-checking
  • --changed-only for quieter watch output
  • ferman-mcp for MCP-based agent integration over stdio
  • predictable exit codes for automation

Install ​

Run without installing:

bash
npx ferman 3000

Install globally:

bash
npm install -g ferman
ferman 3000

Tools ​

Core commands:

bash
ferman 3000
ferman 3000 --force
ferman 3000 --dry
ferman --list --json
ferman 3000 --json
ferman 3000 --toon
ferman 3000 5173 5432 --json
ferman --common --json
ferman --plan --json
ferman --doctor --json
ferman --node --json
ferman --node --filter mcp --json
ferman --node --self --json
ferman --node-ports --json
ferman --kill-all --name vite --json
ferman --kill-all --name vite --signal SIGKILL --json
ferman --json-schema
ferman 3000 --watch --json
ferman 3000 --watch --changed-only --json
npx -p ferman ferman-mcp

Capabilities matrix:

CapabilityCommandOutputAction
Inspect a portferman 3000Human-readableFinds the process and asks before termination
Force releaseferman 3000 --forceHuman-readableFinds the process and terminates without confirmation
Dry inspectionferman 3000 --dryHuman-readableFinds the process and does not terminate anything
Port listferman --list --jsonMachine-readable JSONLists active listening ports with their bound processes
Multi-port supportferman 3000 5173 5432 --jsonMachine-readable JSONReturns batch results and a summary for multiple ports
Common-port scanferman --common --jsonMachine-readable JSONScans a stable set of common local development ports
Plan modeferman --plan --jsonMachine-readable JSONReturns a recommended next action without terminating processes
Doctor modeferman --doctor --jsonMachine-readable JSONReturns a local development diagnosis and summary
Node process listingferman --node --jsonMachine-readable JSONLists active Node.js processes with PID and command data
Filtered node listingferman --node --filter mcp --jsonMachine-readable JSONRestricts node-oriented output to matching process names or commands
Node process listing with selfferman --node --self --jsonMachine-readable JSONIncludes the current ferman invocation in the process list
Node process port listingferman --node-ports --jsonMachine-readable JSONLists active Node.js processes together with listening ports
Kill by process patternferman --kill-all --name vite --jsonMachine-readable JSONTerminates all matching processes by name or command pattern
Custom kill signalferman --kill-all --name vite --signal SIGKILL --jsonMachine-readable JSONUses an explicit signal for Unix-like process termination
JSON modeferman 3000 --jsonMachine-readable JSONReturns structured output for scripts, CI, and AI agents
JSON Schemaferman --json-schemaMachine-readable JSONPrints the JSON Schema for structured output consumers
Watch modeferman 3000 --watch --jsonJSON event streamRe-checks ports continuously and emits snapshot events
Changed-only watch modeferman 3000 --watch --changed-only --jsonJSON event streamEmits a new watch snapshot only when the result changes
MCP wrappernpx -p ferman ferman-mcpMCP stdio serverExposes ferman operations as MCP tools for agent integrations
TOON modeferman 3000 --toonMachine-readable TOONReturns compact structured output optimized for LLM-facing workflows
Free port no-opferman 3000Human-readableReports that the port is already free and exits successfully
Invalid input handlingferman abc, ferman abc --json, ferman abc --toonError, JSON, or TOONRejects invalid port input with a deterministic exit code

Example JSON output:

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

Example TOON output:

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

Exit codes:

  • 0: success
  • 1: runtime error
  • 2: invalid input

Machine error codes:

  • INVALID_ARGUMENTS
  • INVALID_PORT
  • OUTPUT_MODE_CONFLICT
  • UNSUPPORTED_PLATFORM
  • COMMAND_UNAVAILABLE
  • PERMISSION_DENIED
  • PROCESS_NOT_FOUND
  • KILL_FAILED
  • INSPECTION_FAILED
  • UNKNOWN_ERROR

Platform support:

  • macOS and Linux: lsof, ps
  • Windows: netstat, tasklist, taskkill

Verification status:

  • macOS: verified in a live runtime environment
  • Linux: implemented and parser-tested
  • Windows: implemented and parser-tested

Development commands:

bash
npm run lint
npm test
npm run typecheck
npm run build
npm run smoke
npm run release:check

If ferman helps you keep local development moving, you can support ongoing maintenance through GitHub Sponsors:

Support ​

For bugs, regressions, and feature requests, use GitHub Issues:

Resources ​

The hands of AI.

MIT Licensed