supi-cli-1.0.1 is not a library.

supi - Simple Process Supervisor

A lightweight CLI tool for supervising and managing arbitrary processes with easy restart capabilities.

Overview

supi is a simple process supervisor that spawns and manages child processes. It allows you to restart processes on-demand using hotkeys or Unix signals, making it ideal for development workflows where you need to frequently restart services.

Features

Process Management: Spawns and supervises arbitrary commands
Signal Handling: Responds to Unix signals for graceful shutdown and restart
Output Forwarding: Forwards child process stdout and stderr in real-time
Interactive Restart: Press a key to instantly restart your process
Flexible Configuration: Customize restart signals and hotkeys

Why?

I made myself a zellij (a rust terminal multiplexer, like tmux) layout with various panels but most importantly with a panel on the left for a npm run build:app && npm run dev command. This command builds the app and then starts the development server. I wanted to be able to restart the development server with a hotkey or signal. Since the app is really big with a lot of components, I don't want to rebuild the app everytime I make a change. If you look for this behavior, you might enjoy watchexec-cli.

Core Behavior

Output Forwarding

All child process output (stdout and stderr) is forwarded as raw as possible
No buffering or modification of child output
Input is NOT forwarded to the child process by default (an "interactive" mode might be added in the future)

Signal Handling

Restart Signal: SIGUSR1 (default) - Restarts the child process
Stop Signals: Responds to standard termination signals (SIGTERM, SIGINT, etc.)
Gracefully terminates child process before exiting

Interactive Control

Press the r key (default) to restart the child process
Terminal must be focused for hotkey to work (not a global hotkey)

Child Process Exit

By default, supi continues running even if the child process exits
Allows you to restart the process using signals or hotkeys
Can be configured to exit when child exits using --stop-on-child-exit

Usage

# Basic usage
supi <command> [args...]

# Example: Run a development server
supi npm run dev

# Example: Run a Rust application
supi cargo run

# Stop supi when child exits
supi --stop-on-child-exit ./my-script.sh

Command Line Options

`--stop-on-child-exit`

Default: false

When enabled, supi will exit if the child process exits. When disabled (default), supi continues running and you can restart the process using the restart signal or hotkey.

supi --stop-on-child-exit npm start

`--restart-signal <SIGNAL>`

Default: SIGUSR1

Specifies which Unix signal should trigger a process restart.

supi --restart-signal SIGUSR2 ./my-app

`--restart-hotkey <KEY>`

Default: r

Specifies which key should trigger a process restart when pressed. Only works when the terminal running supi is focused.

supi --restart-hotkey R ./my-app

`--restart-debounce-ms <MILLISECONDS>`

Default: 1000 (1 second)

Sets the debounce time for restart requests in milliseconds. This prevents accidental rapid restarts from multiple hotkey presses or signals. Set to 0 to disable debouncing.

# Prevent restarts within 3 seconds of each other
supi --restart-debounce-ms 3000 npm run dev

# Disable debouncing (allow instant restarts)
supi --restart-debounce-ms 0 ./my-app

`--log-color <COLOR>`

Default: yellow

Sets the color for supervisor log messages. Supported colors: yellow, red, green, blue, cyan, magenta, white, none.

supi --log-color cyan npm run dev

`--info-color <COLOR>`

Default: green

Sets the color for informational messages (like hotkey prompts). Supported colors: yellow, red, green, blue, cyan, magenta, white, none.

supi --info-color blue npm run dev

`--silent`

Default: false

Suppresses all supervisor output. Child process output remains visible. Useful when you want to see only the output from your managed process.

supi --silent npm run dev

Example Workflows

Development Server with Quick Restart

# Start your dev server, press 'r' to restart anytime
supi npm run dev

Production-like Supervisor

# Exit when the main process exits
supi --stop-on-child-exit ./production-app

Custom Signal Integration

# Use SIGUSR2 for restart
supi --restart-signal SIGUSR2 python app.py

# In another terminal, send restart signal
kill -SIGUSR2 $(pgrep -f "supi python")

Installation

From crates.io (Recommended)

cargo install --locked supi-cli

From Source

git clone https://github.com/bjesuiter/supi-cli
cd supi-cli
cargo install --path .

Requirements

Unix-like operating system (Linux, macOS)
Rust 1.86 or higher (for building from source)

Distribution Targets

Pre-built binaries might be provided later for:

aarch64-apple-darwin - Apple Silicon macOS
x86_64-unknown-linux-gnu - Linux with glibc
x86_64-unknown-linux-musl - Linux static binary (portable)

Right now the main way to get supi is to install it from crates.io.

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Publishing Information

For Maintainers

Publishing a New Version to crates.io

Update version in Cargo.toml:
```
version = "0.3.0"  # Bump from 0.2.0
```
Update CHANGELOG.md with changes in the new version

Test everything:

cargo clean
cargo build --release
cargo test --release
cargo package --list  # Check included files
cargo publish --dry-run  # Test publication

Commit changes:

git add Cargo.toml CHANGELOG.md
git commit -m "Bump version to 0.3.0"
git push

Publish to crates.io:
```
cargo publish
```
Tag the release:
```
git tag v0.3.0
git push origin v0.3.0
```

Verify installation:

cargo install --locked supi-cli --force
supi --version

Important Notes

Can't unpublish: Published versions are permanent (can only be yanked)
Semantic versioning: Follow semver for version numbers
Cargo.lock: Users will install with --locked for reproducible builds
Test thoroughly: Always run full test suite before publishing

Development Information

This repository uses bonnie/bx cli as a task runner. bx is a custom fork of bonnie with a shorter CLI name for convenience.

See bonnie.toml for all available commands.

Future Considerations and Improvements

The following features and enhancements are being considered for future releases:

Phase 7: Polish & Distribution

Comprehensive error handling: Improve error messages and edge case handling
Enhanced status messages: Add more informative status messages throughout the lifecycle
Cross-platform testing: Thorough testing on various Linux distributions and macOS versions
CI/CD pipeline: Set up automated cross-compilation for multiple platforms
Pre-built binaries: Provide release binaries for common target platforms
Documentation improvements: Expand examples and use case documentation
Examples directory: Add practical examples for common workflows

Phase 8: Vim-Style Interactive Mode (Future)

Add an optional interactive mode that allows switching between normal mode (hotkeys active) and insert mode (stdin forwarded to child):

Normal Mode: Current behavior - hotkeys active, no stdin forwarding
Insert Mode: Forward stdin to child process, press ESC to return to normal
Mode Indicator: Visual display of current mode (like vim)
Smooth Transitions: Mode switching without disrupting child process

Use cases:

Interactive shells or REPLs that need input
Applications requiring both monitoring and interaction
Development workflows mixing observation and interaction

Phase 9: Optional TUI Mode (Future Enhancement)

An optional terminal UI mode (--tui flag) for enhanced monitoring:

Status Bar: Process state, uptime, restart count
Scrollable Output: Buffer for reviewing child stdout/stderr
Help Panel: Available hotkeys and commands
Visual Indicators: Process state visualization (running/stopped/restarting)
Customizable Refresh: Configurable UI update rate

This would be opt-in, preserving the simple passthrough behavior by default.

Other Potential Features (Out of Scope)

Features that might be explored much later:

Configuration file support: TOML/KDL config files
Windows support: Cross-platform signal equivalents
Process statistics: Restart counter, uptime tracking, resource usage

supi-cli 1.0.1