p2p-cli-chat

A terminal P2P chat app with two modes:

• Public (default) — peers find each other over the internet via Hyperswarm DHT. Works across different networks.
• Local — peers discover each other on the same LAN via UDP broadcast, then connect over TCP. No internet required.

Installation

npx p2p-cli-chat

# or install globally
npm i -g p2p-cli-chat

How it works

Public mode (Hyperswarm)

1. Both peers join a DHT topic derived from the shared room key
2. Hyperswarm handles NAT traversal and peer discovery automatically
3. Chat begins once a peer connects

Local mode

1. Each instance broadcasts its presence every 2 seconds on the LAN
2. Instances with the same room key see each other
3. You pick a peer from the list and connect over a direct TCP connection

Usage

p2p-chat [--public | --local] [-k <key>] [-p <port>]

If both --public and --local are passed, the first one in the argument list wins.

If neither is passed, --public is used by default.

Examples

# Public mode (default) — interactive key prompt
p2p-chat

# Public mode — with key provided
p2p-chat --public -k my-room

# Local mode — interactive prompts
p2p-chat --local

# Local mode — with key and port
p2p-chat --local -k my-room -p 4001

# Both flags — first one wins (public)
p2p-chat --public --local -k my-room

# Both flags — first one wins (local)
p2p-chat --local --public -k my-room

Testing locally (two terminals, same machine)

Local mode

Open two terminals and use the same key but different ports:

# Terminal 1
p2p-chat --local -k test-room -p 4000

# Terminal 2
p2p-chat --local -k test-room -p 4001

After a couple of seconds they discover each other. Type connect in either terminal, select the peer, and start chatting.

Requires an active network interface (Wi-Fi or Ethernet). UDP broadcast to 255.255.255.255 does not work over loopback only.

Public mode

Both instances can run on the same machine — they find each other through the DHT:

# Terminal 1
p2p-chat --public -k test-room

# Terminal 2
p2p-chat --public -k test-room

Requires internet access.

Options

| Flag | Description | Default | | ------------------- | ---------------------------------------- | -------- | | --public | Use Hyperswarm (internet DHT) | ✓ | | --local | Use LAN UDP broadcast + TCP | | | -k, --key <key> | Room key (shared discovery secret) | prompted | | -p, --port <port> | TCP listen port 4000–5000 (local only) | 4000 |

In-chat commands (local mode)

| Command | Description | | ------------- | ------------------------------ | | list | Show discovered devices | | connect | Select and connect to a device | | status | Show connection status | | exit | Quit | | anything else | Send as a chat message |

Requirements

• Node.js >= 18
• Same room key on both sides
• Local mode: both devices on the same LAN
• Public mode: internet access on both sides