Network Scan CLI

A command-line tool built with React Ink and TypeScript that scans your local network for active hosts and displays their IP addresses and hostnames in real-time.

Features

• 🔍 Scans your local network (typically /24 subnet) for active hosts
• 🏃‍♂️ Real-time display of scanning progress
• 🏷️ Resolves hostnames for discovered IP addresses
• 💻 Shows MAC addresses of discovered devices (optional)
• 🔎 Filter hosts by hostname using regular expressions
• ⚡ Fast concurrent scanning with batched updates
• 🎨 Modern terminal UI with React Ink

Installation & Usage

Using npx (Recommended)

The easiest way to use this tool is with npx, which runs it directly without installation:

# Run directly with npx
npx @suniltaneja/netscan-cli

# Run with hostname filter
npx @suniltaneja/netscan-cli --hostname raspberry

# Show MAC addresses
npx @suniltaneja/netscan-cli --mac

# Show MAC addresses with hostname filter
npx @suniltaneja/netscan-cli --mac --hostname raspberry

# Run from local directory during development
npx .

Global Installation

If you prefer to install the tool globally:

# Install globally
npm install -g @suniltaneja/netscan-cli

# Then run from anywhere
netscan-cli

Local Development

For local development or contributing:

# Clone and install
git clone <repository-url>
cd netscan-cli
npm install

# Link globally
npm link

# Build and run locally
npm run build
npx .

Usage

# Scan all hosts in your network
netscan-cli

# Filter hosts by hostname pattern
netscan-cli --hostname "raspberry"
network-scan -n "^esp32"

# Show help
netscan-cli --help

Options

• -n, --hostname: Filter hostnames using a regular expression pattern
• -m, --mac: Show MAC addresses of discovered hosts
• --help: Show help information
• --version: Show version number

Examples

# Find all Raspberry Pi devices
netscan-cli --hostname raspberry

# Find ESP32 devices
netscan-cli -n "^esp32"

# Find devices in a specific domain
netscan-cli -n "\.home\.com$"

Development

# Clone the repository
git clone https://github.com/suniltaneja/netscan-cli.git
cd netscan-cli

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run the built version
npm start

Technical Details

• Built with TypeScript and React Ink for a modern terminal UI
• Uses Node.js DNS and network utilities for host discovery
• Concurrent scanning with Promise-based architecture
• Real-time updates with React state management
• ES modules for modern JavaScript support

Requirements

• Node.js 16.0.0 or higher
• Network access (requires permission to ping hosts)

License

MIT © Sunil Taneja