Command reference

Use this page when you know the command and need its exact syntax. For worked examples, see the CLI walkthrough and Scoped kills.

Binary names

Running either with no subcommand opens the TUI. --version reports kickoutchi under both names.

Global options

These work with or without a subcommand.

list

Print open ports and exit.

kick list [OPTIONS]

An empty unfiltered list exits 0. An empty filtered result exits 3.

--snapshot-json ignores --port, --process, --filter, --sort, and hide_system_processes by design, and omits full command lines. See Structured output.

kill

Terminate the process owning a port or PID, after confirmation.

kick kill <--pid PID[,PID...] | --port PORT[,PORT...]> [OPTIONS]

Pass PIDs or ports, not both. Repeat the flag or separate values with commas to kill up to 128 processes behind one confirmation and one summary. --tree and --group take one target.

The equivalent command shown before confirmation is kill PID (terminate) or kill -9 PID (force) on Linux/macOS, and taskkill /F /PID PID on Windows.

After delivery, kill waits up to two seconds and reports separately whether each process exited and whether its confirmed ports are still visible. A batch’s exit code is the most serious outcome across its targets: 1, then 4, then 6, then 3.

Scoped kill confirmations use stronger words: tree, group, or force. The command preview is always re-collected fresh at execution time; stale previews are not trusted. --group is rejected on Windows, and Windows --tree uses Job Object containment with hard termination.

inspect

Show a process family without signalling anything.

kick inspect <--pid PID | --port PORT>

Exactly one of --pid / --port is required.

inspect --pid is read-only and can inspect a portless supervisor. inspect --port follows the same target-resolution rules as kill --port.

watch

Stream bounded socket changes until interrupted or the duration expires. Read-only.

kick watch [OPTIONS]

Events are baseline, bind, release, replacement, and collection_gap. A failed initial collection exits 1; after a valid baseline, the third consecutive failure exits 1. Ctrl-C, duration expiry, and a closed consumer exit 0. Docker is never invoked in the polling loop.

why

Explain whether exact local endpoints are bindable now. Read-only apart from a temporary bind that is closed immediately.

kick why <PORT> [OPTIONS]

The default query probes TCP on 127.0.0.1, then ::1. The matrix is protocol-major and capped at eight endpoints. For a multi-endpoint query the aggregate exit code takes the worst result: 1, then 4, then 3, and 0 only when every endpoint proved bindable. See Watch & Why.

Filters

Used by list --filter, watch --filter, and the TUI search box. Multiple terms are combined with AND, and so are repeated fields. Bare words are matched as substrings across the visible fields.

kick list --filter 3000
kick list --filter port:3000
kick list --filter 'label:web family:ipv4'
kick list --filter address:127.0.0.1
kick list --filter 'proto:tcp family:ipv6 parent:node'
kick watch --filter state:listen

address: matching parses the address rather than comparing text, so address:::1 and address:0:0:0:0:0:0:0:1 are the same query, and IPv4-mapped IPv6 addresses normalize to IPv4.

state: is reserved for watch. list and the TUI reject it rather than quietly treating it as plain search text. Accepted values:

listen bound closed syn_sent syn_received established fin_wait1 fin_wait2
close_wait closing last_ack time_wait delete_tcb new_syn_received unknown

Filter expressions are bounded to 256 UTF-8 bytes. An invalid structured value (e.g. port:not-a-port) is a usage error (exit 2).

In watch, an owner-dependent term must be satisfied by the same conceptual owner • two different owners cannot each satisfy half of one expression. When a needed owner or metadata fact is missing, the event is emitted as indeterminate instead of being silently dropped, unless you pass watch --matched-only.

Sort modes

port • pid • protocol • process • parent • scope

Sorting by scope lists public binds first, then local, then loopback. Rows missing the sort key sink to the bottom. In the TUI, s cycles through these in order.

JSON output

list --json emits an array of objects with this stable shape:

Missing metadata is null. An empty result is []. label is the only field added in 1.3.0; child_pids is a frozen 1.x compatibility field with no data behind it.

Three more contracts • kickoutchi.snapshot/1, kickoutchi.watch_event/1, and kickoutchi.why/1 • are documented in Structured output.

Exit codes

The script-facing contract • these numbers don’t drift.

Config

Defaults for sort, refresh interval, protected processes, and endpoint labels live in a config file. See Configuration.