My personal toolbox of utility scripts
Browse the toolbox
toolbox.py is a cross-platform CLI and terminal UI for browsing, downloading, verifying, and running utility scripts from the toolbox. The toolbox is a searchable collection of scripts that I use for various tasks, and it is backed by a remote manifest that lists the available scripts and their SHA-256 hashes for verification.
Requirements
Features
- Browse and search the toolbox website or the command line interface.
- Interactive terminal UI for browsing available scripts.
- Search scripts by name, ID, description, language, category, or tags.
- View script descriptions, usage examples, download URLs, and checksums.
- Download one or multiple scripts directly from the command line.
- Verify every downloaded script against its SHA-256 checksum.
- Run verified Python and shell scripts directly from the TUI.
- Check for newer Toolbox releases with
toolbox --version.
- Works on macOS, Linux, and Windows with python3 installed.
Install
WinGet (Windows)
winget install --id PiSaucer.Toolbox --exact
Homebrew (macOS)
On macOS, install with Homebrew:
brew tap PiSaucer/homebrew-tap
brew install PiSaucer/tap/toolbox
Python Package (pipx)
Recommended when installing Toolbox as an isolated Python CLI:
pipx install pisaucer-toolbox
toolbox --version
Python Package (pip)
python3 -m pip install pisaucer-toolbox
Python Package (uv)
uv tool install pisaucer-toolbox
toolbox --version
macOS / Linux installer
curl -fsSL https://pisaucer.github.io/toolbox/install.sh | sh
Build from source
Build a wheel:
python3 -m build
pipx install ./dist/pisaucer_toolbox-*.whl
toolbox --version
pipx install .
./install.sh
Manifest caching
Toolbox caches HTTP(S) manifests separately for each manifest URL in your user cache directory (%LOCALAPPDATA%\toolbox on Windows, ~/Library/Caches/toolbox on macOS, or $XDG_CACHE_HOME/toolbox / ~/.cache/toolbox on Linux). Fresh entries avoid a network request for up to ten minutes; server cache directives and response age can shorten that window.
When an entry expires, Toolbox checks its ETag (or Last-Modified when no ETag is available). A 304 Not Modified response reuses the saved manifest; a 200 OK response replaces it with the validated JSON object. no-cache requires revalidation and no-store prevents storage. A failed check reports the network error rather than silently using an expired manifest. Cache read/write failures do not prevent a normal fetch, and local file:// manifests are always read directly.
Use toolbox --refresh to check immediately, even with a fresh cache. toolbox update and toolbox update SCRIPT always check immediately as well. Initial downloads and revalidation still require a network connection, so caching does not fix a slow connection attempt.
Scripts may declare Python packages as well as host commands. For example, whisper-transcribe requires:
python3 -m pip install openai-whisper
Toolbox projects can use a human-maintained Toolfile to declare the scripts they need.
# Download utilities
dcurl>=1.0.0
compress-json==1.3.0 # Keep this version reproducible
Install the declared environment, or manage entries directly:
toolbox install
toolbox install dcurl # Alias for `toolbox add dcurl`
toolbox add dcurl
toolbox add dcurl==1.1.0
toolbox add "dcurl>=1.1.0"
toolbox remove dcurl
toolbox update
toolbox update dcurl
Adding a script without an explicit constraint writes a >= constraint using the version currently published in the manifest. For example, toolbox add dcurl may write dcurl>=1.0.0.
toolbox install --file path/to/Toolfile selects a Toolfile outside the current directory. With a script argument, install is an alias for add. Toolfile.lock is generated by Toolbox and records the exact resolved script versions, Git commits, SHA-256 hashes, download sources, and detected system-tool state. Commit both files when you want a reproducible project environment. install reproduces a compatible lock; update intentionally refreshes versions allowed by the Toolfile.
Uninstall
If you used the macOS/Linux installer, run:
./uninstall.sh
Use the matching package manager if toolbox was installed as a package:
brew uninstall toolbox
pipx uninstall pisaucer-toolbox
uv tool uninstall pisaucer-toolbox
python3 -m pip uninstall pisaucer-toolbox
Links
License
Distributed under the MIT License. See LICENSE for more information.