hostparty

Cross-platform CLI and JavaScript API for managing your hosts file.

Installation

# CLI usage
npm install -g hostparty

# Library usage
npm install hostparty

Quick Start

As a Library

import party from 'hostparty';

// Add hosts to an IP
await party.add('127.0.0.1', ['myapp.local', 'api.local']);

// List all host entries
const hosts = await party.list();
// { '127.0.0.1': ['myapp.local', 'api.local'] }

// Remove specific hostnames
await party.removeHost('api.local');

// Remove all entries for an IP
await party.removeIP('127.0.0.1');

Configuration

import party from 'hostparty';

// Custom hosts file path and force mode
party.setup({
  path: '~/my-own/hosts',
  force: true,
  dryRun: false,      // Preview changes without writing
  autoBackup: true,   // Auto-backup before changes
  maxBackups: 10      // Max backups to keep
});

await party.removeIP('::1');  // Normally protected, but force allows it

CommonJS

const party = require('hostparty');

await party.add('127.0.0.1', ['example.local']);

---

API Reference

All methods return Promises.

party.add(ip, hosts)

Add hostname(s) to an IP address.

Parameter	Type	Description
ip	string	IP address to map to
hosts	string | string[]	Hostname(s) to add

await party.add('127.0.0.1', ['site.local', 'api.local']);

party.list([hostname])

List all entries, optionally filtered by hostname.

Parameter	Type	Description
hostname	string	Optional hostname to filter by

const all = await party.list();
const filtered = await party.list('myapp.local');

party.removeIP(ips)

Remove all entries for the specified IP address(es).

Parameter	Type	Description
ips	string | string[]	IP address(es) to remove

await party.removeIP(['127.0.0.1', '8.8.4.4']);

party.removeHost(hosts)

Remove specific hostname(s) from any IP.

Parameter	Type	Description
hosts	string | string[]	Hostname(s) to remove

await party.removeHost('old-site.local');

party.renameHost(oldHostName, newHostName)

Rename a hostname while keeping its IP binding.

Parameter	Type	Description
oldHostName	string	Current hostname
newHostName	string	New hostname

await party.renameHost('old-app.local', 'new-app.local');

party.moveHostname(hostname, toIP)

Move a hostname from its current IP to a new IP.

Parameter	Type	Description
hostname	string	Hostname to move
toIP	string	Destination IP address

await party.moveHostname('myapp.local', '192.168.1.100');

party.replaceIP(fromIP, toIP, [keepSource])

Migrate all hostnames from one IP to another.

Parameter	Type	Description
fromIP	string	Source IP address
toIP	string	Destination IP address
keepSource	boolean	Keep source IP (copy mode). Default: false

// Move all hostnames (removes source IP)
await party.replaceIP('192.168.1.1', '192.168.1.2');

// Copy all hostnames (keeps source IP)
await party.replaceIP('192.168.1.1', '192.168.1.2', true);

party.searchByIP(ip)

Find all hostnames mapped to a given IP address.

Parameter	Type	Description
ip	string	IP address to search for

Returns { ip, hostnames } or null if not found.

const result = await party.searchByIP('127.0.0.1');
// { ip: '127.0.0.1', hostnames: ['localhost', 'myapp.local'] }

party.disable(ips)

Disable IP entries by commenting them out.

Parameter	Type	Description
ips	string | string[]	IP address(es) to disable

await party.disable('192.168.1.100');
// Entry becomes: # 192.168.1.100 myapp.local

party.enable(ips)

Re-enable previously disabled IP entries.

Parameter	Type	Description
ips	string | string[]	IP address(es) to enable

await party.enable('192.168.1.100');
// Restores: 192.168.1.100 myapp.local

party.getStats()

Get statistics about the hosts file.

const stats = await party.getStats();
// {
//   activeIPs: 12,
//   disabledIPs: 2,
//   totalIPs: 14,
//   totalHostnames: 28,
//   uniqueHostnames: 25
// }

party.createBackup()

Create a backup of the current hosts file.

const backupPath = await party.createBackup();
// ~/.hostparty-backups/hosts.backup.2024-01-15T10-30-00-000Z

party.listBackups()

List all available backup files.

const backups = await party.listBackups();
// [{ filename, path, timestamp }, ...]

party.restore([backupPath])

Restore the hosts file from a backup.

Parameter	Type	Description
backupPath	string	Path to backup file. Default: latest backup

// Restore from latest backup
await party.restore();

// Restore from specific backup
await party.restore('/path/to/backup');

party.setup(options)

Configure hostparty. Returns the party instance for chaining.

Option	Type	Default	Description
path	string	auto	Custom path to hosts file
force	boolean	false	Bypass protection on system entries
dryRun	boolean	false	Preview changes without writing
autoBackup	boolean	true	Auto-backup before changes
maxBackups	number	10	Maximum backups to retain

party.setup({ path: '/custom/hosts', force: true }).removeIP('::1');

---

CLI Reference

Usage: hostparty [options] [command]

