# ez

> A macOS CLI tool for project-scoped command aliases with team sharing, secrets management via Apple Keychain, and local run history tracking.

ez is an open-source macOS command-line tool built in Swift that lets developers define command aliases scoped to individual project directories. Created by Tommi Urtti of Urtti Apps, it is distributed via Homebrew and licensed under MIT. The latest release is version 1.3.0, published in August 2026.

## What It Is

ez solves the problem of memorizing long, context-specific shell commands by letting you define short aliases in a `.ez_cli.json` file inside any directory. Unlike global shell aliases, ez aliases only exist where they are defined, preventing accidental execution in the wrong project. The tool is a single native Swift binary with instant startup and zero runtime dependencies beyond Apple's own swift-argument-parser.

## Core Workflow

The typical ez workflow involves three steps: adding an alias, running it, and optionally sharing it with a team:

- **Add**: `ez add deploy "./scripts/deploy.sh --env prod"` stores the command in the local `.ez_cli.json`.
- **Run**: `ez deploy` executes the stored command with full terminal passthrough.
- **Share**: Committing `.ez_cli.json` to version control gives every team member the same aliases immediately, similar to a `Makefile` or `npm run` script.

Aliases support `{1}`, `{2}` positional placeholders for parameterization, and extra arguments are automatically appended to the end of the command.

## Secrets and Privacy

Secrets such as API keys are stored in Apple Keychain via `ez add-secret` and injected into the command environment at runtime. They are never written to disk, never printed to the terminal, and never visible in the process table. ez itself makes zero telemetry or external network calls. Run history is stored in a local SQLite file at `~/.ez/runs.db` and never leaves the machine.

## Update: Version 1.3.0

Version 1.3.0, released August 19, 2026, added three significant capabilities:

- **Run history**: Every alias execution is recorded locally. `ez stats` reports success rate, median duration, p90, and a duration trend per alias.
- **Outlier alerts**: When a run is meaningfully slower or faster than its own median, a notice is printed directly on the timing line (e.g., "↑ 56% slower than median").
- **Parallel mode**: Aliases added with `-p` run multiple commands concurrently, each with individual timing and shared Ctrl+C handling.

## Architecture and Platform

ez requires macOS 15.0 or later and is built with Swift 6.0+ / Xcode 16.4+. The project structure separates source code in `ezcli/`, an automated acceptance test suite (`acceptance-test.sh`), and a manual interactive test script for TTY features. zsh tab completion is included for command discovery. The tool passes through real exit codes from driven processes, making `ez test && ez deploy` chains behave correctly in CI and scripts.

## Features
- Project-scoped aliases stored in .ez_cli.json per directory
- Team sharing via version control commit
- Apple Keychain secrets management
- Parameterized aliases with {1} {2} placeholders
- Local run history in SQLite (~/.ez/runs.db)
- ez stats with success rate, median, p90, and duration trend
- Outlier alerts for runs meaningfully off their median
- Parallel command execution with -p flag
- Real exit code passthrough for CI and script chaining
- Full terminal passthrough for interactive tools (vim, less, ssh)
- zsh tab completion
- Zero telemetry and no external network calls
- Single native Swift binary with instant startup
- MIT open-source license

## Integrations
Homebrew, Apple Keychain, zsh, SQLite, Git / version control

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
1.3.0

## Links
- Website: https://urtti.com/ez
- Documentation: https://github.com/urtti/ez
- Repository: https://github.com/urtti/ez
- EveryDev.ai: https://www.everydev.ai/tools/ez-cli