Metadata-Version: 2.1
Name: cli_tool_audit
Version: 1.0.1
Summary: Audit for existance and vesion number of cli tools.
Home-page: https://github.com/matthewdeanmartin/cli_tool_audit
License: MIT
Keywords: cli tooling,version numbers
Author: Matthew Martin
Author-email: matthewdeanmartin@gmail.com
Requires-Python: >=3.8
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: prettytable (>=3.9.0)
Requires-Dist: semver (>=3.0.2)
Requires-Dist: whichcraft (>=0.6.1)
Project-URL: Bug Tracker, https://github.com/matthewdeanmartin/cli_tool_audit/issues
Project-URL: Change Log, https://github.com/matthewdeanmartin/cli_tool_audit/blob/main/CHANGES.md
Project-URL: Documentation, https://github.com/matthewdeanmartin/cli_tool_audit
Project-URL: Repository, https://github.com/matthewdeanmartin/cli_tool_audit
Description-Content-Type: text/markdown

# cli_tool_audit
Verify that a list of cli tools are available. Like a requirements.txt for cli tools, but without an installer 
component. Intended to work with cli tools regardless to how they were installed, e.g. via pipx, npm, etc.

## How it works
You declare a list of cli commands and version ranges.

The tool will run `tool --version` for each tool and make best efforts to parse the result and compare it to the 
desired version range.

The tool then can either output a report with warnings or signal failure if something is missing, the wrong version 
or can't be determined.

There is no universal method for getting a version number from a CLI tool, nor is there a universal orderable 
version number system, so the outcome of many check may be limited to an existence check or exact version number check.

## Installation

You will need to install it to your virtual environment if tools you are looking for are in your virtual environment.
If all the tools are global then you can pipx install.

```shell
pipx install cli-tool-audit
```

## Usage

CLI usage
```shell
cli-tool-audit [--config=pyproject.toml]
```

```python
import cli_tool_audit

print(cli_tool_audit.validate(config="pyproject.toml"))
```

The configuration file lists the tools you expect how hints on how detect the version.
```toml
[tool.cli-tools]
pipx = { description = "Python package installer for applications", version = "^1.0.0", version_switch = "--version" }
mypy = { version = "^1.0.0", version_switch = "--version" }
pylint = {  version = "^1.0.0", version_switch = "--version" }
black = {  version = "^1.0.0", version_switch = "--version" }
pygount = { version = "^1.0.0", version_switch = "--version" }
ruff = { version = "^1.0.0", version_switch = "--version" }
```

## Testing

You can check that all pipx installed tools are compatible with the package-declared version. Sometimes they are not,
sometimes the tool fails to run, sometimes the tool doesn't support any known `--version` switch.

```bash
python -m cli_tool_audit.pipx_stress_test
```

You can check that all tools in the current virtual environment are at least version 0.0.0.

```bash
python -m cli_tool_audit.venv_stress_test
```

Just running the file will check anything configured in `pyproject.toml`

```bash
python -m cli_tool_audit
```

## Prior Art

If your cli tools are all installed by a package manager, you could use the package manager's manifest, e.g. 
pyproject.toml for poetry. If your CLI tools are installed by a variety of package managers, or not installed but 
just copied to a location on the PATH, then this may not help.

- [tool-audit](https://github.com/jstutters/toolaudit)
- [dotnet-tool-list](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-list)

