agent-hive

# portctl Cross-platform tool for inspecting and managing port usage, supporting Linux / macOS / Windows. - **find**: find processes occupying a given port - **kill**: kill processes occupying a given port - **list**: list all port usage on the system - Supports wildcards, IPv6, and TCP/UDP protocol filtering; results are printed as a table - Output language (Chinese / English) selectable via Cargo features ## Installation Install from [crates.io](https://crates.io/crates/portctl): ```bash cargo install portctl ``` Or build and install from source: ```bash git clone https://github.com/RowanCole/portctl cd portctl cargo install --path . ``` The binary is installed to `~/.cargo/bin/portctl` (make sure `~/.cargo/bin` is in your PATH). ### Output language The output language is selected at compile time via Cargo features (`zh` and `en` are mutually exclusive): ```bash cargo install portctl # Chinese (default) cargo install portctl --no-default-features --features en # English # when building from source cargo build # Chinese (default) cargo build --no-default-features --features en # English ``` ## Usage ### Command format ``` portctl find <ip:port>[/proto] portctl kill <ip:port>[/proto] portctl list ``` - **Protocol**: one of `TCP` / `UDP` / `*` (case-insensitive); `*` matches both protocols - **Omitting the protocol**: `/proto` may be omitted, or written as `/` (`*:8080/`), which is equivalent to `*` - **Omitting the IP**: `:3000` is equivalent to `*:3000` and matches all local IPs - **Wildcard `*`**: - For ip: matches all local IPs (`0.0.0.0`, `127.0.0.1`, LAN IPs, IPv6) - For port: matches any port in 0-65535 - For protocol: matches both TCP and UDP - **IPv6**: the address must be wrapped in brackets, e.g. `[::1]:8080` ### find — locate occupying processes ```bash portctl find :3000 # all IPs' port 3000, shorthand for *:3000 portctl find *:8080 # port 8080 on all IPs, TCP+UDP together portctl find *:8080/TCP # TCP only portctl find *:8080/UDP # UDP only portctl find 127.0.0.1:8080/TCP # specific IP + specific protocol portctl find '[::1]:8080/UDP' # IPv6 address ``` Output (English build): ``` PID PROCESS PROTO LOCAL REMOTE STATE ------ ------- ---- ------------- --------- ------ 199261 python3 TCP 0.0.0.0:18096 0.0.0.0:0 LISTEN ``` UDP has no notion of "remote address" or "state"; those columns are filled with `-`. ### kill — kill occupying processes ```bash portctl kill *:8080 # kill all TCP+UDP occupants portctl kill *:8080/TCP # kill TCP occupants only portctl kill 127.0.0.1:8080/UDP # kill UDP occupants of a specific IP only ``` Example output: ``` Killed PID=199261 process=python3 ``` When a port is occupied by multiple processes, they are killed one by one; exit code is 0 if all succeed, otherwise each failure (e.g. insufficient permissions) is reported and the command exits with a non-zero code. ### list — list all ports ```bash portctl list ``` Prints all current TCP/UDP connections and listeners on the system, in the same format as find, sorted by protocol and local address. ### Shell wildcard caveats A bare `*` in the shell may be expanded to file names in the current directory: ```bash portctl find *:8080 # safe: *:8080 matches no file names, passed as-is portctl kill *:8080 # same as above portctl find *:8080/* # unsafe: the trailing * may be expanded; prefer quoting portctl find '*:8080' # quoting is always the safest habit ``` ### "Not found" message format When no process is found, the target in the message is normalized: a wildcard IP is shown as `0.0.0.0`, and a specified protocol is appended as a suffix: ``` $ portctl find *:57336/* No process found occupying 0.0.0.0:57336 $ portctl find *:57336/TCP No process found occupying 0.0.0.0:57336/TCP ``` ## Permissions - Viewing the PID / process name of processes owned by other users, or killing them, may require **root / administrator** privileges; with insufficient permissions the corresponding fields show `-` or the kill fails with an error - kill uses `SIGKILL` (Linux/macOS) / `TerminateProcess` (Windows), which cannot be intercepted by the target process ## Platform support | Platform | Port enumeration | Process name lookup | Kill | | -------- | ------------------ | ---------------------------- | ------------------- | | Linux | procfs / netlink | `/proc/{pid}/comm` | `kill(SIGKILL)` | | macOS | libproc | `libproc::proc_pid::name` | `kill(SIGKILL)` | | Windows | iphlpapi | `QueryFullProcessImageNameW` | `TerminateProcess` | Built on top of [netstat2](https://crates.io/crates/netstat2); basic port information can be viewed without administrator privileges.