die

package module
v0.0.0-...-77cdef5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 16, 2026 License: MIT Imports: 17 Imported by: 0

README

die – Process Assassination Tool

die is a powerful CLI tool to find and kill processes by port, name, resource usage, or cgroup. It provides a clean interface, safe dry-runs, audit logging, and watch mode.

Installation

go install github.com/olekukonko/die/cmd/die@latest

Quick Start

Task Command
Kill a node on system die node
Kill all node processes die -a node
Kill process using port 3000 die 3000
Kill process by PID die -pid 1234
Dry-run (preview only) die --dry 3000
List listening ports die -l

Targeting Modes

die automatically detects the target type, or you can specify it explicitly.

Mode Flag Example
Port -p die -p 8080
Name -n die -n nginx
PID -pid die -pid 1234
Cgroup -cgroup die -cgroup /docker/abc
CPU above threshold --cpu-above die --cpu-above 90
Memory above threshold --mem-above die --mem-above 80

Auto-detection rules:

  • Numeric argument → port mode
  • Alphanumeric → name substring search

Kill Options

Flag Description
-f, --force SIGKILL immediately (no graceful termination)
-t, --timeout Grace period before SIGKILL (default: 3s)
-a, --all Kill all matching processes (default: first only)
--tree Kill entire process tree (children then parent)
-r, --regex Use regex for name/cmdline matching

Safety & Control

Flag Description
--dry Preview what would be killed – no actual kill
-i, --interactive Confirm before killing
-q, --quiet Suppress non-essential output
-v, --verbose Show detailed debug information
--audit Write JSON audit log to file

Discovery & Monitoring

Flag Description
-l, --list Show all listening ports with process info
-l --json Same as above, JSON output
-w, --watch Watch mode – kill matching processes repeatedly

Examples

Kill by port with grace period
die -t 5s 3000
Force kill entire tree on port 8080
die -f --tree 8080
Kill all processes matching "chrome" using regex
die -a -r "chrome.*"
Kill by memory usage (above 50%) matching "node"
die --mem-above 50 node
Watch mode: every 5s, kill node processes using > 50% CPU
die -w 5s --cpu-above 50 node
Preview (dry-run) before killing
die --dry -a python
Kill all processes inside a cgroup (containers)
die -cgroup /system.slice/apache2
Audit log for forensics
die --audit /var/log/die.log 3000

Output Examples

Process table preview
🎯 Target: 3000 [mode=port] (2 process(es))
+-------+-------+--------+-------+------+------+---------+--------+-------+
|  PID  | PPID  |  NAME  | USER  | CPU% | MEM% | THREADS | STATUS | PORTS |
+-------+-------+--------+-------+------+------+---------+--------+-------+
|  1234 |   1   | node   | root  | 2.5  | 12.3 |    8    |  S     | 3000  |
|  5678 |  1234 | npm    | root  | 0.0  | 1.2  |    2    |  S     | none  |
+-------+-------+--------+-------+------+------+---------+--------+-------+
Kill result
✓ Killed 2 process(es) in 312ms
Listening ports
🔌 Listening Ports (5 found):
+----------+------+-------+---------+--------------------------+
| PROTOCOL | PORT |  PID  | PROCESS | COMMAND                  |
+----------+------+-------+---------+--------------------------+
| TCP      | 3000 | 1234  | node    | /usr/bin/node app.js     |
| TCP      | 5432 | 5678  | postgres| postgres -D /var/lib/... |
+----------+------+-------+---------+--------------------------+

Audit Log Format

When --audit is enabled, JSON entries are appended:

{
  "timestamp": "2026-03-28T10:30:00Z",
  "action": "kill",
  "target": "3000",
  "mode": "port",
  "pids": [1234, 5678],
  "success": true,
  "user": "oleku",
  "force": false,
  "tree": false,
  "duration_ms": 312,
  "version": "v1.0.0"
}

Build from Source

git clone https://github.com/olekukonko/die.git
cd die
go build -o die ./cmd/die

Set version info:

go build -ldflags="-X github.com/olekukonko/die.Version=v0.1.0 -X github.com/olekukonko/die.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" -o die ./cmd/die

License

