DEV Community

Cover image for Building a Cross-Platform CLI Tool with TypeScript
Adeyomi Lawal
Adeyomi Lawal

Posted on

Building a Cross-Platform CLI Tool with TypeScript

#typescript #javascript #cli #opensource

The Problem

Every developer has seen this error:

\
Error: Port 3000 is already in use
\\

And every developer has done this:

  1. Open Google
  2. Search "how to kill port process [your OS]"
  3. Copy-paste: lsof -ti :3000 | xargs kill -9 (macOS)
  4. Hope it works
  5. Repeat tomorrow

After doing this 100+ times, I decided to build a solution.

Introducing zkill

zkill is a cross-platform CLI tool that kills zombie processes in one command:

\bash
zkill 3000
\\

That's it. Works on Mac, Linux, and Windows.

Features

  • 🎯 Smart detection - Shows what process is using the port
  • 🔒 Safe mode - Asks for confirmation before killing
  • 🧠 Project-aware - Remembers which ports belong to which projects
  • ⚡ Fast - Less than 100ms to detect processes
  • 🎨 Beautiful CLI - Color-coded output with spinners

Installation

\bash
npm install -g zombie-port-killer
\\

Quick Start

\`bash

Kill process on port 3000

zkill 3000

Kill without confirmation

zkill 3000 --force

List all active ports

zkill scan

Show system info

zkill info
`\

Technical Deep Dive

Architecture

I built zkill using a cross-platform adapter pattern. Each OS has its own adapter:

  • macOS: Uses lsof and ps
  • Linux: Uses ss (or netstat fallback) and ps
  • Windows: Uses netstat and tasklist/taskkill

[Code snippet of adapter pattern]

TypeScript Setup

Built entirely in TypeScript for type safety and better DX:

\json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
// ...
}
}
\\

Testing

114 tests covering all major functionality:

  • Unit tests for services
  • Integration tests for commands
  • Cross-platform compatibility tests

\bash
npm test
\\

What I Learned

1. Cross-Platform is Hard

Different operating systems use completely different commands for process management. Windows was particularly challenging.

2. UX Matters in CLI Tools

Even in a terminal, UX matters:

  • Color-coded output
  • Loading spinners
  • Clear error messages
  • Helpful prompts

3. Testing Saves Time

Comprehensive tests caught platform-specific bugs early and gave me confidence to ship.

4. Documentation is Critical

A good README is the difference between 0 users and 1000 users.

Roadmap

Coming in v1.1:

  • Kill multiple ports: zkill 3000 8000 5432
  • Kill by process name: zkill --name node
  • Port range support: zkill --range 3000-3010

Try it Out!

\bash
npm install -g zombie-port-killer
zkill --help
\\

Links:

What do you think? What features would you like to see next?

If you found this useful, please star the repo and share it with other developers!
\`

Top comments (0)