Skip to main content

ToolR - AI Generated Logo

In-project CLI tooling, with a Rust front-end.

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

ToolR is a Python task runner that boots in milliseconds because the front-end is a Rust binary. Python only runs when you invoke a command, inside a per-repo uv-managed venv.

Tool runner -h steady-state First run Second run
toolr 10.4 ms 277.0 ms 21.8 ms
doit 83.4 ms 143.0 ms 88.9 ms
invoke 84.6 ms 101.7 ms 77.4 ms
nox 91.8 ms 395.9 ms 115.3 ms
duty 166.4 ms 188.5 ms 252.4 ms
python-tools-scripts 252.2 ms 340.3 ms 189.0 ms

<tool> -h, 20 runs, steady-state = mean of last 18. Measured on Apple M3 Pro / macOS 26.5 / arm64. Reproduce locally with python3 scripts/bench.py (stdlib-only; emits the table above to stdout).

Why ToolR

  • Sub-millisecond discovery. The CLI is a Rust binary. --help and Tab completion read a cached static manifest; Python never boots for non-execute paths.
  • No system-Python dependency. Toolr resolves a per-repo Python venv via uv on first invocation. The host OS doesn't need Python at all to install toolr — it's a single static binary.
  • Write Python, not framework boilerplate. Drop a tools/*.py file with a command_group and a @command decorator. Type hints become CLI arguments; Google-style docstrings become --help text.
  • First-class third-party command packages. Plugins ship a static toolr-manifest.json inside the wheel. Discovery is a glob + JSON parse; no Python import to find them.
  • Signed releases. Every release archive ships with a SLSA build-provenance attestation. The install scripts verify it by default (requires the gh CLI); pass --verify-attestation=skip to bypass, accepting the supply-chain risk.

Two wheels, two roles

Package What it is Where it lives
toolr The Rust CLI binary you run from the shell. On $PATH, installed once.
toolr-py The Python runtime your tools/*.py import. In your tools/pyproject.toml.

Most projects want both: the CLI installed globally, toolr-py declared in the per-repo tools/pyproject.toml so from toolr import Context, command_group works when your commands run.

Install

Five first-class install paths.

mise

mise use aqua:s0undt3ch/ToolR@latest

Pulls toolr from the aqua registry via mise's built-in aqua backend — no plugin to register. For projects that already pin tool versions via .mise.toml, toolr's version becomes part of your project's reproducible tool set. See docs/installation/mise/.

pip

pip install toolr   # Rust CLI binary

This installs the toolr binary into whatever venv pip is pointing at. Do not pip install toolr-py into that same venv — toolr-py is the Python runtime your tools/*.py files import, and it belongs in the per-repo tools venv that toolr project init scaffolds for you (where it's declared in tools/pyproject.toml and materialised via uv sync). See "Two wheels, two roles" above for the split.

curl | sh (Linux + macOS)

curl -fsSL https://raw.githubusercontent.com/s0undt3ch/ToolR/main/installation/install.sh | sh

Verifies the SLSA attestation by default (requires the gh CLI; pass --verify-attestation=skip to bypass). Pin a version with sh -s -- --version X.Y.Z. Custom prefix: sh -s -- --prefix /opt/toolr/bin.

PowerShell (Windows)

irm https://raw.githubusercontent.com/s0undt3ch/ToolR/main/installation/install.ps1 | iex

GitHub release archives

Download toolr-<version>-<target-triple>.tar.gz (or .zip for Windows) from https://github.com/s0undt3ch/ToolR/releases, verify the .sha256 sibling and the SLSA attestation, drop the binary on $PATH. Useful in locked-down environments that audit binaries before allowing them on a machine.

Scaffold your repo

After the binary is on $PATH:

toolr project init                  # writes tools/{pyproject.toml,.gitignore,example.py}
toolr example hello                 # run the generated example
toolr self completion install bash  # or zsh / fish

The full install matrix (per-OS notes, attestation flags, prefix overrides) lives in docs/installation/.

What you write

# tools/example.py
"""Example commands."""
from toolr import Context, command_group

example = command_group("example", title="Example", description=__doc__)


@example.command
def hello(ctx: Context, name: str = "world") -> None:
    """Say hello to <name>.

    Args:
        name: who to greet.
    """
    ctx.print(f"Hello, {name}!")
$ toolr example hello --name Pedro
Hello, Pedro!

toolr project init writes a richer four-command starter than this two-liner — open it and edit, or delete it and start from scratch.

Where to go next

Project status

ToolR is pre-1.0. The on-disk manifest is versioned (schema_version in tools/.toolr-manifest.json); the binary refuses to load a higher version than it understands. The public Python surface is toolr.__all__; anything not listed there is implementation detail. Backwards-incompatible changes will be explicit in the changelog (generated by git-cliff on release).

Contributing

See CONTRIBUTING.md.

License

Apache-2.0.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

toolr_py-0.26.1.tar.gz (232.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

toolr_py-0.26.1-cp311-abi3-win_amd64.whl (982.8 kB view details)

Uploaded CPython 3.11+Windows x86-64

toolr_py-0.26.1-cp311-abi3-musllinux_1_2_x86_64.whl (476.5 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

toolr_py-0.26.1-cp311-abi3-musllinux_1_2_aarch64.whl (447.8 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

toolr_py-0.26.1-cp311-abi3-manylinux_2_28_x86_64.whl (536.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ x86-64

toolr_py-0.26.1-cp311-abi3-manylinux_2_28_aarch64.whl (383.2 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

toolr_py-0.26.1-cp311-abi3-macosx_11_0_x86_64.whl (791.9 kB view details)

Uploaded CPython 3.11+macOS 11.0+ x86-64

toolr_py-0.26.1-cp311-abi3-macosx_11_0_arm64.whl (673.0 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file toolr_py-0.26.1.tar.gz.

File metadata

  • Download URL: toolr_py-0.26.1.tar.gz
  • Upload date:
  • Size: 232.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for toolr_py-0.26.1.tar.gz
Algorithm Hash digest
SHA256 27997d786763e890252afe2109d4e4e6bf8749081252b8c6ce46090fdbf49c89
MD5 29626d666bf3830393b730109742070d
BLAKE2b-256 001d62cca707626f5f19292280e9dd330ded60b614d5891d69e53ac2f29021ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1.tar.gz:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-win_amd64.whl.

File metadata

  • Download URL: toolr_py-0.26.1-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 982.8 kB
  • Tags: CPython 3.11+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 609ee9356cf1093bd71ab921cc381b24b177d1e74cd566cffcec1b45fbf3553d
MD5 decdcc9814d0a1cf42eb912d50918204
BLAKE2b-256 88ed8445b848502e2bd4e929853f01c090c8d9d4d8ff7e3d0d26454b3c55fdde

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-win_amd64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 f940ce9f2a2daef9ca01bb9ccabfa31cff801aeed36268a2e3a0e39652b9dd87
MD5 75a316815840dd8093e7c857b20508a2
BLAKE2b-256 aafaec507f03cb6873f687e5ab3e5f850f301de92d7262c0366002902d3318b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 28c99ea6c79b2959660cb6661946d71d1e8c82ec9e9008a052c7142eba03a06d
MD5 dbedd6c8972dbb7d65d775715a8987c5
BLAKE2b-256 560646019e628ca86a69c42f7ae66f2ab68c5727d9d36370c07aa8ba493dd9ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0873bd922c086ed9281128e97c0423cb1fa89e761f68ac0db6457221732cfe6d
MD5 a1e39c3eedec225d10d2a7bb3996fae7
BLAKE2b-256 933638153e924828d058cbf546a8e05298557962e21056062b48304e91e8ab74

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6af14e5744eb4882c96fddde75d028416c615b82ef321c948194d3eb37e53058
MD5 0c2d3aa21cd019d59e79c02449552d90
BLAKE2b-256 3026d2d7c9b1568de7cef5bffe9cfaad7308ca801efd56777eb924ddd29973c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 11e1fa40c8ce86b680da591581d6ef15d3ee074b36e12068cbfad2e8ddc7a913
MD5 b7c51e58b8e0ba4dd1d5246fde2e7812
BLAKE2b-256 11b7765d2cdc6948d32d2d7bca35883c1c1c51c5f6cc7f98ee12934b6e5a97f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-macosx_11_0_x86_64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toolr_py-0.26.1-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for toolr_py-0.26.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1893524143fd4d90d2c7b33feec9cee9c9265fcf5f6e197752aa76e33d63276b
MD5 d0047b98f0024293beb33e912f552102
BLAKE2b-256 cdffb01de64d5b742d7575d1ff1bbab7246e15058261d929f6399a1b0e947670

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.26.1-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on s0undt3ch/ToolR

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page