proc_cli/
lib.rs

1#![warn(missing_docs)]
2//! # proc - Semantic Process Management CLI
3//!
4//! Semantic CLI tool for process management. Target by port, PID, name or path.
5//!
6//! ## Features
7//!
8//! - **Unified Targets**: `:port`, `PID`, and `name` work the same everywhere
9//! - **Multi-Target**: `proc kill :3000 :8080 node` - separate arguments (comma-separated targets still work, but are deprecated)
10//! - **Query Language**: `proc by node --in .` - composable filters
11//! - **Working Directory**: See which project folder a process is running from
12//! - **Terminal-Adaptive Tables**: Tables adjust to terminal width automatically
13//! - **Consistent Filters**: `--in`, `--by`, `--min-uptime`, `--parent`, `--range`, `--sort`, `--limit`
14//! - **JSON Output**: `--json` on every command except `completions` and `manpage` — one `{action, success, ...}` document per run (`watch` streams one per refresh), and `success: false` always exits non-zero
15//! - **Custom Signals**: `proc stop worker --signal INT` - send a different first signal; whatever is still running after `--timeout` is force-killed
16//! - **Real-Time Monitoring**: `proc watch` / `proc top` - live process table (TUI on a terminal, NDJSON stream with `--json`)
17//! - **Process Waiting**: `proc wait node` - block until process(es) exit (pipe-friendly)
18//! - **Freeze/Thaw**: `proc freeze` / `proc thaw` - pause and resume by port, PID, or name
19//! - **Port Freeing**: `proc free :3000` - kill and verify port is available
20//! - **Ancestry Tracing**: `proc why :3000` - trace why a port is busy
21//! - **Orphan Detection**: `proc orphans` - find abandoned child processes
22//! - **File Lookup**: `proc for ./server` - find by file path
23//! - **Cross-Platform**: macOS, Linux, and Windows
24//! - **Shell Completions**: bash, zsh, fish, elvish, PowerShell via `proc completions`
25//! - **Man Pages**: `proc manpage` generates the top-level page (commands and examples; per-command flags are in `proc <command> --help`)
26//!
27//! ## Quick Start
28//!
29//! ```bash
30//! # What's on port 3000?
31//! proc on :3000
32//!
33//! # What has this file open, or runs it as its program?
34//! proc for ./server
35//!
36//! # Kill multiple targets
37//! proc kill :3000 :8080 node
38//!
39//! # Node processes in current directory
40//! proc by node --in .
41//!
42//! # Preview before killing
43//! proc kill node --dry-run
44//!
45//! # Kill only node processes in current directory
46//! proc kill node --in .
47//!
48//! # Watch processes in real-time
49//! proc watch node --in .
50//!
51//! # Wait for a process to finish
52//! proc wait node --timeout 3600
53//!
54//! # Free a port (kill + verify available)
55//! proc free :3000
56//!
57//! # Why is this port busy?
58//! proc why :3000
59//!
60//! # Pause and resume
61//! proc freeze node && proc thaw node
62//!
63//! # Ask politely with SIGINT instead of SIGTERM
64//! proc stop worker --signal INT
65//!
66//! # JSON output for scripting/LLMs
67//! proc by node --json
68//!
69//! # Generate shell completions
70//! proc completions zsh > ~/.zsh/completions/_proc
71//! ```
72//!
73//! ## Commands
74//!
75//! **Discovery**: `on`, `for`, `by`, `in`, `list`, `info`, `ports`, `tree`, `stuck`, `why`, `orphans`
76//!
77//! **Lifecycle**: `kill`, `stop`, `unstick`, `freeze`, `thaw`, `free`
78//!
79//! **Monitoring**: `watch` (interactive TUI, or NDJSON with `--json`), `wait` (blocking, pipe-friendly)
80//!
81//! **Tooling**: `completions`, `manpage`
82//!
83//! ## Exit Codes
84//!
85//! `0` success, `1` error or partial failure (including `wait` timeouts),
86//! `2` not found, `3` permission denied, `4` invalid input (including unknown flags),
87//! an action this OS does not support, or a command that changes processes run
88//! without `--yes` where nobody can confirm (`--json`, or no terminal): nothing
89//! was changed. A signal that ends proc while `watch` has the screen or a
90//! prompt is waiting (SIGINT, SIGTERM, SIGHUP, SIGQUIT) puts the terminal back,
91//! then ends proc by that signal, so a shell shows 128 plus its number.
92
93pub mod cli;
94pub mod commands;
95pub mod core;
96pub mod error;
97pub mod ui;
98pub mod version;
99
100#[cfg(test)]
101mod test_support;
102
103pub use error::{ProcError, Result};
104
105/// Library version: the Cargo version for a release, and for any other build
106/// from git the version with the commit named (see [`version`])
107pub const VERSION: &str = env!("PROC_VERSION");
proc_cli/lib.rs

proc_cli/
lib.rs
