cli-base-utilities

Helpers to build a CLI program and some useful tools for CLI programs.

pip install cli-base-utilities

GitHub suspended me!

Important notice:

GitHub suspended my account sometime in late August 2026 ! There was no warning beforehand, nor any explanation of the reasons afterwards. Since then, I have had no access or control over my data on GitHub.

All my projects and everything about me have completely disappeared. Everything just results in a 404 "Not Found" error page.

A support request still hasn't been answered, even after several weeks (apart from a confirmation that the request was received).

For that reason, I have been looking for a new home for all my OpenSource projects. (Or rather, I am in the process of republishing all my projects elsewhere.)

Now you can find my on these places:

• https://codeberg.org/jedie
• Radicle: https://radicle.network/nodes/iris.radicle.network/users/did%3Akey%3Az6MkfvNUuBCwRtNZwANEAGd4vaTzyuZXMKfiSyjoBALga934

That is why there will probably be a lot of broken links pointing to my GitHub account for quite some time!

Features

Some of the features are:

• run_pip_audit() to run pip-audit with configuration from pyproject.toml

TODO: Document all features here ;)

start development

~$ git clone https://codeberg.org/jedie/cli-base-utilities.git
~$ cd cli-base-utilities
~/cli-base-utilities$ ./dev-cli.py --help

dev CLI

usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,shell-completion,test,update,update-readme-history,update-test-snapshot-files,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help     show this help message and exit                                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • coverage   Run tests and show coverage report.                                     │
│   • install    Install requirements and 'cli_base' via pip as editable.                │
│   • lint       Check/fix code style by run: "ruff check --fix"                         │
│   • mypy       Run Mypy (configured in pyproject.toml)                                 │
│   • nox        Run nox                                                                 │
│   • pip-audit  Run pip-audit check against current requirements files                  │
│   • publish    Build and upload this project to PyPi                                   │
│   • shell-completion                                                                   │
│                Setup shell completion for this CLI (Currently only for bash and zsh)   │
│   • test       Run unittests                                                           │
│   • update     Update dependencies (uv.lock) and git pre-commit hooks                  │
│   • update-readme-history                                                              │
│                Update project history base on git commits/tags in README.md            │
│                                                                                        │
│                Will be exited with 1 if the README.md was updated otherwise with 0.    │
│                                                                                        │
│                Also, callable via e.g.:                                                │
│                    python -m cli_base update-readme-history -v                         │
│   • update-test-snapshot-files                                                         │
│                Update all test snapshot files (by remove and recreate all snapshot     │
│                files)                                                                  │
│   • version    Print version and exit                                                  │
╰────────────────────────────────────────────────────────────────────────────────────────╯

app CLI

usage: cli-base-utilities [-h] {shell-completion,update-readme-history,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help   show this help message and exit                                           │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • shell-completion                                                                   │
│              Setup shell completion for this CLI (Currently only for bash and zsh)     │
│   • update-readme-history                                                              │
│              Update project history base on git commits/tags in README.md              │
│                                                                                        │
│              Will always exist with exit code 0 because changed README is auto added   │
│              to git.                                                                   │
│                                                                                        │
│              Also, callable via e.g.:                                                  │
│                  python -m cli_base update-readme-history -v                           │
│   • version  Print version and exit                                                    │
╰────────────────────────────────────────────────────────────────────────────────────────╯

DEMO app CLI

usage: ./demo-cli.py [-h] {demo-endless-loop,demo-verbose-check-output-error,edit-settings,print-settings,systemd-debug,systemd-logs,systemd-remove,systemd-setup,systemd-status,systemd-stop,version}



╭─ options ──────────────────────────────────────────────────────────────────────────────╮
│ -h, --help         show this help message and exit                                     │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                             │
│   • demo-endless-loop                                                                  │
│                    Just a useless example command, used in systemd DEMO: It just print │
│                    some information in a endless loop.                                 │
│   • demo-verbose-check-output-error                                                    │
│                    DEMO for a error calling                                            │
│                    cli_base.cli_tools.subprocess_utils.verbose_check_output()          │
│   • edit-settings  Edit the settings file. On first call: Create the default one.      │
│   • print-settings                                                                     │
│                    Display (anonymized) MQTT server username and password              │
│   • systemd-debug  Print Systemd service template + context + rendered file content.   │
│   • systemd-logs   List and follow logs of systemd service. (May need sudo)            │
│   • systemd-remove                                                                     │
│                    Write Systemd service file, enable it and (re-)start the service.   │
│                    (May need sudo)                                                     │
│   • systemd-setup  Write Systemd service file, enable it and (re-)start the service.   │
│                    (May need sudo)                                                     │
│   • systemd-status                                                                     │
│                    Display status of systemd service. (May need sudo)                  │
│   • systemd-stop   Stops the systemd service. (May need sudo)                          │
│   • version        Print version and exit                                              │
╰────────────────────────────────────────────────────────────────────────────────────────╯

Generate project history base on git commits/tags

Add a test case similar to cli_base/tests/test_readme_history.py into your project. Add the needed start/end comments into your README.

To make a new release, do this:

• Increase your project version number
• Run tests to update the README
• commit the changes
• Create release

It's recommended to use git hookd (via pre-commit) to update the README. For this, add in your pyproject.toml:

[tool.cli_base]
version_module_name = "<your_package>" # Must provide the `__version__` attribute

Copy&paste .pre-commit-config.yaml into your project.

Add pre-commit to your requirements and install the git hooks by:

.venv/bin/pre-commit install
.venv/bin/pre-commit autoupdate

Update pre-commit hooks

Update version in .pre-commit-config.yaml and make a release.

The Problem: The hooks are broken, if the "new" version is not tagged yet. To create a release, it's possible to use all git commands (commit, push, etc) with --no-verify to skip the hooks.

It's easier to temporarily uninstall the hooks, create the release and install the hooks again, e.g.:

.../cli-base-utilities$ .venv/bin/pre-commit uninstall
# ...bump version, commit, push, merge... create release...
.../cli-base-utilities$ .venv/bin/pre-commit install

Backwards-incompatible changes

v0.14 - Switch from pip-tools to uv

cli_base.run_pip_audit.run_pip_audit() works now with uv base projects instead of pip-tools.

history

• v0.32.0
  • 2026-09-11 - GitHub -> Codeberg + Radicle
• v0.31.1
  • 2026-08-22 - Fix "pip-audit" command
  • 2026-08-22 - apply projects upgrades
  • 2026-06-16 - Enhance README utils
  • 2026-06-16 - remove lock file from git
• v0.30.0
  • 2026-04-11 - Enhance print_version(): Add optional project_name and clean module name
• v0.29.2
  • 2026-04-10 - Bugfix fallback to default Path instance
  • 2026-04-10 - update requirements