MIT License – see LICENSE for details.

Documentation

Index

Constants

View Source 
const (
	DefaultTimeout     = 5 * time.Second
	DefaultParallelism = 0 // resolved at runtime to GOMAXPROCS
	AutoConfirmLimit   = 5 // prompt user when matching more than this many processes
)

Default configuration values

Variables

View Source 
var (
	BuildTime = "unknown"
	GitCommit = "unknown"
)

Build info

View Source 
var Version = "dev"

Version is set at build time via ldflags

Functions

func IsNumeric 

func IsNumeric(s string) bool

Types

type AuditEntry 

type AuditEntry struct {
	Timestamp  time.Time `json:"timestamp"`
	Action     string    `json:"action"`
	Target     string    `json:"target"`
	Mode       string    `json:"mode"`
	PIDs       []int32   `json:"pids"`
	Success    bool      `json:"success"`
	Error      string    `json:"error,omitempty"`
	User       string    `json:"user"`
	DryRun     bool      `json:"dry_run"`
	Force      bool      `json:"force"`
	Tree       bool      `json:"tree"`
	DurationMs int64     `json:"duration_ms"`
	Version    string    `json:"version"`
}

AuditEntry represents a structured audit log entry

type Config 

type Config struct {
	Force       bool
	Timeout     time.Duration
	Verbose     bool
	DryRun      bool // explicit --dry flag; redundant when KillEnabled is false
	KillEnabled bool // must be explicitly true to perform actual kills; false = dry-run always
	Interactive bool
	Quiet       bool
	Tree        bool
	All         bool
	Regex       bool
	AuditLog    string
	Parallelism int
}

Config holds all kill operation parameters

func (Config) IsDryRun 

func (c Config) IsDryRun() bool

IsDryRun reports whether this config will result in a preview-only run. Killing is live only when KillEnabled is explicitly true and DryRun is false.

func (Config) WithDefaults 

func (c Config) WithDefaults() Config

WithDefaults returns a Config with safe zero-value defaults applied.

type KillResult 

type KillResult struct {
	Killed   int
	Failed   int
	Skipped  int
	DryRun   bool // true when the run was preview-only
	Duration time.Duration
	PIDs     []int32
	Error    error
}

KillResult represents the outcome of a kill operation

type KillStats 

type KillStats struct {
	Attempted int32
	Killed    int32
	Failed    int32
	Skipped   int32
}

KillStats tracks operation metrics

type Killer 

type Killer struct {
	// contains filtered or unexported fields
}

Killer executes process termination operations

func NewKiller 

func NewKiller(config Config, logger *ll.Logger) (*Killer, error)

NewKiller creates a new Killer instance

func (*Killer) Close 

func (k *Killer) Close() error

Close cleans up resources

func (*Killer) GetProcesses 

func (k *Killer) GetProcesses(ctx context.Context, target string, mode TargetMode) ([]*ProcessInfo, error)

GetProcesses returns process info without killing (for discovery)

func (*Killer) GetStats 

func (k *Killer) GetStats() KillStats

GetStats returns current statistics

func (*Killer) Kill 

func (k *Killer) Kill(ctx context.Context, target string, mode TargetMode) (*KillResult, error)

Kill performs the kill operation and returns structured results

type PortInfo 

type PortInfo struct {
	Protocol string `json:"protocol"`
	Port     int    `json:"port"`
	PID      int32  `json:"pid"`
	Name     string `json:"name"`
	Cmdline  string `json:"cmdline,omitempty"`
}

PortInfo represents a listening port

func ListPorts 

func ListPorts(ctx context.Context) ([]PortInfo, error)

ListPorts returns all listening ports

type ProcessInfo 

type ProcessInfo struct {
	PID       int32
	PPID      int32
	Name      string
	Cmdline   string
	User      string
	CPU       float64
	Mem       float32
	MemRSS    uint64
	Status    string
	Ports     []int
	Cgroup    string
	Threads   int32
	StartTime int64
	Children  []*ProcessInfo
}

ProcessInfo holds enriched process metadata

type TargetMode 

type TargetMode int

TargetMode defines how to interpret the target 

