go-process-cli

# Go Process-Management CLIs > Make Go command-line tools that spawn, supervise, and shut down processes correctly — the part the stdlib makes easy to get subtly wrong. ## When to Apply Reach for this skill when building or reviewing a Go CLI whose job is to *control other processes or concurrent workloads*: a daemon, a process supervisor, a job/worker runner, a deploy or migration tool, a test harness that shells out, or any program that must stop cleanly when an orchestrator says so. It targets **Go 1.22+** on **Unix-like systems** (Linux, macOS); a few rules note where Windows differs. It assumes you already know Go — it only corrects the specific defaults that go wrong in this domain. ## Categories | # | Category | Prefix | What it covers | |---|----------|--------|----------------| | 1 | Signals & Graceful Shutdown | `sig` | Binding a context to SIGINT/SIGTERM; second-signal force-quit | | 2 | Child Processes | `exec` | `os/exec` lifetime, graceful kill, process groups, pipes, exit codes | | 3 | Concurrency & Workloads | `work` | errgroup fan-out, bounded concurrency, goroutine-leak discipline, channel ownership | | 4 | Context Propagation | `ctx` | Explicit context args, `defer cancel()`, cancellable waits | | 5 | Errors & Exit Codes | `err` | `run() error` for deferred cleanup, aggregating failures | | 6 | CLI Framework & Flags | `cli` | stdlib `flag` vs cobra, `ExecuteContext`, `RunE`, subcommand patterns | | 7 | Process State & Supervision | `state` | Liveness probes, atomic PID files, zombie reaping, structured logs | ## Quick Reference The defaults this skill exists to correct: - **`signal.NotifyContext(ctx, SIGINT, SIGTERM)`** — not a channel that only watches Ctrl-C. Orchestrators send SIGTERM. - **`exec.CommandContext` + `cmd.Cancel`/`cmd.WaitDelay`** — plain `CommandContext` SIGKILLs children with no cleanup. - **`Setpgid` + `kill(-pgid)`** — signalling the direct child orphans grandchildren (`sh -c`, `make`, `npm`). - **`cmd.Output()`** for capture — reading a pipe after `Wait()` deadlocks. - **`errgroup.WithContext` + `SetLimit(n)`** — a goroutine per task means a *process* per task: PID/FD exhaustion. - **`ctx` as an argument** — never a struct field; **`defer cancel()`** on every derived context. - **`select { case <-ticker.C: case <-ctx.Done(): }`** — `time.Sleep` makes shutdown wait out the interval. - **`main → run() error → os.Exit(1)`** — `log.Fatal`/`os.Exit` deep in code skip every `defer`. - **`proc.Signal(syscall.Signal(0))`** — `os.FindProcess` always succeeds on Unix; it never proves liveness. - **`os.OpenFile(O_CREATE|O_EXCL)`** for PID files — check-then-create is a race; **`cmd.Wait()`** every child or it zombifies. ## How to Use 1. Identify which category your task falls under (see table above). 2. Read the relevant rule files in `references/` — each is a focused, self-contained pattern naming the wrong default it corrects. 3. Apply the pattern; follow the `Reference` link in each rule for the authoritative source. Rules cross-link (e.g. graceful shutdown ties signals → context → child-process kill → cleanup), so follow the links when a task spans categories. When extending this skill, copy `assets/templates/_template.md`: WHY first, one canonical example with realistic names, a foil only if the wrong way is a genuine trap. ## Source Authority Every rule cites primary sources — the Go standard library reference on pkg.go.dev, the official Go blog (go.dev/blog), and the cobra documentation — chosen because they are maintainer-authored and version-current. No content farms, listicles, or undated tutorials. ## Related Skills - `radical-simplification` — when a supervisor design has accreted accidental complexity. - `unix-cli` / `cli-for-agents` — broader CLI ergonomics beyond process management.