LSPORT(1)

NAME
lsport - TUI and CLI tool for managing local and remote ports via SSH

SYNOPSIS
lsport [OPTIONS]
lsport describe [OPTIONS] PORT_OR_PID
lsport kill [OPTIONS] [--pid PID | --port PORT]

DESCRIPTION
lsport is a fast, interactive terminal user interface (TUI) and command-line tool for managing ports on local and remote machines via SSH. It allows you to quickly identify which process is using a port and kill it with a single keystroke.

Features include:

•   Live port monitoring with real-time updates

•   TCP and UDP support with multiple detection methods

•   Remote server monitoring via SSH

•   CLI mode with describe and kill commands

•   Vim-style navigation with keyboard shortcuts

•   Process termination with a single keystroke

•   Regex filtering for ports, PIDs, and process names

•   Zombie process detection with visual highlighting

•   K9s-inspired dark theme UI with color-coded information

OPTIONS

-H, --host HOST
    Remote host to monitor. Format: user@host:port or user@host or host.

-i, --identity PATH
    Path to SSH private key. If not specified, uses ssh-agent or default keys (~/.ssh/id_ed25519, ~/.ssh/id_rsa, ~/.ssh/id_ecdsa).

-s, --scan-interval SECS
    Scan interval in seconds. Default is 2.

-h, --help
    Print help information.

-V, --version
    Print version information.

CLI COMMANDS

describe PORT_OR_PID
    Get detailed information about a port or process by port number or PID. Output includes port number, protocol, PID, process name, CPU usage, memory usage, parent process status, and zombie process detection.

kill
    Kill a process by PID or port number. Requires either --pid or --port to be specified.

  Describe Command Options

-H, --host HOST
    Remote host to query. Format: user@host:port or user@host or host.

-i, --identity PATH
    Path to SSH private key. If not specified, uses ssh-agent or default keys.

  Kill Command Options

--pid PID
    Kill process by PID.

--port PORT
    Kill process by port number.

-H, --host HOST
    Remote host to query. Format: user@host:port or user@host or host.

-i, --identity PATH
    Path to SSH private key. If not specified, uses ssh-agent or default keys.

-f, --force
    Force kill using SIGKILL instead of SIGTERM.

KEYBINDINGS

  Navigation

↑ / k
    Move selection up.

↓ / j
    Move selection down.

PgUp
    Move up 10 rows.

PgDn
    Move down 10 rows.

Home
    Go to first entry.

End Go to last entry.

  Actions

Enter
    Kill selected process.

/   Enter filter mode (supports regex).

?   Toggle help popup.

Esc Clear filter or close help.

q   Quit.

  Sorting (K9s-style)

Shift+P / 1
    Sort by Port.

Shift+O / 2
    Sort by Protocol.

Shift+I / 3
    Sort by PID.

Shift+N / 4
    Sort by Name.

Shift+C / 5
    Sort by CPU %.

Shift+M / 6
    Sort by Memory.

Press the same key again to toggle ascending/descending order.

EXAMPLES

Monitor localhost:
    lsport

Monitor with sudo (needed for killing system processes):
    sudo lsport

Monitor a remote server via SSH:
    lsport --host user@example.com

Remote server with custom SSH port:
    lsport --host user@example.com:2222

Use a specific SSH key:
    lsport --host user@example.com -i ~/.ssh/my_key

Custom scan interval (5 seconds):
    lsport -s 5

Describe a port:
    lsport describe 8080

Describe a PID:
    lsport describe 12345

Describe on remote server:
    lsport describe -H user@example.com 8080

Kill process by port:
    lsport kill --port 8080

Kill process by PID:
    lsport kill --pid 12345

Force kill a process:
    lsport kill --port 8080 --force

Kill on remote server:
    lsport kill --port 8080 -H user@example.com

SSH AUTHENTICATION
For remote monitoring, authentication is attempted in this order:

1.  Specified key (-i flag)

2.  SSH agent (if running)

3.  Default keys: ~/.ssh/id_ed25519, ~/.ssh/id_rsa, ~/.ssh/id_ecdsa

FILTERING
Press / to enter filter mode. Filters support:

•   Simple text: node matches any entry containing "node"

•   Regex patterns: ^80[0-9]{2}$ matches ports 8000-8099

•   All filters are case-insensitive

AUTHOR
Written by Parash Subedi <subediparas5@gmail.com>.

MAINTAINER
Parash Subedi <subediparas5@gmail.com>

REPORTING BUGS
Report bugs at: https://github.com/subediparas5/lsport/issues

COPYRIGHT
Copyright © 2024-2026 Parash Subedi. License MIT.

SEE ALSO
netstat(8), ss(8), lsof(8), fuser(1)