TUI walkthrough

Run either binary with no subcommand to open the terminal UI.

kickoutchi
kick

Both names do the same thing • kickoutchi is canonical, kick is the short one.

The layout

The screen is split into four regions, top to bottom:

• Header • the title and a one-line key hint (r refresh / search s sort x/X kill t/T tree ? help q quit on Linux/macOS; Windows omits the tree keys).
• Open Ports table • one row per confirmed socket, with a >> marker on the selected row.
• Details panel • live context for whatever row is selected.
• Status line • visible/total port counts, last refresh age, current sort, active filter, and the result of your last kill.

Table columns

Rows are colour-coded: protected processes and rows with partial metadata (visible socket, unreadable owner) are tinted so you notice them before acting.

Moving around

Search and filter

Press / to start editing the filter, then type. The table narrows on every keypress.

• Enter keeps the filter and returns to the table.
• Esc clears it.

Plain text matches across port, address, PID, process, path, command line, parent, and label. You can also use the same structured filters as the CLI:

port:3000   proto:udp   scope:public   protected:true   parent:node
label:web   address:127.0.0.1   scope_id:3   family:ipv6

Terms combine with AND, and address: compares parsed addresses rather than text. state: is reserved for kick watch and is rejected here rather than being treated as a plain search word. See the command reference for the full grammar.

Sorting

Press s to cycle the sort mode. The order steps through port → pid → protocol → process → parent → scope, then wraps. Sorting by scope surfaces public binds first • the ones most worth a second look.

Refreshing

Kickoutchi re-collects ports automatically (every few seconds by default • tune it with refresh_interval_seconds in your config). Press r to refresh immediately. The status line shows how long ago the last refresh happened.

Details

The details panel always reflects the selected row. Press Enter for the full details modal, which also lazily loads the owner UID, the process’s children, and any protected-process warnings. The UID and children appear only when they were read from the same process as the row, so a reused PID never mixes two processes in one view. When the Docker CLI is available, Docker-owned ports show their container context here too.

Kicking a process out

Either opens the Confirm Termination modal showing the target identity, the affected ports, and the equivalent shell command (e.g. kill 18422, or kill -9 18422 for a force kill).

Tree kill opens a separate Confirm Tree Termination modal. Kickoutchi enumerates the bounded tree on a background worker, shows the process count and preview, then requires typing tree (or force for T). Execution always re-runs the tree scan fresh before the first freeze signal.

After a successful kick, the status area reports the outcome and the next refresh shows the port gone. Kill results and errors get their own wrapped rows above the routine status line. When a report is longer than that space, such as a cleanup failure listing many stopped PIDs, the preview says so and m opens the complete, scrollable report.

For process-group cleanup, use the CLI --group flow. The TUI intentionally exposes only tree scope, so the broader process-group blast radius is reviewed in a full CLI banner.

A few edge states

• Esc is context-aware • it clears the search, closes an open modal, cancels a kill confirmation, or quits, depending on what’s on screen.
• Terminal too small • below 80×20 the TUI shows a “Terminal too small” notice instead of a cramped, unreadable table. Resize and it returns.
• Warnings that don’t fit • a kill confirmation wraps its warnings instead of cutting them off. If the terminal can’t show every warning and the prompt, the confirmation is cancelled rather than shown partially.

Next

Already know which port to clear? The CLI walkthrough is the swamp shortcut. Need the big green boot? Read Scoped kills.