Portsy

Portsy – A fast, cross-platform Node.js utility to check and discover available TCP ports, with a fully-featured CLI. Lightweight, easy to use, and fully asynchronous, Portsy enables high-performance port scanning with support for concurrency, making it ideal for development, CI/CD pipelines, and network diagnostics.

Pronunciation: Say it like PORT-u — the “s” is shy and stays silent, and the “y” just wants to be a “u”!

Features

• Check if a specific TCP port is available.
• Find one or more available ports within a given range.
• Supports custom host, range, count, and concurrency.
• Validates input ports and timeouts.
• Lightweight and fully ES module compatible.
• Works on Windows, macOS, and Linux.

Installation

npm install portsy

or

yarn add portsy

Usage

Library

import { isPortAvailable, findAvailablePort } from 'portsy';

;(async () => {
    // Check if port 3000 is available
    const isAvailable = await isPortAvailable({ port: 3000 });
    console.log('Is port 3000 available?', isAvailable); 
    // Output: true or false

    // Find up to 10 available ports in the range 3000 to 4000
    const availablePorts = await findAvailablePort({ 
        startPort: 3000, 
        endPort: 4000, 
        count: 10 
    });
    console.log('Available ports', availablePorts);
    // Output example: [3000, 3001, 3002, ...]

    // Find an available port (default range : [3000, 3100])
    const [availablePort] = await findAvailablePort();
    console.log('Available port:', availablePort);
    // Output example: 3000
})();

Note: This example uses top-level async with an IIFE; you can adapt it in your app as needed.

API

isPortAvailable(args: IPortAvailableArgs): Promise<boolean>

Check whether a specific TCP port is available.

| Property | Type | Default | Description | | --------- | ------------------ | ----------- | ---------------------------------------------- | | port | number \| string | — | Port number to check (required) | | host | string | localhost | Hostname or IP to check | | timeout | number | 2000 | Maximum time in ms before assuming unavailable |

Resolves to true if the port is available, or false otherwise.

findAvailablePort(options: IFindAvailablePortArgs): Promise<number[]>

Find one or more available ports within a given range.

| Property | Type | Default | Description | | --------------- | ---------- | ----------------- | ----------------------------------- | | startPort | number | 3000 | Starting port of the range | | endPort | number | startPort + 100 | Ending port of the range | | host | string | localhost | Hostname or IP to check | | count | number | 1 | Number of ports to find | | concurrency | number | 10 | How many ports to check in parallel | | isAvailableFn | function | isPortAvailable | Custom port checking function |

Returns an array of available port numbers.

CLI (Command-Line-Interface)

Portsy comes with a fully functional Command-Line Interface (CLI) to quickly check and find available TCP ports without writing code.

Install globally to use the CLI:

npm install -g portsy

Or run via npx portsy without global install.

Available Commands

| Command | Description | | ------------- | ---------------------------------------------------- | | scan <port> | Check whether a specific TCP port is available. | | find | Find one or more available TCP ports within a range. | | info | Display author and contributor information. | | version | Show the current Portsy version. |

scan — Check port availability

Check if a specific TCP port is available on a host.

# Check port 3000 on localhost (returns 0 if available, 1 if not)
portsy scan 3000

# Check port 3000 on a custom host (returns 0 if available, 1 if not)
portsy scan 3000 --host 127.0.0.1

# JSON output (includes PID if port is in use)
portsy scan 3000 --json
# Example output: {"port":"3000","isAvailable":false,"pid":41818}

# CI-friendly mode (returns 0 if available, 1 if not)
portsy scan 8080 --ci

Options:

| Option | Description | | --------------- | ---------------------------------------------- | | -h, --host | Host to check (default: localhost) | | -t, --timeout | Timeout in milliseconds (default: 2000) | | --ci | CI mode: exit code indicates port availability | | --json | Output results in JSON format | | --command | Custom shell command to get PID (optional) |

find — Find available ports

Locate one or more available TCP ports.

# Find a single available port (default range 3000–3100)
portsy find

# Find 5 available ports within a range
portsy find --start-port 3000 --end-port 4000 --count 5

# Scan with higher concurrency
portsy find --concurrency 50

Options:

| Option | Description | | --------------- | ------------------------------------ | | -c, --count | Number of ports to find | | --concurrency | Number of ports to check in parallel | | --start-port | Starting port of the range | | --end-port | Ending port of the range | | -h, --host | Host address to bind to |

If an invalid option is provided, Portsy will print an error message and exit with code 1.

info — Display project info

Shows author details and GitHub contributors.

# Display author name
portsy info --name

# Display author email
portsy info --email

# Display GitHub info
portsy info --github

# List contributors (with optional pagination)
portsy info --contributors --limit 5 --page 2

Options:

| Option | Description | | ------------------ | --------------------------------------------- | | --name | Show author name | | --email | Show author email | | --github [field] | Show GitHub info (username, url, or both) | | --contributors | List GitHub contributors | | --limit | Number of contributors per page | | --page | Page number for pagination |

version — Show CLI version

portsy --version
# Example output: 1.0.0

Tip: You can combine options like portsy scan 3000 --json to integrate into scripts or CI/CD pipelines.

Contributing

Contributions are welcome! 🎉

Whether it's fixing bugs, improving documentation, or adding new features. We appreciate all contributions.
Please read our Contributing Guidelines to learn how to set up the project locally, follow our coding standards, and submit a pull request.

License

MIT