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> -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, and every release from 0.34.0 onward publishes a signed packslip manifest that mise verifies against the ToolR repository's signing identity, remembering the release workflow after the first install. The install scripts verify the attestation by default (requires the gh CLI); pass --verify-attestation=skip to bypass, accepting the supply-chain risk.

Two wheels, two roles

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 packslip:github.com/s0undt3ch/ToolR@latest

# Pin a version
mise use packslip:github.com/s0undt3ch/ToolR@X.Y.Z

# Install machine-wide instead of per-project
mise use -g packslip:github.com/s0undt3ch/ToolR@latest

Installs toolr from its signed packslip manifest via mise's packslip backend — no plugin to register. mise verifies the release against the ToolR repository's signing identity, remembering the release workflow after the first install, and checks the digest and size of the archive for your platform before unpacking it. For projects that already pin tool versions via .mise.toml, toolr's version becomes part of your project's reproducible tool set. Releases before 0.34.0 have no manifest to install from; use mise use aqua:s0undt3ch/ToolR@<version> for those. 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

• Quickstart
• Writing commands
• Third-party packages
• Agent skills (for LLM coding assistants)
• Internals (manifest, freshness, cache)
• CLI reference

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.