wayu is a zero-dependency CLI for Zsh and Bash. Manage PATH entries, aliases, env vars, and plugins with one command. Every change backed up automatically.
wayu replaces the scattered, manual editing of shell config files with structured commands — each with validation, dry-run preview, and automatic backups.
A declarative wayu.toml keyed table for PATH entries. Auto-derived keys, deduplication, validation, and a clean command that removes entries pointing to missing directories. Changes compile to optimized shell scripts automatically.
Every modification creates a timestamped backup automatically. Keeps the last 5. Restore any config type with one command. You cannot accidentally lose your shell config.
Automatic Zsh/Bash detection from $SHELL. Shell-specific config files with correct syntax. Fish support is experimental. Migrate between shells with wayu migrate.
Shell identifier validation, reserved word checking (if, export, etc.), dangerous character escaping, and path sanitization.
Surface read-only aliases from external tools (e.g. fabric patterns) in wayu alias list via alias-sources.conf.
Author your entire shell environment in one wayu.toml file — PATH, aliases, constants, plugins, prompt, even the prompt format. Single source of truth, dotfile-friendly, machine-portable. Validated with wayu toml validate.
wayu search <query> across PATH entries, aliases, and constants at once. Acronym matching: frwrks finds FIREWORKS_AI_API_KEY.
62 curated plugins. Install from registry name or any Git URL. Dependency resolution with cycle detection. Conflict detection across env vars, functions, aliases. Priority-based load ordering.
CLI mode is pipe-safe and CI-ready. Run wayu with no args (or --tui) for a 9-view full-screen interface with vim-style navigation, fuzzy filter, confirmation modals.
Health-check every config: install, source line, PATH entries, plugins, backups, TOML, dependencies. --fix auto-repairs known issues. --json output for CI.
wayu reload start watches wayu.toml and config files. Regenerates static output on save (debounced 500ms). No more source ~/.zshrc after every tweak.
Configure custom commands to run before or after operations via hooks.conf. Supports pre_path_add, post_alias_add, etc. Logging, notifications, custom integrations.
Bootstrap with wayu template apply developer. Presets: developer, minimal, data-science, full. Each preset adds common paths, aliases, and constants to your wayu.toml.
wayu function add mkcd seeds a shell-specific skeleton in ~/.config/wayu/functions/ and opens it in $EDITOR. Every file is sourced at shell startup. list and remove round it out.
wayu migrate --from zsh --to bash. Generates equivalent shell-specific config files. Switch between Zsh and Bash without losing PATH, aliases, env, or plugin state. Fish migration is experimental.
The --dry-run flag previews any change before it’s written to disk. BSD sysexits.h exit codes (0, 1, 64–78). Fails fast, never silently.
Every command follows the same pattern: wayu <command> <action> [args]. No flags to memorize. No config files to learn.
# Add a new PATH entry
wayu path add ~/.cargo/bin
# List all entries
wayu path list
# Remove an entry
wayu path rm /usr/local/bin
# Remove broken entries (preview first)
wayu path clean --dry-run
wayu path clean --yes
# Remove duplicates
wayu path dedup --yes# Add aliases
wayu alias add ll 'ls -la'
wayu alias add gs 'git status'
wayu alias add gc 'git commit'
# List wayu-managed (--full for external too)
wayu alias list
# Remove an alias
wayu alias rm ll
# Browse 62 popular plugins
wayu plugin search
wayu plugin search syntax
# Install from registry or URL
wayu plugin add autosuggestions
wayu plugin add https://github.com/user/plugin.git
# Manage plugins
wayu plugin list
wayu plugin enable zsh-autosuggestions
wayu plugin priority zsh-autosuggestions 50
wayu plugin update --all# Search across PATH, aliases, and constants
wayu search git
# Acronym matching: 'frwrks' → FIREWORKS_AI_API_KEY
wayu find frwrks
# Short alias
wayu f api
# Direct lookup of one constant
wayu const get CLOUDFLARE_API_TOKEN# Run all checks (9 diagnostics)
wayu doctor
# Auto-fix issues marked 🔧
wayu doctor --fix
# Machine-readable output (CI-friendly)
wayu doctor --json
# Generate optimized init for faster startup
wayu doctor --optimize# Edit declarative wayu.toml
wayu config edit
# Validate schema
wayu toml validate
# Watch mode — regenerate on save
wayu reload start
# Custom shell scripts (extra.<shell>)
wayu config extend
# Detect inline scripts to migrate
wayu config scan# Backups are created automatically.
# These commands let you manage them.
# List all backups
wayu backup list
# List backups for one config type
wayu backup list path
# Restore most recent backup
wayu backup restore path
# Clean up old backups (keeps last 5)
wayu backup rmEvery command is wayu <noun> <verb>. No flags to memorize, no subcommand trees. Muscle memory transfers instantly.
Add --dry-run to any command to see exactly what would change. No surprises, no rollbacks needed.
Zero interactive prompts in CLI mode. BSD exit codes for proper error handling. Add --yes for unattended operations.
Generates plain .zsh / .bash files you can read and edit directly. No lock-in, no proprietary format.
~/.config/wayu/wayu.toml is the single source of truth: PATH, aliases, constants, plugins, prompt, and inline scripts.
Commit it to your dotfiles. Restore your entire shell on any machine in one command. Hot-reload on every save.
wayu <cmd> add to mutate, or edit the TOML directly.
Wayu detects which is your source of truth.
wayu reload start watches the TOML and regenerates static .zsh files on save (debounced 500ms).
wayu toml validate catches typos, malformed values, and missing required keys.
# Single source of truth for your shell
[shell]
type = "zsh"
[prompt]
format = "{username}{dir}{git_branch}\n{character}"
command_timeout = 60000
[paths]
cargo_bin = "$HOME/.cargo/bin"
local_bin = "$HOME/.local/bin"
homebrew_bin = "/opt/homebrew/bin"
[aliases]
ll = "ls -la"
gs = "git status"
gco = "git checkout"
[env]
EDITOR = "nvim"
PAGER = "less -R"
# Plugins managed separately in plugins.json
# Install with: wayu plugin add autosuggestionswayu config edit
wayu toml validate
wayu reload start
Activated when you pass a command. Zero prompts, zero interactive elements. Designed for shell scripts, CI/CD pipelines, and provisioning tools.
--yes flag for confirmation-free destructive opsif statements and pipesLaunch with wayu (no args) or wayu --tui. A complete terminal UI built from scratch — no external TUI libraries.
j/k, arrow keys)9 checks across install state, shell sourcing, PATH validity, plugin health, backups, TOML schema, and external dependencies. Auto-fix what's mechanical. JSON output for CI pipelines.
wayu doctor — interactive run with status, summary, and fix suggestionswayu doctor --fix — auto-repair issues marked 🔧wayu doctor --json — structured output for CI / monitoringwayu doctor --optimize — generate optimized init for faster shell startupOne command via Homebrew. No compiler, no build system, no drama.
Config & runtime files in ~/.config/wayu/ + ~/.local/share/wayu/
~/.local/share/wayu/. Source init.zsh from your shell RC — it loads core, lazy, and helper scripts automatically.Ready to clean up?
One binary. Zero dependencies. Every shell config change backed up, validated, and reversible.