Pronounced /ˈtuːlər/ (tool-er)

ToolR is a tool similar to invoke and the next generation of python-tools-scripts.

The goal is to quickly enable projects to write a Python module under the project's tools/ sub-directory and it automatically becomes a sub command to the toolr CLI.

ToolR automatically discovers and registers commands from your project's tools/ directory, making it easy to organize and maintain your project's CLI tools.

Define commands using simple Python functions with type hints. ToolR automatically generates argument parsing based on your function signatures.

Organize commands into logical groups and subgroups using dot notation, providing a clean and intuitive CLI structure.

Built-in support for rich text formatting and automatic help generation from docstrings and type annotations.

Extend ToolR's functionality by installing packages that provide additional commands through Python entry points.

1. Install ToolR:

   python -m pip install toolr

2. Create a tools package in your project root:

   mkdir tools
   touch tools/__init__.py

3. Write your first command in tools/example.py:

   from toolr import Context, command_group
   
   group = command_group("example", "Example Commands", "Example command group")
   
   @group.command
   def hello(ctx: Context, name: str = "World"):
       """Say hello to someone.
   
       Args:
         name: The name to say hello to.
       """
       ctx.print(f"Hello, {name}!")

4. Run your command:

   toolr example hello --name Alice

ToolR supports 3rd-party commands from installable Python packages. Create packages that extend ToolR's functionality by defining commands and registering them as entry points.

See the Advanced Topics section in the documentation for detailed information about creating 3rd-party command packages.