lpm hosts

lpm hosts removes the hosts-file blocks that LPM CLI creates for local development hostnames.

lpm hosts [ACTION] [--yes] [--json]

clean is the only action and the default. It removes all managed blocks, including blocks for active projects.

Use lpm dev to add hostnames from lpm.json. Use clean after an interrupted session leaves entries behind.

Quickstart with lpm.json

Configure a hostname and an HTTPS port that does not require administrator privileges:

{
  "$schema": "https://cli.lpm.dev/schemas/lpm.json",
  "proxy": {
    "host": "app.test",
    "port": 9443,
    "httpRedirect": false
  }
}

lpm dev

lpm dev shows the hosts-file path, backup destination, and hostnames before it requests consent. With permission to write the file, it maps app.test to 127.0.0.1.

Open https://app.test:9443. LPM CLI removes the session's managed block during normal shutdown.

To approve the change without a consent prompt:

lpm dev --yes

--yes gives consent. It does not grant permission to edit the system file.

Examples

lpm hosts
lpm hosts clean
lpm hosts clean --yes --json
lpm dev --yes

Stop active development sessions before cleanup. Cleanup removes their hostname mappings too.

Configure multiple hostnames

Use services.<name>.host for individual services:

{
  "proxy": {
    "port": 9443,
    "httpRedirect": false
  },
  "services": {
    "web": { "command": "vite", "host": "web.test" },
    "api": { "command": "node api.js", "host": "api.test" }
  }
}

lpm dev

The session adds both hostnames to one managed block. Separate sessions have separate blocks. Normal shutdown removes only the session's own block.

proxy.host selects the sole service or the unique service with primary: true. See lpm proxy for route configuration.

Avoid hosts-file edits

Use a name below .localhost:

{
  "proxy": {
    "host": "app.localhost",
    "port": 9443,
    "httpRedirect": false
  }
}

LPM CLI skips hosts-file edits for these names. Resolution depends on your browser and operating system.

Other configured hostnames require entries. Common local suffixes include .test, .local, .internal, and .home.arpa.

The command has no hostname override. Change lpm.json to select hostnames or avoid edits for a development session.

Remove managed blocks

lpm hosts clean

The command shows the hosts-file path, backup destination, and block count. After consent, it checks the current count under a file lock.

If the count changed, cleanup stops without editing the hosts file. Run the command again to review the new count.

Cleanup preserves entries outside managed blocks. It does not restore an older hosts file.

If no managed blocks exist, the command succeeds without a consent prompt or a new backup.

Non-interactive cleanup

lpm hosts clean --yes --json

The process must already have permission to edit the file. Automatic elevation requires an interactive terminal.

--json does not give consent. Include --yes in scripts.

Backups

Before the first change, LPM CLI saves the current file to ~/.lpm/hosts.bak. With LPM_HOME, the destination is $LPM_HOME/hosts.bak.

An existing regular backup is preserved, including one created concurrently. Backup creation rejects symbolic links and other non-regular destinations.

The backup can predate later manual edits. Review it before any manual restoration. Replacing the current hosts file can remove newer entries from other tools.

Neither normal session shutdown nor lpm hosts clean restores the backup automatically.

Permissions and file selection

Consent comes before elevation. If authorization fails, cleanup returns an error.

Use --yes for consent instead of running the complete development command with elevated access.

LPM_HOSTS_FILE selects another hosts file and disables automatic elevation. For example, use a temporary fixture to inspect cleanup behavior:

LPM_HOSTS_FILE=./hosts.fixture lpm hosts clean --yes --json

This variable does not change the operating system's hostname lookup. lpm.json does not select the hosts-file path or backup destination.

Repair malformed blocks

LPM CLI refuses to remove an incomplete or nested managed block. It leaves the hosts file unchanged.

A complete block has matching markers:

# >>> lpm:project-example >>>
127.0.0.1 app.test
# <<< lpm:project-example <<<

If a block is malformed, open the hosts file with permission to edit it. Review the enclosed entries before repairing or removing the markers.

Preserve unrelated entries. Then run cleanup again:

lpm hosts clean

If the error reports a changed block count, stop active development sessions and retry. If it reports file access, resolve the reported permission failure.

Flags

See global flags for shared options.

See also

• lpm dev — start services and manage session hostnames
• lpm proxy — route local hostnames to services
• lpm cert — prepare local HTTPS certificates
• lpm.json — configure hostnames and listeners