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

proc_cli/
lib.rs
