Skip to content
Kickoutchi
installdocschangeloggithub
Documentation menu

CLI walkthrough

CLI

The swamp shortcut • print ports, filter precisely, and kick by port or PID from scripts.

The swamp shortcut: use the CLI when you already know which port to clear. CLI commands never open the TUI • they print to stdout/stderr and exit with a stable code.

There are three subcommands on every platform: list, inspect, and kill. Windows supports read-only inspect and CLI --tree; --group stays Linux/macOS-only. Use whichever binary you like • kick is shorter.

Listing ports

The table is plain, whitespace-separated text with no box-drawing • so it stays friendly to grep and awk. Withheld metadata shows as -.

Narrowing the list

list options
kick list --port 3000
kick list --process node
kick list --filter scope:public
kick list --sort pid
  • --port PORT • only the rows bound to one exact port.
  • --process TEXT • rows whose process name contains the text.
  • --filter TEXT • TUI-style search text or structured filters (see filters).
  • --sort MODE • port, pid, protocol, process, parent, or scope.

JSON for scripts

list --json prints a stable, documented shape • the field names and enum casing are a contract, so it’s safe to parse.

[
  {
    "protocol": "tcp",
    "local_addr": "127.0.0.1",
    "local_port": 3000,
    "state": "listen",
    "pid": 18422,
    "process_name": "node",
    "executable_path": "/usr/bin/node",
    "command_line": "node server.js",
    "parent_pid": 18001,
    "parent_process_name": "cursor-agent",
    "child_pids": [],
    "protected": false,
    "platform": "linux",
    "permission": "full"
  }
]

Missing metadata is null, never an empty string. An empty result is always [].

Killing by port or PID

kill needs exactly one target • a --port or a --pid • and asks before it does anything.

kill examples
kick kill --port 3000
kick kill --pid 18422
kick kill --port 3000 --yes
kick kill --pid 18422 --force
  • --force • stronger force confirmation; Unix uses kill -9, while Windows delivery is hard termination either way.
  • --yes • skip the normal prompt for a target you already trust.

Inspecting a process family

inspect is the read-only way to choose the right root before a scoped kill. It shows ancestors, descendants, siblings, command lines, ports, and suggested tree commands. Linux/macOS also show process-group members and --group hints.

inspect examples
kick inspect --port 3000
kick inspect --pid 18422

Tree and group scope

Normal kill still targets one PID. --tree adds descendant cleanup on Linux, macOS, and Windows; --group is the Linux/macOS-only POSIX process-group scope:

scoped kill examples
kick kill --port 3000 --tree
kick kill --pid 18422 --tree
kick kill --pid 18422 --group
  • --tree • terminate the target and its descendants. Type tree to confirm, or force with --force.
  • --group • terminate every visible member of the target’s POSIX process group. Type group to confirm, or force with --force.
  • --tree and --group conflict; pick one scope.
  • Windows rejects --group and does not expose TUI t/T tree keys. Windows CLI --tree uses Job Object containment and hard termination.

See Scoped kills for the Unix freeze-first and Windows Job Object safety details.

How the CLI behaves

  • An empty unfiltered list is success (exit 0) • a quiet machine isn’t an error.
  • An empty filtered result is no-match (exit 3) • so kick list --port 3000 && echo busy works as an occupancy probe.
  • kill --port refuses ambiguous ports • if two PIDs own one port, it lists the candidates and asks you to pick with --pid instead of guessing.
  • A port with no readable owner exits 4 (permission denied) rather than pretending it can act.

When a --port lookup finds no socket but a process mentions that port on its command line, Kickoutchi prints a “possible related process” hint to stderr so JSON on stdout stays clean.

Next

Want the terse index of every flag, filter, and exit code? See the command reference.