Hyper alias — manage shell aliases and functions through an interactive CLI. Search, edit, track usage, and back up — without ever touching
.zshrc.
📖 English · 한국어 README
Managing shell aliases used to mean editing .zshrc by hand. halias turns it into an app:
- 🎯 Context-aware ranking — shortcuts you use in this directory float to the top of search. No manual grouping required.
- ✨ Interactive add (
ha add) — Clack-powered TUI ... - 🔍 Fuzzy search (
ha) — fzf integration searches across name, command, tags, and description - 📊 Auto stats — every shortcut is generated as a wrapper function, so usage is tracked automatically
- 🛡️ Safety nets — system command conflict detection, frequent-use confirmation on delete
- 💾 Backup & restore — single-file JSON export/import with merge or replace strategies
- 🐚 Two entry points —
haliasfor scripts,hafor daily use; same binary
npm install -g haliasBoth halias and ha will be available globally. The shorter ha is recommended for daily use.
git clone https://github.com/hyukjunkwon/halias.git
cd halias
npm install
npm run link:local # registers both `halias` and `ha` globally# 1. Add your first shortcut interactively
ha add
# ◇ Name? gs
# ◇ Type? alias
# ◇ Command? git status
# ◇ Description? show working tree status (optional)
# ◇ Tags? git (optional)
# 2. Install shell integration (one-time setup)
ha install
# 3. Apply (or just open a new terminal)
source ~/.zshrc
# 4. Use it!
gs # → runs `git status`
# 5. Find shortcuts later
ha # fuzzy search across all your shortcuts
hareload # apply newly added shortcuts to current shell| Command | Description |
|---|---|
ha (no args) |
Fuzzy search — find shortcuts fast |
ha search (= ha s) |
Same as above, explicit |
ha add |
Add a new shortcut interactively |
ha edit [name] |
Edit an existing shortcut (picker if no name) |
ha list (= ha ls) |
List shortcuts (--sort name|recent|usage) |
ha rm [name] |
Delete a shortcut (extra confirm for frequently used) |
ha stats |
Usage stats (top N, unused, time-filtered) |
ha export [path] |
Back up shortcuts to JSON |
ha import <path> |
Restore from backup (--strategy merge|replace) |
ha install |
Add shell integration to ~/.zshrc |
ha doctor |
Diagnose your environment |
halias keeps a single source of truth in ~/.halias/shortcuts.json and generates ~/.halias/generated/aliases.sh from it. Your .zshrc only ever has one line added:
# >>> halias shortcuts >>>
[ -f "$HOME/.halias/generated/aliases.sh" ] && source "$HOME/.halias/generated/aliases.sh"
# <<< halias shortcuts <<<Every shortcut — even simple aliases — is generated as a shell function so usage tracking works consistently:
# from `ha add gs "git status"`:
gs() {
_halias_track "gs" # appends to ~/.halias/stats.log
git status "$@" # forwards extra args
}This unification means ha stats works identically for aliases and functions, and you get "$@" arg forwarding for free.
Hit ha with no args to drop into a full-text search across all your shortcuts:
halias❯ git gs git status #git ★ 12회 Show working tree status dev pnpm dev #js ★ 8회 Start dev server gp git pull #git 34회 Pull from origin mkcd mkdir -p && cd #fs Make and enter directory
Search matches across name, command body, tags, and description. Try searching for "polled" — if you described gp as "pull from origin", it'll match.
halias automatically tracks which shortcuts you use in each directory. When you run ha, shortcuts you've used in the current directory float to the top, marked with ★. Global frequency is the tiebreaker.
Example: in ~/work/myapp, dev (used 8 times here) ranks above gs (used 12 times globally but only once here). Move to ~/side/api and the ranking shifts to match what you actually do there.
This means you don't need to organize aliases manually — they organize themselves around your usage patterns.
Best experience comes with fzf installed. The easiest way:
ha doctorIt detects your OS and package manager (Homebrew, apt, dnf, winget, scoop) and offers safe options. Without fzf, search falls back to a simple selector.
ha stats # top 10 with bar chart
ha stats --top 5
ha stats --since 7d # last 7 days only (also: 24h, 30m)
ha stats --unused # never-used + 30+ days idle Usage stats (since 1 month ago · 14 calls total)
1. gs 5 ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ last: 1 min ago
2. gp 3 ▇▇▇▇▇▇▇▇▇▇▇▇ last: 6 min ago
3. mkcd 2 ▇▇▇▇▇▇▇▇ last: 30 min ago
ha export # ./halias-backup-2026-04-29.json
ha export ~/Dropbox/halias-backup.json
ha import ~/Dropbox/halias-backup.json # merge (existing wins)
ha import backup.json --strategy replacemerge keeps existing entries on name conflict (safe). replace clears everything first (explicit confirmation required).
ha doctor checks your environment end-to-end:
halias environment check
✓ fzf installed
✓ Shell integration installed (.zshrc)
✓ shortcuts.json integrity OK (12 entries)
! 1 shortcut overrides system command
• ls
→ Run `ha rm <name>` if unintended.
✓ aliases.sh generated
~/.halias/
├── shortcuts.json # source of truth (human-readable JSON)
├── stats.log # raw usage log (timestamp + name)
└── generated/
└── aliases.sh # auto-generated, sourced by your shell
Everything is plain text, version-controllable, and easy to back up.
The first version ships with everything you need for personal alias management: core CRUD, fuzzy search, usage stats, backup/restore, and an environment doctor.
Driven by real usage and friction discovered in daily work, not by feature checklists. Some likely candidates:
- First-run onboarding — auto-suggest
ha installon first invocation $EDITORmode for function bodies — edit multi-line functions in vim/code- Search results sorted by usage frequency
Suggestions and bug reports welcome via issues.
npm run dev -- add # run with tsx (no build needed)
npm run typecheck # type check
npm run build # produce dist/MIT — see LICENSE.