GitHub - urtti/ez: Source code repo for the Mac command line tool ez, distribution Homebrew

3 min read Original article ↗

A macOS CLI tool for project-specific command aliases. Define commands locally within project directories, making team workflows more efficient and discoverable.

Demo

Features

  • Project-scoped storage - Aliases live in .ez_cli.json files at the directory level, keeping commands tethered to their respective projects
  • Safety through locality - No global aliases means no accidental damage in a different directory
  • Team collaboration - Commit the config file to version control so new team members get immediate access to established commands
  • Fast - Built in Swift with zero third-party dependencies and instant startup times
  • Secrets management - Store API keys and tokens in Apple Keychain, reference them in aliases without exposing values in terminal output
  • Private - Entirely offline with no telemetry or cloud connectivity
  • Interactive support - Full terminal passthrough for interactive applications like vim and ssh
  • Shell integration - zsh tab completion for command discovery
  • Built-in analytics - Automatic runtime tracking logs command execution duration

Installation

brew tap urtti/ez && brew install ez

Usage

Add an alias:

ez add deploy "./scripts/deploy.sh --env prod"

Run an alias:

List all aliases:

Remove an alias:

Parameterized aliases with {1}, {2}, ... placeholders:

ez add tag 'git tag -a {1} -m "Release {1}"'
ez tag v2.0.0  # → git tag -a v2.0.0 -m "Release v2.0.0"

Extra arguments are automatically appended to the end of the command:

ez add gs "git stash"
ez gs pop              # → git stash pop

ez add greet 'echo hello {1}'
ez greet world a b     # → echo hello world a b

Store secrets in Apple Keychain and reference them in aliases:

ez add-secret --key EZ_API_KEY --value sk-abc123
ez add deploy 'curl -H "Authorization: {EZ_API_KEY}" https://api.example.com/deploy'
ez deploy  # secret is injected at runtime, never shown in terminal output

Remove a secret:

ez remove-secret EZ_API_KEY

Run multiple commands sequentially:

ez build && ez test && ez deploy

Run commands in parallel:

How It Works

Aliases are stored in .ez_cli.json files within each directory. This keeps commands context-specific and prevents conflicts between projects. To clear all aliases in a directory, simply delete the .ez_cli.json file.

Requirements

  • macOS 15.0+

Development

Building

Running from source

Testing

Use the provided script to run tests with the correct flags:

Or filter specific tests:

./run-test.sh --filter EzTests.testScopeGetURL

Note: Do not use swift test directly. The UNIT_TEST flag must be passed to prevent tests from interfering with your real configuration:

swift test -Xswiftc -DUNIT_TEST

Code Coverage

Generate a coverage report:

For a detailed HTML report:

llvm-cov show .build/debug/ezcliPackageTests.xctest/Contents/MacOS/ezcliPackageTests \
  -instr-profile $(swift test --show-codecov-path | tail -n 1) \
  -format=html -output-dir=coverage

Project Structure

  • ezcli/ - Source code
  • test/ - Unit tests
  • run-test.sh - Script to run tests with the correct flags

Build Requirements

  • Swift 6.0+
  • Xcode 16.4+

Xcode Setup

If building for device or distribution, set your own Apple Development Team in the Xcode project settings.

License

MIT