# 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.
If 100% of your tools are installed by the same package manager that can install tools from a list with desired
versions, then you don't need this tool.
Some useful scenarios:
- Validating a developer's workstation instead of an "install everything" script.
- - Validating a CI environment and failing the build when configuration has drifted
- Validating an end user's environment before running an app where you can't install all the
dependencies for them.
## 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.
Here is an example run.
```text
❯ cli_tool_audit audit
+--------+--------------------------+--------+----------+------------+----------+
| Tool | Found | Parsed | Desired | Status | Modified |
+--------+--------------------------+--------+----------+------------+----------+
| java | openjdk version "17.0.6" | 17.0.6 | >=17.0.6 | Compatible | 01/18/23 |
| make | GNU Make 3.81 | 3.81.0 | >=3.81 | Compatible | 11/24/06 |
| | Copyright ( | | | | |
| python | Python 3.11.1 | 3.11.1 | >=3.11.1 | Compatible | 01/13/24 |
+--------+--------------------------+--------+----------+------------+----------+
```
## 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. It is on the roadmap to support a pipx install for all scenarios.
```shell
pipx install cli-tool-audit
```
## Usage
Generate minimal config for a few tools.
```bash
cli_tool_audit freeze python java make rustc
```
Copy result of above into your pyproject.toml. Edit as needed, especially if you don't want snapshot versioning,
which is probably too strict.
Audit the environment with the current configuration.
```bash
cli_tool_audit audit
```
All commands
```text
❯ cli_tool_audit --help
usage: cli_tool_audit [-h] [-V] [--verbose] [--demo {pipx,venv,npm}]
{interactive,freeze,audit,single,read,create,update,delete} ...
Audit for existence and version number of cli tools.
positional arguments:
{interactive,freeze,audit,single,read,create,update,delete}
Subcommands.
interactive Interactively edit configuration
freeze Freeze the versions of specified tools
audit Audit environment with current configuration
single Audit one tool without configuration file
read Read and list all tool configurations
create Create a new tool configuration
update Update an existing tool configuration
delete Delete a tool configuration
options:
-h, --help show this help message and exit
-V, --version Show program's version number and exit.
--verbose verbose output
--demo {pipx,venv,npm}
Demo for values of npm, pipx or venv
Examples:
# Audit and report using pyproject.toml
cli_tool_audit audit
# Generate config for snapshots
cli_tool_audit freeze python java make rustc
```
Note. If you use the create/update commands and specify the `--version` switch, it must have an equal sign.
Here is how to generate a freeze, a list of current versions by snapshot, for a lis tof tools. All tools will be
check with `--version` unless they are well known.
```shell
cli_tool_audit freeze python java make rustc
```
This is for programmatic usage.
```python
import cli_tool_audit
print(cli_tool_audit.validate(file_path="pyproject.toml"))
```
The configuration file lists the tools you expect how hints on how detect the version.
```toml
[tool.cli-tools]
# Typical example
pipx = { version = ">=1.0.0", version_switch = "--version" }
# Restrict to specific OS
brew = { version = ">=0.1.0", if_os="darwin" }
# Pin to a snapshot of the output of `poetry --version`
poetry = {version = "Poetry (version 1.5.1)", schema="snapshot"}
# Don't attempt to run `notepad --version`, just check if it is on the path
notepad = { schema = "existence" }
# Any version.
vulture = { version = "*" }
# Supports ^ and ~ version ranges.
shellcheck = { version = "^0.8.0" }
# Uses semver's compatibility logic, which is not the same as an exact match.
rustc = { version = "1.67.0" }
```
See [semver3](https://python-semver.readthedocs.io/en/latest/usage/check-compatible-semver-version.html) for
compatibility logic for versions without operators/symbols.
See [poetry](https://python-poetry.org/docs/dependency-specification/) for version range specifiers.
See [stackoverflow](https://stackoverflow.com/a/13874620/33264) for os names.
## Demos
Demos will discover a bunch of executables as installed in the local virtual environment, installed by pipx or
installed by npm. It will then assume that we want the current or any version and run an audit. Since we know these
files already exist, the failures are centered on failing to execute, failing to guess the version switch, failure
to parse the switch or the
tool's version switch returning a version incompatible to what the package manager reports.
```bash
cli_tool_audit --demo=pipx --verbose
cli_tool_audit --demo=venv --verbose
cli_tool_audit --demo=npm --verbose
```
## How does this relate to package managers, e.g. apt, pipx, npm, choco, etc.
Package managers do far more than check for the existence of a tool. They will install it, at the desired version
and make sure that tools and their transitive dependencies are compatible.
What they can't do is verify what other package managers have done.
This captures your desired tools, versions and guarantees you have them by installing them.
```shell
# list everything available on one machine
pip freeze>requirements.txt
# install it on another.
pip install -r requirements.txt
```
This is the same thing, but for windows and .net centric apps.
```shell
choco export requirements.txt
choco install -y requirements.txt
```
There are similar patterns, for apt, brew, npm, and so on.
It would be foolish to try to create a package manager that supports other package managers, so features in that
vein are out of scope.
## Prior Art
- [tool-audit](https://github.com/jstutters/toolaudit)
- [dotnet-tool-list](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-list)
Raw data
{
"_id": null,
"home_page": "https://github.com/matthewdeanmartin/cli_tool_audit",
"name": "cli-tool-audit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cli tooling,version numbers",
"author": "Matthew Martin",
"author_email": "matthewdeanmartin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8e/d7/d232ca2f6bac001d1048385cc3f5cd04718c24e5c23d1bcfeea98bfd0dfc/cli_tool_audit-3.0.1.tar.gz",
"platform": null,
"description": "# cli_tool_audit\n\nVerify that a list of cli tools are available. Like a requirements.txt for cli tools, but without an installer\ncomponent. Intended to work with cli tools regardless to how they were installed, e.g. via pipx, npm, etc.\n\nIf 100% of your tools are installed by the same package manager that can install tools from a list with desired\nversions, then you don't need this tool.\n\nSome useful scenarios:\n\n- Validating a developer's workstation instead of an \"install everything\" script.\n- - Validating a CI environment and failing the build when configuration has drifted\n- Validating an end user's environment before running an app where you can't install all the\n dependencies for them.\n\n## How it works\n\nYou declare a list of cli commands and version ranges.\n\nThe tool will run `tool --version` for each tool and make best efforts to parse the result and compare it to the\ndesired version range.\n\nThe tool then can either output a report with warnings or signal failure if something is missing, the wrong version\nor can't be determined.\n\nThere is no universal method for getting a version number from a CLI tool, nor is there a universal orderable\nversion number system, so the outcome of many check may be limited to an existence check or exact version number check.\n\nHere is an example run.\n\n```text\n\u276f cli_tool_audit audit\n+--------+--------------------------+--------+----------+------------+----------+\n| Tool | Found | Parsed | Desired | Status | Modified |\n+--------+--------------------------+--------+----------+------------+----------+\n| java | openjdk version \"17.0.6\" | 17.0.6 | >=17.0.6 | Compatible | 01/18/23 |\n| make | GNU Make 3.81 | 3.81.0 | >=3.81 | Compatible | 11/24/06 |\n| | Copyright ( | | | | |\n| python | Python 3.11.1 | 3.11.1 | >=3.11.1 | Compatible | 01/13/24 |\n+--------+--------------------------+--------+----------+------------+----------+\n```\n\n## Installation\n\nYou will need to install it to your virtual environment if tools you are looking for are in your virtual environment.\nIf all the tools are global then you can pipx install. It is on the roadmap to support a pipx install for all scenarios.\n\n```shell\npipx install cli-tool-audit\n```\n\n## Usage\n\nGenerate minimal config for a few tools.\n\n```bash\ncli_tool_audit freeze python java make rustc\n```\n\nCopy result of above into your pyproject.toml. Edit as needed, especially if you don't want snapshot versioning,\nwhich is probably too strict.\n\nAudit the environment with the current configuration.\n\n```bash\ncli_tool_audit audit\n```\n\nAll commands\n\n```text\n\u276f cli_tool_audit --help\nusage: cli_tool_audit [-h] [-V] [--verbose] [--demo {pipx,venv,npm}]\n {interactive,freeze,audit,single,read,create,update,delete} ...\n\nAudit for existence and version number of cli tools.\n\npositional arguments:\n {interactive,freeze,audit,single,read,create,update,delete}\n Subcommands.\n interactive Interactively edit configuration\n freeze Freeze the versions of specified tools\n audit Audit environment with current configuration\n single Audit one tool without configuration file\n read Read and list all tool configurations\n create Create a new tool configuration\n update Update an existing tool configuration\n delete Delete a tool configuration\n\noptions:\n -h, --help show this help message and exit\n -V, --version Show program's version number and exit.\n --verbose verbose output\n --demo {pipx,venv,npm}\n Demo for values of npm, pipx or venv\n\n Examples:\n\n # Audit and report using pyproject.toml\n cli_tool_audit audit\n\n # Generate config for snapshots\n cli_tool_audit freeze python java make rustc\n```\n\nNote. If you use the create/update commands and specify the `--version` switch, it must have an equal sign.\n\nHere is how to generate a freeze, a list of current versions by snapshot, for a lis tof tools. All tools will be\ncheck with `--version` unless they are well known.\n\n```shell\ncli_tool_audit freeze python java make rustc\n```\n\nThis is for programmatic usage.\n\n```python\nimport cli_tool_audit\n\nprint(cli_tool_audit.validate(file_path=\"pyproject.toml\"))\n```\n\nThe configuration file lists the tools you expect how hints on how detect the version.\n\n```toml\n[tool.cli-tools]\n# Typical example\npipx = { version = \">=1.0.0\", version_switch = \"--version\" }\n# Restrict to specific OS\nbrew = { version = \">=0.1.0\", if_os=\"darwin\" }\n# Pin to a snapshot of the output of `poetry --version`\npoetry = {version = \"Poetry (version 1.5.1)\", schema=\"snapshot\"}\n# Don't attempt to run `notepad --version`, just check if it is on the path\nnotepad = { schema = \"existence\" }\n# Any version.\nvulture = { version = \"*\" }\n# Supports ^ and ~ version ranges.\nshellcheck = { version = \"^0.8.0\" }\n# Uses semver's compatibility logic, which is not the same as an exact match.\nrustc = { version = \"1.67.0\" }\n```\n\nSee [semver3](https://python-semver.readthedocs.io/en/latest/usage/check-compatible-semver-version.html) for\ncompatibility logic for versions without operators/symbols.\n\nSee [poetry](https://python-poetry.org/docs/dependency-specification/) for version range specifiers.\n\nSee [stackoverflow](https://stackoverflow.com/a/13874620/33264) for os names.\n\n## Demos\n\nDemos will discover a bunch of executables as installed in the local virtual environment, installed by pipx or\ninstalled by npm. It will then assume that we want the current or any version and run an audit. Since we know these\nfiles already exist, the failures are centered on failing to execute, failing to guess the version switch, failure\nto parse the switch or the\ntool's version switch returning a version incompatible to what the package manager reports.\n\n```bash\ncli_tool_audit --demo=pipx --verbose\ncli_tool_audit --demo=venv --verbose\ncli_tool_audit --demo=npm --verbose\n```\n\n## How does this relate to package managers, e.g. apt, pipx, npm, choco, etc.\n\nPackage managers do far more than check for the existence of a tool. They will install it, at the desired version\nand make sure that tools and their transitive dependencies are compatible.\n\nWhat they can't do is verify what other package managers have done.\n\nThis captures your desired tools, versions and guarantees you have them by installing them.\n\n```shell\n# list everything available on one machine\npip freeze>requirements.txt\n# install it on another.\npip install -r requirements.txt\n```\n\nThis is the same thing, but for windows and .net centric apps.\n\n```shell\nchoco export requirements.txt\nchoco install -y requirements.txt\n```\n\nThere are similar patterns, for apt, brew, npm, and so on.\n\nIt would be foolish to try to create a package manager that supports other package managers, so features in that\nvein are out of scope.\n\n## Prior Art\n\n- [tool-audit](https://github.com/jstutters/toolaudit)\n- [dotnet-tool-list](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-list)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Audit for existence and version number of cli tools.",
"version": "3.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/matthewdeanmartin/cli_tool_audit/issues",
"Change Log": "https://github.com/matthewdeanmartin/cli_tool_audit/blob/main/CHANGELOG.md",
"Documentation": "https://matthewdeanmartin.github.io/cli_tool_audit/cli_tool_audit/index.html",
"Homepage": "https://github.com/matthewdeanmartin/cli_tool_audit",
"Repository": "https://github.com/matthewdeanmartin/cli_tool_audit"
},
"split_keywords": [
"cli tooling",
"version numbers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "287bddc33c831591ef22399fd8d5631482448b8bb43496ad2fa32dae32620a9e",
"md5": "65bc8b5617b48ee3b2039a7ec277f91e",
"sha256": "941ae3647c2e94df7e15dee3b0301683088c0024136d1fff002812d5af03476c"
},
"downloads": -1,
"filename": "cli_tool_audit-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65bc8b5617b48ee3b2039a7ec277f91e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 36237,
"upload_time": "2024-01-20T16:18:39",
"upload_time_iso_8601": "2024-01-20T16:18:39.648080Z",
"url": "https://files.pythonhosted.org/packages/28/7b/ddc33c831591ef22399fd8d5631482448b8bb43496ad2fa32dae32620a9e/cli_tool_audit-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ed7d232ca2f6bac001d1048385cc3f5cd04718c24e5c23d1bcfeea98bfd0dfc",
"md5": "30c4329f0700c112d3bdc65766d63bb7",
"sha256": "701b10fe3b234cc5bce9f9bf511003c02a15bbdf6fe87fed5b38cbceba988518"
},
"downloads": -1,
"filename": "cli_tool_audit-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "30c4329f0700c112d3bdc65766d63bb7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29708,
"upload_time": "2024-01-20T16:18:42",
"upload_time_iso_8601": "2024-01-20T16:18:42.815572Z",
"url": "https://files.pythonhosted.org/packages/8e/d7/d232ca2f6bac001d1048385cc3f5cd04718c24e5c23d1bcfeea98bfd0dfc/cli_tool_audit-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-20 16:18:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matthewdeanmartin",
"github_project": "cli_tool_audit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "cli-tool-audit"
}
JSON
