tools

Collection of tools mostly found on GitHub.

Setup with uv

This project uses uv for dependency management and task execution.

Install uv (if not already installed):

curl -Ls https://astral.sh/uv/install.sh | sh

Create the virtual environment and install dependencies:

uv sync

Run tasks via uv:

uv run inv --list

Install Tools

Install all tools to dist (default):

uv run inv install

Install a single tool to dist:

uv run inv install --name <tool>

Install all tools to ~/.local/bin (or ~/bin):

uv run inv install --local

Install a single tool to ~/.local/bin:

uv run inv install --name <tool> --local

Force reinstall all tools:

uv run inv install --force

Force reinstall a single tool:

uv run inv install --name <tool> --force

These tasks:

• Resolve the correct version from metadata.yaml
• Render the download_url template for your platform
• Download and place the binary in the configured install location

Update Metadata

Add a New Tool

uv run inv update.add \
  --repo-url https://github.com/owner/repo \
  --download-url "{{repo_url}}/releases/download/v{{version}}/{{name}}-{{os}}-{{arch}}" \
  --license MIT \
  --description "Short tool description"

Optional:

• --name Override the inferred tool name
• --dry-run Preview the generated entry without writing changes

The command will fail if the tool name already exists.

Adding a New Tool

You can automatically add a new entry to tasks/metadata.yaml using the update.add task.

This task:

• Fetches the latest GitHub release from the provided repo_url
• Infers the tool name from the repository if --name is not provided
• Extracts and normalizes the semantic version (strips leading v)
• Inserts the tool into metadata.yaml
• Keeps entries in strict alphanumeric order
• Validates against metadata.schema.json

Download URL Template Variables

The download_url field is rendered using Jinja. Common variables:

• {{name}} The tool name
• {{version}} Resolved semantic version
• {{repo_url}} Repository URL from metadata
• {{os}} Target operating system
• {{arch}} Target architecture
• {{rust_arch}} Rust-style architecture (when required by upstream releases)

Refer to existing entries in tasks/metadata.yaml for patterns.

Updating Existing Tools

To update all tools to their latest GitHub release:

uv run inv update.update-all

To update a single tool:

uv run inv update.package --name <tool>

To preview updates without writing changes:

uv run inv update.update-all --dry-run

These commands:

• Query the latest GitHub release
• Compare against the current version
• Update metadata.yaml if a newer semantic version is found
• Preserve strict alphanumeric ordering

This ensures the correct Python environment and pinned dependencies are used.