Programmatic and CLI editing for OS hosts file
npm install hostparty
Cross-platform CLI and JavaScript API for managing your hosts file.
``bashCLI usage
npm install -g hostparty
Quick Start
$3
javascript
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');
`$3
javascript
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
`$3
javascript
const party = require('hostparty');await party.add('127.0.0.1', ['example.local']);
`---
API Reference
All methods return Promises.
$3
Add hostname(s) to an IP address.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | IP address to map to |
| hosts | string \| string[] | Hostname(s) to add |`javascript
await party.add('127.0.0.1', ['site.local', 'api.local']);
`$3
List all entries, optionally filtered by hostname.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | Optional hostname to filter by |`javascript
const all = await party.list();
const filtered = await party.list('myapp.local');
`$3
Remove all entries for the specified IP address(es).
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string \| string[] | IP address(es) to remove |`javascript
await party.removeIP(['127.0.0.1', '8.8.4.4']);
`$3
Remove specific hostname(s) from any IP.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string \| string[] | Hostname(s) to remove |`javascript
await party.removeHost('old-site.local');
`$3
Rename a hostname while keeping its IP binding.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | Current hostname |
| newHostName | string | New hostname |`javascript
await party.renameHost('old-app.local', 'new-app.local');
`$3
Move a hostname from its current IP to a new IP.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | Hostname to move |
| toIP | string | Destination IP address |`javascript
await party.moveHostname('myapp.local', '192.168.1.100');
`$3
Migrate all hostnames from one IP to another.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | Source IP address |
| toIP | string | Destination IP address |
| keepSource | boolean | Keep source IP (copy mode). Default: false |`javascript
// 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);
`$3
Find all hostnames mapped to a given IP address.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | IP address to search for |Returns
{ ip, hostnames } or null if not found.`javascript
const result = await party.searchByIP('127.0.0.1');
// { ip: '127.0.0.1', hostnames: ['localhost', 'myapp.local'] }
`$3
Disable IP entries by commenting them out.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string \| string[] | IP address(es) to disable |`javascript
await party.disable('192.168.1.100');
// Entry becomes: # 192.168.1.100 myapp.local
`$3
Re-enable previously disabled IP entries.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string \| string[] | IP address(es) to enable |`javascript
await party.enable('192.168.1.100');
// Restores: 192.168.1.100 myapp.local
`$3
Get statistics about the hosts file.
javascript
const stats = await party.getStats();
// {
// activeIPs: 12,
// disabledIPs: 2,
// totalIPs: 14,
// totalHostnames: 28,
// uniqueHostnames: 25
// }
`$3
Create a backup of the current hosts file.
javascript
const backupPath = await party.createBackup();
// ~/.hostparty-backups/hosts.backup.2024-01-15T10-30-00-000Z
`$3
List all available backup files.
javascript
const backups = await party.listBackups();
// [{ filename, path, timestamp }, ...]
`$3
Restore the hosts file from a backup.
| Parameter | Type | Description |
|-----------|------|-------------|
|
| string | Path to backup file. Default: latest backup |`javascript
// Restore from latest backup
await party.restore();// Restore from specific backup
await party.restore('/path/to/backup');
`$3
Configure hostparty. Returns the party instance for chaining.
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
| 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 |`javascript
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
$3
bash
Add hosts
hostparty add 127.0.0.1 myapp.local api.localList all entries
hostparty listList entries matching a hostname
hostparty list myappList in JSON format
hostparty list --jsonList in CSV format
hostparty list --csvRemove all entries for an IP
hostparty remove-ip 127.0.0.1Remove specific hostnames
hostparty remove-host old-site.localRename a hostname
hostparty rename-host old.local new.localMove a hostname to a different IP
hostparty move-hostname myapp.local 192.168.1.100Find hostnames for an IP
hostparty search-ip 127.0.0.1Migrate all hostnames from one IP to another
hostparty replace-ip 192.168.1.1 192.168.1.2Copy hostnames (keep source)
hostparty replace-ip 192.168.1.1 192.168.1.2 --keep-sourceTemporarily disable an IP entry
hostparty disable 192.168.1.100Re-enable a disabled entry
hostparty enable 192.168.1.100Preview changes without applying
hostparty add 127.0.0.1 test.local --dry-runShow statistics
hostparty statsCreate a backup
hostparty backupList available backups
hostparty list-backupsRestore from latest backup
hostparty restoreRestore from specific backup
hostparty restore hosts.backup.2024-01-15T10-30-00-000ZSkip auto-backup for a change
hostparty add 127.0.0.1 temp.local --no-backup
`$3
If you accidentally swap arguments, hostparty detects and offers to correct:
bash
$ hostparty add example.com 192.168.1.100Warning: 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
.`bash
Manual backup
hostparty backupList 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 restoreRestore specific backup
hostparty restore hosts.backup.2024-01-14T15-45-00-000ZSkip auto-backup for a single operation
hostparty remove-host temp.local --no-backup
`$3
javascript
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:
bash
$ 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.
`javascript
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
flag will result in an error.$3
| 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 |$3
| Hostname | Purpose | OS |
|----------|---------|-----|
|
localhost | Loopback hostname | All |
| broadcasthost | Broadcast hostname | macOS |$3
Use the
--force flag (CLI) or force: true option (API) to modify protected entries:`bash
CLI
hostparty remove-ip 127.0.0.1 --force
hostparty remove-host localhost --force
`javascript
// 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.
MIT