const (
	ModeAuto TargetMode = iota
	ModePort
	ModeName
	ModePID
	ModeCgroup
	ModeCPUAbove
	ModeMemAbove
)

func (TargetMode) String 

func (m TargetMode) String() string

type Theme 

type Theme struct {
	Primary   *color.Color
	Success   *color.Color
	Error     *color.Color
	Warning   *color.Color
	Info      *color.Color
	Highlight *color.Color
}

Theme defines colors for UI elements

func DefaultTheme 

func DefaultTheme() *Theme

DefaultTheme returns the default color theme

func NoColorTheme 

func NoColorTheme() *Theme

NoColorTheme returns a theme with no colors

type UI 

type UI struct {
	// contains filtered or unexported fields
}

UI handles all user interface rendering

func NewUI 

func NewUI(opts ...UIOption) *UI

NewUI creates a new UI instance

func (*UI) ConfirmKill 

func (u *UI) ConfirmKill(infos []*ProcessInfo, force bool) bool

ConfirmKill prompts for user confirmation before a destructive operation. It accepts the infos slice as returned by Kill (may be a forest in --tree mode) and flattens it internally so totals include all descendants.

func (*UI) Debug 

func (u *UI) Debug(format string, args ...interface{})

Debug prints debug output

func (*UI) PrintError 

func (u *UI) PrintError(format string, args ...interface{})

PrintError prints with error color

func (*UI) PrintInfo 

func (u *UI) PrintInfo(format string, args ...interface{})

PrintInfo prints with info color

func (*UI) PrintPrimary 

func (u *UI) PrintPrimary(format string, args ...interface{})

PrintPrimary prints with primary color

func (*UI) PrintSuccess 

func (u *UI) PrintSuccess(format string, args ...interface{})

PrintSuccess prints with success color

func (*UI) PrintUsage 

func (u *UI) PrintUsage()

PrintUsage prints help text

func (*UI) PrintWarning 

func (u *UI) PrintWarning(format string, args ...interface{})

PrintWarning prints with warning color

func (*UI) Println 

func (u *UI) Println(args ...interface{})

Println prints a plain line

func (*UI) RenderKillResult 

func (u *UI) RenderKillResult(result *KillResult)

RenderKillResult displays kill operation results.

When the run was a dry-run (preview), it prints a clear banner showing what would have been killed and how to proceed. When live, it prints the outcome.

func (*UI) RenderPortsJSON 

func (u *UI) RenderPortsJSON(ports []PortInfo)

RenderPortsJSON outputs ports as JSON

func (*UI) RenderPortsTable 

func (u *UI) RenderPortsTable(ports []PortInfo)

RenderPortsTable displays listening ports

func (*UI) RenderProcessTable 

func (u *UI) RenderProcessTable(infos []*ProcessInfo, target string, mode TargetMode)

RenderProcessTable displays processes in a table

func (*UI) RenderProcessTree 

func (u *UI) RenderProcessTree(infos []*ProcessInfo)

RenderProcessTree displays hierarchical process structure

func (*UI) SetOutput 

func (u *UI) SetOutput(w io.Writer)

SetOutput sets the output writer (useful for testing)

func (*UI) Verbose 

func (u *UI) Verbose(format string, args ...interface{})

Verbose prints verbose output

type UIOption 

type UIOption func(*UI)

UIOption configures the UI

func WithQuiet 

func WithQuiet(quiet bool) UIOption

WithQuiet suppresses non-essential output

func WithTheme 

func WithTheme(theme *Theme) UIOption

WithTheme sets a custom theme

func WithVerbose 

func WithVerbose(verbose bool) UIOption

WithVerbose enables verbose output

type Watcher 

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher continuously monitors and kills processes

func NewWatcher 

func NewWatcher(killer *Killer, config WatcherConfig) *Watcher

NewWatcher creates a new watcher

func (*Watcher) Run 

func (w *Watcher) Run(ctx context.Context, target string, mode TargetMode)

Run starts the watcher loop

type WatcherConfig 

type WatcherConfig struct {
	Interval time.Duration
	OnKill   func(*KillResult)
}

WatcherConfig holds watcher configuration

Source Files

View all Source files

Directories

Path Synopsis
cmd
die command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.