lib-cli-exit-tools

What it is and what it does

lib_cli_exit_tools wraps Click commands to handle platform-specific signal translation, exception-to-exit-code mapping, and error output formatting. It solves the problem of CLI applications behaving inconsistently across shells, CI/CD systems, and operating systems by automatically converting Python exceptions (FileNotFoundError, PermissionError, KeyboardInterrupt) into standard exit codes, translating SIGINT/SIGTERM/SIGBREAK into structured exceptions, and gracefully handling BrokenPipeError when output is piped to truncating tools.

The library is built on rich-click and provides two main entry points: run_cli() for wrapping a single command with signal handling and exit-code translation, and cli_session() as a context manager for centralised configuration and testing. It supports optional traceback display via --traceback, custom signal handlers, and subprocess stdout/stderr capture. Configuration is test-friendly and requires no boilerplate beyond wrapping your Click command.

Use it for:

• Wrap a Click command to ensure it returns exit code 130 on Ctrl+C and 141 on broken pipe, matching shell conventions.
• Build a multi-command CLI that toggles full Rich-formatted tracebacks via --traceback without modifying command code.
• Handle SIGTERM gracefully in containerised applications by translating it to a deterministic exit code.
• Test error paths by raising exceptions and verifying the correct exit code is returned without manual bookkeeping.
• Pipe CLI output to head or other truncating tools without noisy tracebacks when BrokenPipeError occurs.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides portable signal handling, exception-to-exit-code mapping, and clean error printing for Click CLI applications across platforms.

Yes. The package is actively maintained, has low install friction, carries no security vulnerabilities, and solves a real problem for CLI developers: portable signal handling and consistent exit codes across platforms. Use it whenever you wrap a Click command that needs to behave correctly in shell pipelines and CI/CD systems.

Install

lib-cli-exit-tools on PyPI

pip install lib-cli-exit-tools

uv add lib-cli-exit-tools

poetry add lib-cli-exit-tools

Installing lib-cli-exit-tools

Before you install

Low friction: pure Python wheel with a single runtime dependency (rich-click). Active maintenance with recent releases. Supports Python 3.10 through 3.14.

License in practice

MIT license is permissive; you may use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install lib-cli-exit-tools

from lib_cli_exit_tools import run_cli
import rich_click as click

@click.command()
def hello():
    click.echo("Hello")

if __name__ == "__main__":
    raise SystemExit(run_cli(hello))

Requires Python 3.10 or newer.

Verify before relying

• Whether the library's exit-code mappings (e.g., FileNotFoundError → 2, PermissionError → 13) match all target platforms' conventions.
• Performance impact of signal installation and exception handling in high-throughput CLI scenarios.

Package facts

Evidence: lib_cli_exit_tools-2.3.4-py3-none-any.whl

Keywords: cli, click, errors, exit, signals

Tags

More Software Development packages