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.27.0.tar.gz (238.8 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.27.0-cp311-abi3-win_amd64.whl (983.7 kB view details)

Uploaded CPython 3.11+Windows x86-64

toolr_py-0.27.0-cp311-abi3-musllinux_1_2_x86_64.whl (477.1 kB view details)

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

toolr_py-0.27.0-cp311-abi3-musllinux_1_2_aarch64.whl (448.6 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

toolr_py-0.27.0-cp311-abi3-manylinux_2_28_x86_64.whl (538.7 kB view details)

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

toolr_py-0.27.0-cp311-abi3-manylinux_2_28_aarch64.whl (383.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

toolr_py-0.27.0-cp311-abi3-macosx_11_0_x86_64.whl (793.4 kB view details)

Uploaded CPython 3.11+macOS 11.0+ x86-64

toolr_py-0.27.0-cp311-abi3-macosx_11_0_arm64.whl (674.7 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for toolr_py-0.27.0.tar.gz
Algorithm Hash digest
SHA256 aaab3a6e75624fbc9aea9878ef895f4d1c6ffb8ae744a9394c7cb49e48c66079
MD5 847884667c3e998d06112d50e750bfc7
BLAKE2b-256 660640cf568d92fea6ee75deb998d8789fa8e21b1a059b75ec27520a121ba957

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0.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.27.0-cp311-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 87a39292d92f88b63acc2cc1c4dfc054f7ea86f6aa441538c4ae496f93c99519
MD5 fe523c0e0d66d1c07bb7516b54484a9a
BLAKE2b-256 4ea9a2b6d892c0dc422952b0b056f6dd526c3f8efe761d2198ced7240170b460

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 e76475dfc39f1d9ec7aaf404553847198b81f868829a4a95fac525240d5671c2
MD5 47863ea27656c02b6450969c8f2a8759
BLAKE2b-256 70b3493f635efcc4ea3b42a007d6c90dc854c19416eb13ae6c7fed84dcc7f319

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 e23593bb22f21a1ab8b0ab55da8fd6d31d1e27c94e8e258ba4c9d76e3e543a8a
MD5 fb26ce841703b4adbd9988756f51e601
BLAKE2b-256 f1f25f7ce2a3751b51e71a40c0e65088c127b90b256d3f6daa024eab08995cf2

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 52ab0c6f9f01c51d143ff0bbd5f53a86701701c40f13b41200da44ddc8b6917f
MD5 bbf5a5d0e4c7ed05de3a27b35a7e50fc
BLAKE2b-256 54b99c960265a44dd2a1e21932fd325a36bd7886de2a3a10c40fd8cf4fc0ad4e

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 cc3174d51021152f141b3d0cf12d26dc04add227d866e923708ad06f5cd95393
MD5 7185193f5dcb58b20332b44137c14da6
BLAKE2b-256 798e1ea35d14220091b361b3abba58a282a53462adb3a57bbd71f23887ca9697

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 c844710fc1efeabb5408f8036901a1e85ca8fe2fd6493939fd0a7a7ef340381f
MD5 7bc94989d0e757624cf56978dccacf7e
BLAKE2b-256 84c4a4e78bd3ce799c865a460249329dd1a2a8fa0583a550a21acf4c5c418d67

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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.27.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for toolr_py-0.27.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8392d6a08b35d17ce9a0f22eeb6432b58df736e3a2b3144854f44fe71990a982
MD5 cfcec7351c45db9f905509dff909e4b4
BLAKE2b-256 8421b4b2bc029ec1f07f38a88f5329d8d8b0bdd9fabdb20acb191f79484b6a59

See more details on using hashes here.

Provenance

The following attestation bundles were made for toolr_py-0.27.0-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