Tool Tray
System tray app to manage and update Python tools from private GitHub repos via uv.
Quick Start
For Users
-
Install:
uv tool install tool-tray
-
Run the tray:
tooltray
-
On first run, setup dialog opens automatically - paste your config code
For Admins
Generate a config code to share with your team:
tooltray encode --token ghp_xxx --repo myorg/myapp
# Output: TB-eyJ0b2tlbi...
Each repo must have a tooltray.toml manifest (see below).
Commands
| Command | Description |
|---|---|
tooltray |
Run tray app |
tooltray setup |
Configure via CLI (paste config code) |
tooltray reset |
Remove config and start fresh |
tooltray init |
Create tooltray.toml template in current dir |
tooltray encode |
Generate config code for sharing |
tooltray autostart |
Manage system startup |
tooltray logs |
View log file |
tooltray cleanup |
Remove orphaned desktop icons |
tooltray --help |
Show help |
tooltray --version |
Show version |
Encode Options
tooltray encode --token TOKEN --repo ORG/REPO [--repo ...] [--prefix PREFIX]
Examples:
# Single repo (default TB- prefix)
tooltray encode --token ghp_xxx --repo myorg/myapp
# Multiple repos
tooltray encode --token ghp_xxx \
--repo acme/cli \
--repo acme/api
# Custom prefix for branding
tooltray encode --prefix ACME --token ghp_xxx --repo acme/cli
Autostart
tooltray autostart --enable # Add to system startup
tooltray autostart --disable # Remove from startup
tooltray autostart --status # Check if enabled
Logs
tooltray logs # Show last 50 lines
tooltray logs -f # Tail in real-time
tooltray logs --path # Print log file path
Cleanup
Remove orphaned desktop icons (icons for tools no longer in config):
tooltray cleanup --dry-run # Show what would be removed
tooltray cleanup # Prompt and remove
tooltray cleanup --force # Remove without prompting
Tray Menu
When not configured:
| Item | Description |
|---|---|
[!] Not configured |
Status indicator |
| Setup... | Open setup dialog |
| Quit | Exit the app |
When configured:
| Item | Description |
|---|---|
> myapp 1.0.0 |
Click to launch |
> myapp 1.0.0 -> 1.1.0 * |
Update available, click to launch |
myapp (not installed) |
Not yet installed |
| Orphaned Icons | Shows icons needing cleanup (if any) |
| Clean Up (n) | Remove orphaned icons |
| Update All | Install/update all tools |
| Check for Updates | Refresh version info |
| Configure... | Open setup dialog to reconfigure |
| Quit | Exit the app |
Project Manifest (tooltray.toml)
Each managed repo must have a tooltray.toml in its root:
name = "databridge" # Display name (required)
type = "uv" # uv | git (required)
launch = "databridge" # Command to launch (optional)
build = "npm install" # Build command for git type (optional)
desktop_icon = true # Create desktop shortcut (default: false)
icon = "assets/icon.png" # Path to icon in repo (optional)
autostart = false # Add to system autostart (default: false)
Repos without tooltray.toml are skipped.
Config Code Format
The config code is a prefix + base64-encoded JSON:
TB-eyJ0b2tlbiI6ImdocF94eHgiLCJyZXBvcyI6WyJteW9yZy9teWFwcCJdfQ==
Decodes to:
{
"token": "ghp_xxx",
"repos": ["myorg/myapp"]
}
Config is stored at:
- Windows:
%LOCALAPPDATA%\tooltray\config.json - macOS:
~/Library/Application Support/tooltray/config.json - Linux:
~/.config/tooltray/config.json
Requirements
- Python 3.12+
- uv
Development
# Run directly
uv run tooltray
# Test encode command
uv run tooltray encode --token test123 --repo myorg/myapp
# Type check
uv run basedpyright src/
License
MIT
Metadata
Release files for tool-tray 0.3.19
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tool_tray-0.3.19.tar.gz | 16.8 kB | Without provenance | Details for tool_tray-0.3.19.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tool_tray-0.3.19-py3-none-any.whl | Python 3 | none | any | Details for tool_tray-0.3.19-py3-none-any.whl |
Total release size: 40.3 kB
Release files / tool_tray-0.3.19.tar.gz
| Download URL | tool_tray-0.3.19.tar.gz |
|---|---|
| Size | 16.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
04bcafab0118b466c5a7a6b80dec522205885dae61196aa4a013a0b677847b41
|
|
BLAKE2b-256 checksum How to use checksums |
687f54b29b1a039cbd5ca4440494cc56a7fd8b4ce490fb1785690ec8cedd17b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tool_tray-0.3.19-py3-none-any.whl
| Download URL | tool_tray-0.3.19-py3-none-any.whl |
|---|---|
| Size | 23.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
df60a9faa40734dbe2ef6b143b0317e96631e5ab4e808c4ca4e3d57818b89310
|
|
BLAKE2b-256 checksum How to use checksums |
54319f4fdf61be278951649fb8edaae8f01f70470a0bedf98b3cbfc1bc664949
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"EndeavourOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for tool-tray 0.3.19
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.