lpm ports

lpm ports shows project service ports and helps you find the process behind a port conflict.

lpm ports [action] [target]

Quickstart with lpm.json

Declare preferred service ports:

{
  "$schema": "https://cli.lpm.dev/schemas/lpm.json",
  "services": {
    "web": { "command": "vite", "port": 5173 },
    "api": { "command": "node api.js", "port": 4000 }
  }
}

lpm ports
lpm dev

lpm dev can assign replacement ports after conflicts. From another terminal, inspect the assignments:

lpm ports --json

A saved assignment takes precedence over the declared port. Without a saved assignment, the command shows the declared port.

These values are preferred assignments, not proof that a service is running. Each row reports whether its port is free or in use.

Examples

lpm ports
lpm ports all
lpm ports 5173
lpm ports inspect 5173 --json
lpm ports kill 5173
lpm ports kill 3000-3010 --yes --json
lpm ports kill --pid 48213
lpm ports reset --json

Saved assignments and hostnames

A hostname service can omit its port:

{
  "proxy": {
    "host": "app.localhost",
    "port": 9443,
    "httpRedirect": false
  },
  "services": {
    "web": { "command": "vite", "primary": true }
  }
}

lpm dev

After development startup saves an assignment, lpm ports includes that service. This applies to proxy.host and services.<name>.host workflows.

A saved assignment remains visible if you remove the hostname configuration. Use reset to clear it.

Without a saved assignment or a declared port, a service has no row. readyPort alone does not supply a listed port.

Without HTTPS, lpm dev --port <PORT> overrides the primary application port for one run. With HTTPS, it selects the HTTPS frontend port.

The override need not replace the saved assignment. Read startup output or inspect active listeners for the running port.

The listed service port is the application port. It is separate from the HTTPS listener configured by lpm proxy.

Project scope

list and reset act on the project: the nearest directory at or above the current one that has a package.json or an lpm.json, stopping before your home directory. LPM CLI prints that directory when it is not the current one. Run the command from the project root or any of its subdirectories.

If the configuration contains services, list shows their declared or saved assignments in service-name order.

Without configured services, list shows visible listeners associated with the project directory. Operating-system access can limit the available project information.

To inspect listeners across projects:

lpm ports all
# Equivalent:
lpm ports --all

Port inspection and process termination are not restricted to the current project's services.

Resolve a port conflict

Inspect the owner before deciding to stop its process:

lpm ports inspect 5173

If that process is no longer needed:

lpm ports kill 5173
lpm ports reset
lpm dev

A single-port kill does not request consent. It requests termination of the entire process, including its other listeners.

On Unix, LPM CLI sends SIGTERM. Success confirms the request, without waiting for the process to exit.

If the port is already free, the command succeeds without stopping anything. If the owner changes during validation, LPM CLI refuses to stop the replacement owner.

Stop a range

lpm ports all
lpm ports kill 3000-3010

Ranges are inclusive and must be ascending. Ports are integers from 0 to 65535.

If listeners match, the command groups ports by PID and requests consent. A matching process can also own ports outside the range.

For scripts and JSON output, give explicit consent:

lpm ports kill 3000-3010 --yes --json

An empty range result succeeds without consent. Process identities and ownership are checked again before termination.

Stop a known PID

lpm ports kill --pid 48213

This action does not request consent. The process does not have to own a TCP listener.

A numeric positional target always means a port. Use --pid for a process ID, without a positional target.

LPM CLI refuses to stop protected system PIDs or itself. Permission failures return an error.

Reset saved assignments

lpm ports reset --json

Reset clears only the project's entries from the saved port state. It preserves other projects and coordinates with development startup.

It does not edit lpm.json or stop processes. On the next start, lpm dev tries the declared ports again.

If a declared port is still unavailable, LPM CLI can assign another port.

Missing saved state is a successful no-op. Malformed TOML, an unreadable state file, or a failed write returns an error.

If reset fails, inspect the reported state file and permissions, correct the problem, and retry.

JSON output

lpm ports --json
lpm ports all --json
lpm ports inspect 5173 --json
lpm ports reset --json

Listener details can include the address, PID, process, command, project directory, framework, and uptime. Unavailable details can be null.

Errors return success: false. Successful responses return success: true.

Platform support

Windows does not expose another process's current directory through a stable public API. Generic processes can therefore lack project information.

Port and range termination requires operating-system support that binds termination to a captured process identity. Unsupported BSD systems, older Linux kernels, and macOS releases without that support return an error.

System permissions can limit results on every platform.

Flags

See global flags for shared options.

See also

• lpm dev — start services and assign application ports
• lpm proxy — inspect HTTPS listeners and hostname routes
• lpm.json — configure service ports
• Port management — assignments and reservations