A cross-platform CLI for identifying and releasing busy ports with predictable output for humans and AI agents.
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:
--force for direct action--dry for inspection only--json for scripts, CI, and agents--toon for compact LLM-oriented structured output--common for common local development ports--plan for recommendations without termination--doctor for environment-level diagnosis--json-schema for integration-safe contracts--watch for continuous re-checkingRun without installing:
npx ferman 3000Install globally:
npm install -g ferman
ferman 3000Core commands:
ferman 3000
ferman 3000 --force
ferman 3000 --dry
ferman 3000 --json
ferman 3000 --toon
ferman 3000 5173 5432 --json
ferman --common --json
ferman --plan --json
ferman --doctor --json
ferman --json-schema
ferman 3000 --watch --jsonCapabilities matrix:
| Capability | Command | Output | Action |
|---|---|---|---|
| Inspect a port | ferman 3000 | Human-readable | Finds the process and asks before termination |
| Force release | ferman 3000 --force | Human-readable | Finds the process and terminates without confirmation |
| Dry inspection | ferman 3000 --dry | Human-readable | Finds the process and does not terminate anything |
| Multi-port support | ferman 3000 5173 5432 --json | Machine-readable JSON | Returns batch results and a summary for multiple ports |
| Common-port scan | ferman --common --json | Machine-readable JSON | Scans a stable set of common local development ports |
| Plan mode | ferman --plan --json | Machine-readable JSON | Returns a recommended next action without terminating processes |
| Doctor mode | ferman --doctor --json | Machine-readable JSON | Returns a local development diagnosis and summary |
| JSON mode | ferman 3000 --json | Machine-readable JSON | Returns structured output for scripts, CI, and AI agents |
| JSON Schema | ferman --json-schema | Machine-readable JSON | Prints the JSON Schema for structured output consumers |
| Watch mode | ferman 3000 --watch --json | JSON event stream | Re-checks ports continuously and emits snapshot events |
| TOON mode | ferman 3000 --toon | Machine-readable TOON | Returns compact structured output optimized for LLM-facing workflows |
| Free port no-op | ferman 3000 | Human-readable | Reports that the port is already free and exits successfully |
| Invalid input handling | ferman abc, ferman abc --json, ferman abc --toon | Error, JSON, or TOON | Rejects invalid port input with a deterministic exit code |
Example JSON output:
{
"ok": true,
"code": "PORT_RELEASED",
"port": 3000,
"busy": true,
"processes": [
{
"pid": 1234,
"name": "node"
}
],
"action": "killed",
"message": "Port released."
}Example TOON output:
ok: true
code: PORT_RELEASED
port: 3000
busy: true
processes[1]{pid,name}:
1234,node
action: killed
message: Port released.Exit codes:
0: success1: runtime error2: invalid inputMachine error codes:
INVALID_ARGUMENTSINVALID_PORTOUTPUT_MODE_CONFLICTUNSUPPORTED_PLATFORMCOMMAND_UNAVAILABLEPERMISSION_DENIEDPROCESS_NOT_FOUNDKILL_FAILEDINSPECTION_FAILEDUNKNOWN_ERRORPlatform support:
lsof, psnetstat, tasklist, taskkillDevelopment commands:
npm run lint
npm test
npm run typecheck
npm run build
npm run smoke
npm run release:checkIf ferman helps you keep local development moving, you can support ongoing maintenance through GitHub Sponsors:
For bugs, regressions, and feature requests, use GitHub Issues: