| verblock |
|---|
12 Nov 2025:v0.1: Matthew Sinclair - Initial version |
A bash/zsh framework for building and managing command-line utilities with a single dispatcher.
Utilz is a dispatcher-based framework where all utilities are symlinks to a single bin/utilz script. When you run a utility, the dispatcher figures out what was called and routes to the appropriate implementation.
This means:
- One codebase for common functionality (help, version, error handling)
- Each utility gets its own directory with implementation and tests
- Consistent CLI experience across all utilities
- Built-in testing with BATS
Utilz/
├── VERSION # Framework version (single source of truth)
├── bin/
│ ├── utilz # Dispatcher script
│ ├── cleanz -> utilz # Utility symlinks...
│ ├── clipz -> utilz
│ ├── ... # (7 utilities total)
│ └── retry -> utilz
├── opt/
│ ├── utilz/
│ │ ├── lib/
│ │ │ └── common.sh # Shared functions
│ │ ├── test/ # Framework tests
│ │ └── utilz.yaml # Framework metadata
│ └── <utility>/ # Each utility has its own directory
│ ├── <utility> # Implementation
│ ├── <utility>.yaml # Utility metadata
│ ├── test/ # Utility tests
│ └── README.md # Utility docs
└── help/
├── utilz.md # Framework help
└── <utility>.md # Utility help files
# Clone the repo
git clone https://github.com/matthewsinclair/utilz.git ~/Devel/prj/Utilz
# Set up environment
export UTILZ_HOME="$HOME/Devel/prj/Utilz"
export PATH="$UTILZ_HOME/bin:$PATH"
# Add to your shell config (~/.zshrc or ~/.bashrc)
echo 'export UTILZ_HOME="$HOME/Devel/prj/Utilz"' >> ~/.zshrc
echo 'export PATH="$UTILZ_HOME/bin:$PATH"' >> ~/.zshrc
# Check installation
utilz doctorutilz help # Show framework help
utilz help <utility> # Show utility-specific help
utilz list # List installed utilities
utilz version # Show framework version
utilz doctor # Run diagnostics
utilz test # Run all tests
utilz test <utility> # Run tests for specific utility
utilz generate <name> [desc] # Generate new utility scaffoldYou can call utilities in two ways:
# Direct (via symlink)
mdagg --help
mdagg config.yaml -o output.md
# Via dispatcher
utilz mdagg --help
utilz mdagg config.yaml -o output.mdBoth methods work identically.
LLM text cleaner that removes hidden characters and formatting artifacts from text copied from ChatGPT, Claude, Gemini, and other LLM interfaces. Also supports stripping C2PA metadata from AI-generated images.
# Clean a file
cleanz document.txt
# Clean file in place
cleanz -i document.txt
# Clean clipboard contents
cleanz --clipboard
# Detect hidden characters without cleaning
cleanz --detect document.txt
# Pipe mode
pbpaste | cleanz | pbcopy
# Image mode: strip C2PA/AI metadata
cleanz --image photo.png -o cleaned.png
cleanz --image --detect dalle-image.pngSee utilz help cleanz for details.
Cross-platform clipboard copy and paste utility. Supports macOS (pbcopy/pbpaste), Linux X11 (xclip/xsel), and Wayland (wl-clipboard).
# Copy from stdin
echo "hello" | clipz copy
# Copy from file
clipz copy file.txt
# Paste to stdout
clipz pasteSee utilz help clipz for details.
GPG encryption and decryption wrapper with sensible defaults.
# Encrypt a file
cryptz encrypt secret.txt
# Decrypt a file
cryptz decrypt secret.txt.gpg
# Specify recipient
[email protected] cryptz encrypt file.txtSee utilz help cryptz for details.
Git multi-repository operations. Recursively find and check git repositories, excluding paths with leading underscores or .work.
# Check all repos in current directory
gitz status-all
# Check repos in specific path
gitz status-all ~/ProjectsSee utilz help gitz for details.
macOS system utilities - desktop backgrounds and folder icons.
# Desktop backgrounds with seasonal auto-selection
macoz bg # Auto-select current season
macoz bg autumn # Random autumn wallpaper
macoz bg autumn 02 # Specific seasonal wallpaper
macoz bg ~/Pictures/wallpaper.jpg # Custom image
# Folder icons
macoz setpicfor icon.png # Set icon for current directory
macoz setpicfor photo.jpg ~/Projects # Set icon for specific directory
macoz setpicfor --all # Batch: set icons for subdirectories
macoz setpicfor --all --dry-run # Preview changesSee utilz help macoz for details.
Markdown aggregator for concatenating multiple markdown files into a single document. Useful for assembling multi-file documents into PDFs.
# Using YAML config
mdagg assembly.yaml -o output.md
# Using glob pattern
mdagg "chapter-*.md" -d -b -o book.md
# From stdin
find docs -name "*.md" | sort | mdagg --stdin -o docs.mdSee utilz help mdagg for details.
Retry command until success with configurable wait time and max attempts.
# Retry with defaults (10s wait, unlimited retries)
retry "curl https://example.com"
# Retry with custom settings
retry --wait 5 --retries 3 "ping -c 1 google.com"See utilz help retry for details.
Use the built-in generator to scaffold a new utility:
# Generate a new utility
utilz generate myutil "My new utility description"
# Or with author name
utilz generate myutil "Does something useful" "Your Name"This creates:
opt/myutil/myutil- Executable implementation with boilerplateopt/myutil/myutil.yaml- Metadata (version, description, dependencies)opt/myutil/README.md- Documentationopt/myutil/test/myutil.bats- Test suite with basic testshelp/myutil.md- Help documentationbin/myutil- Symlink to dispatcher
Then customize the implementation:
# Edit the implementation
vim opt/myutil/myutil
# Test it
utilz myutil --help
utilz myutil
# Run tests
utilz test myutil
# Check everything is working
utilz doctor
utilz listTests use BATS (Bash Automated Testing System).
# Install BATS
brew install bats-core
# Run all tests
utilz test
# Run specific utility tests
utilz test mdagg
# Run tests directly
cd opt/mdagg/test
bats mdagg.batsTest files go in opt/<utility>/test/*.bats. See opt/mdagg/test/mdagg.bats for examples.
All utilities have access to functions from opt/utilz/lib/common.sh:
info()- Info message (blue)success()- Success message (green)warn()- Warning message (yellow)error()- Error message (red)show_help()- Display help fileshow_version()- Display versioncheck_command()- Check if command existsrequire_command()- Require command or show errorget_util_metadata()- Read utility YAML metadata
The framework version is stored in /VERSION. Utility metadata files (*.yaml) can either:
- Reference the framework version:
version_file: ../../VERSION- Specify their own version:
version: 1.0.0
utilz_version: "^1.0.0" # Compatible framework versions- Bash 4.0+ or Zsh
yqfor YAML parsing (install:brew install yq)bats-corefor testing (install:brew install bats-core)
Personal use. Copyright (c) 2025 Matthew Sinclair
Matthew Sinclair matthewsinclair.com