@sachinthapa572/killport

Kill processes running on specified ports - cross-platform CLI utility for freeing ports.

Features

• Cross-platform support (Windows, macOS, Linux)
• Simple CLI interface - Just run killport <port> or kp <port>
• Dry-run mode - Preview what would be killed
• Force kill by default - Reliably terminates processes
• Graceful kill option - Opt-in gentle termination
• Multiple ports - Kill several ports at once
• Timeout + retries - Retry with a bounded timeout
• Process ownership checks - Permission validation on Unix systems
• Reserved port warnings - Alerts for ports 1-1023 requiring elevated privileges

Installation

Global Installation

# Using npm
npm install -g @sachinthapa572/killport

# Using yarn
yarn global add @sachinthapa572/killport

# Using bun
bun install -g @sachinthapa572/killport

Local Installation

# Using npm
npm install @sachinthapa572/killport

# Using yarn
yarn add @sachinthapa572/killport

# Using bun
bun add @sachinthapa572/killport

Using npx (No Installation)

npx @sachinthapa572/killport 8080

Usage

Basic Usage

The CLI is available as both killport and the shorter alias kp:

# Kill a single port
killport 8080
# or using the short alias
kp 8080

# Kill multiple ports
killport 8080 3000 5000
# or
kp 8080 3000 5000

# Kill with verbose output
killport --verbose 8080
# or
kp -v 8080

Options

# Graceful kill (SIGTERM on Unix, no /F on Windows)
killport --graceful 8080
killport -g 8080

# Dry run - show what would be killed without executing
killport --dry-run 8080
killport -d 8080

# Set timeout (milliseconds, 1000-60000)
killport --timeout 5000 8080
killport -t 5000 8080

# Set retry attempts (0-5)
killport --retries 5 8080
killport -r 5 8080

# Verbose output
killport --verbose 8080
killport -v 8080

# Show help
killport --help
killport -h

Examples

# Kill development servers
killport 3000 8080 5000

# Gracefully kill a process (gentle termination)
killport --graceful 8080

# Preview what would be killed
killport -d -v 3000

# Kill with custom timeout and retries
killport -t 10000 -r 5 8080

CLI Options Reference

| Option | Short | Type | Default | Description | |--------|-------|------|---------|-------------| | --graceful | -g | boolean | false | Graceful kill (SIGTERM on Unix, no /F on Windows) | | --dry-run | -d | boolean | false | Preview without actually killing | | --verbose | -v | boolean | false | Show detailed output | | --timeout | -t | number | 30000 | Command timeout in milliseconds (1000-60000) | | --retries | -r | number | 3 | Number of retry attempts (0-5) | | --help | -h | | | Show help |

Platform Support

• Windows: Uses netstat and taskkill
• macOS: Uses lsof and kill
• Linux: Uses lsof and kill

Development

Prerequisites

• Bun >= 1.0.0
• Node.js >= 18.0.0 (optional, for npm compatibility)

Build from Source

# Install dependencies
bun install

# Build the CLI
bun run build

# Run in development mode
bun run dev

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Type check
bun run typecheck

# Lint
bun run lint

# Format code
bun run format

Releasing

This project uses a two-step release process: local version bump → automated CI publish.

How It Works

1. You bump version locally using the release script
2. Push to main - GitHub Actions detects the version change
3. CI automatically publishes to npm and creates GitHub release

Release Commands

# For bug fixes - patch bump (1.0.3 → 1.0.4)
./release.sh patch

# For new features - minor bump (1.0.3 → 1.1.0)
./release.sh minor

# For breaking changes - major bump (1.0.3 → 2.0.0)
./release.sh major

The script handles: tests → build → version bump → changelog → git tag → push → CI publishes to npm

What Gets Published?

GitHub Actions only publishes when:

• Files in src/** or package.json change
• Version in package.json is different from previous commit

Pushing docs, tests, or README changes won't trigger a release.

Commit Message Convention

When committing (VS Code will suggest these), use conventional format:

• feat: add new feature → use ./release.sh minor
• fix: resolve bug → use ./release.sh patch
• Breaking changes → use ./release.sh major

Testing

The project includes a comprehensive test suite using Bun's built-in test runner:

# Run all tests
bun test

# Run tests with coverage report
bun run test:coverage

# Run tests in watch mode
bun run test:watch

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Removed Features

For a list of features that were previously available but removed during codebase simplification, see FEATURES_REMOVED.md.