Commands:
  list [hostname]                    Output hosts file, optionally filtered
  add [ip] [hosts...]                Add hostname(s) to an IP address
  remove-ip [ips...]                 Remove all entries for IP address(es)
  remove-host [hosts...]             Remove specific hostname(s)
  rename-host [oldHost] [newHost]    Rename a hostname
  move-hostname [hostname] [toIP]    Move a hostname to a different IP
  search-ip [ip]                     Find all hostnames for an IP
  replace-ip [fromIP] [toIP]         Migrate hostnames between IPs
  disable [ips...]                   Comment out IP entries
  enable [ips...]                    Restore commented IP entries
  stats                              Show hosts file statistics
  backup                             Create a backup
  list-backups                       List available backups
  restore [filename]                 Restore from backup

Options:
  --path [path]     Path to hosts file (auto-detected by default)
  --force           Bypass validation on protected entries
  --no-group        Don't group output by IP
  --dry-run         Preview changes without applying
  --no-backup       Skip automatic backup
  --json            Output in JSON format (list, stats)
  --csv             Output in CSV format (list)
  --keep-source     Keep source IP when using replace-ip
  -h, --help        Show help
  -V, --version     Show version

Examples

# Add hosts
hostparty add 127.0.0.1 myapp.local api.local

# List all entries
hostparty list

# List entries matching a hostname
hostparty list myapp

# List in JSON format
hostparty list --json

# List in CSV format
hostparty list --csv

# Remove all entries for an IP
hostparty remove-ip 127.0.0.1

# Remove specific hostnames
hostparty remove-host old-site.local

# Rename a hostname
hostparty rename-host old.local new.local

# Move a hostname to a different IP
hostparty move-hostname myapp.local 192.168.1.100

# Find hostnames for an IP
hostparty search-ip 127.0.0.1

# Migrate all hostnames from one IP to another
hostparty replace-ip 192.168.1.1 192.168.1.2

# Copy hostnames (keep source)
hostparty replace-ip 192.168.1.1 192.168.1.2 --keep-source

# Temporarily disable an IP entry
hostparty disable 192.168.1.100

# Re-enable a disabled entry
hostparty enable 192.168.1.100

# Preview changes without applying
hostparty add 127.0.0.1 test.local --dry-run

# Show statistics
hostparty stats

# Create a backup
hostparty backup

# List available backups
hostparty list-backups

# Restore from latest backup
hostparty restore

# Restore from specific backup
hostparty restore hosts.backup.2024-01-15T10-30-00-000Z

# Skip auto-backup for a change
hostparty add 127.0.0.1 temp.local --no-backup

Smart Argument Detection

If you accidentally swap arguments, hostparty detects and offers to correct:

$ hostparty add example.com 192.168.1.100

Warning: Arguments might be swapped. Did you mean: 192.168.1.100 example.com?
Use the suggested order? (y/n): y
Using corrected order.
1 hostname(s) added to IP 192.168.1.100

---

Backup & Restore

Hostparty automatically creates backups before making changes. Backups are stored in ~/.hostparty-backups/.

# Manual backup
hostparty backup

# List backups
hostparty list-backups
# Found 3 backup(s):
#   hosts.backup.2024-01-15T10-30-00-000Z
#   hosts.backup.2024-01-14T15-45-00-000Z
#   hosts.backup.2024-01-13T09-00-00-000Z

# Restore latest
hostparty restore

# Restore specific backup
hostparty restore hosts.backup.2024-01-14T15-45-00-000Z

# Skip auto-backup for a single operation
hostparty remove-host temp.local --no-backup

Backup Configuration

party.setup({
  autoBackup: true,   // Enable/disable auto-backup (default: true)
  maxBackups: 10      // Maximum backups to keep (default: 10)
});

---

Dry Run Mode

Preview changes before applying them:

$ hostparty add 127.0.0.1 test.local --dry-run
[DRY RUN] Would add: test.local -> 127.0.0.1
[DRY RUN] No changes written to disk.

party.setup({ dryRun: true });
const result = await party.add('127.0.0.1', ['test.local']);
// { dryRun: true, message: 'Would add: test.local -> 127.0.0.1', preview: '...' }

---

Protected Entries

Certain entries are protected from accidental removal as they're critical for OS networking. Attempting to remove these without the force flag will result in an error.

Protected IP Addresses

IP	Purpose	OS
127.0.0.1	IPv4 loopback	All
::1	IPv6 loopback	All
fe80::1%lo0	Link-local address	macOS
255.255.255.255	Broadcast address	macOS

Protected Hostnames

Hostname	Purpose	OS
localhost	Loopback hostname	All
broadcasthost	Broadcast hostname	macOS

Overriding Protection

Use the --force flag (CLI) or force: true option (API) to modify protected entries:

# CLI
hostparty remove-ip 127.0.0.1 --force
hostparty remove-host localhost --force

// API
party.setup({ force: true }).removeIP('127.0.0.1');
party.setup({ force: true }).removeHost('localhost');

Warning: Removing these entries can break networking on your system. Use with caution.

License

MIT