---
id: lib-cli-exit-tools
version: "2.3.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# lib-cli-exit-tools — CLI exit handling helpers: clean signals, exit codes, and error printing

License: permissive · Maintenance: active · Downloads: 138.7K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 138.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

cli exit code handling, signal handling python click, portable sigint sigterm, cli error printing, keyboard interrupt handling, broken pipe graceful, click command exit codes, cli-tools, signal-handling, exit-codes

[View on SkillFed](https://skillfed.io/packages/lib-cli-exit-tools) · [View on PyPI](https://pypi.org/project/lib-cli-exit-tools/)