v8.0.0 · A shell configuration management CLI written in Odin. Manages PATH entries, aliases, environment variables, completions, and backups across Bash, Zsh, and Fish.
Recorded with VHS in a throwaway home: vhs docs/demo/demo.tape (see docs/demo/). Website: wayu.dvrd.io.
- Multi-shell -- Automatic Bash/Zsh/Fish detection with shell-specific config files
- Dual mode -- Non-interactive CLI for scripting + interactive TUI (default when run with no args)
- PATH management -- Keyed entries in entries.json with deduplication and validation
- Alias & constants -- Add, remove, list with input validation and reserved word checking
- Fuzzy matching -- Smart search with acronym support (e.g.,
faak→FIREWORKS_AI_API_KEY) - Completions -- Manage shell completion scripts (Zsh, Bash, Fish)
- Plugin management -- Install, enable/disable, and prioritize shell plugins with dependency resolution
- Built-in autosuggestions -- opt-in fish-like history suggestions for zsh (
[settings] autosuggest = true), without wrapping every zle widget like the zsh-autosuggestions plugin - Built-in syntax highlighting -- opt-in command-line highlighting for zsh (
[settings] highlight = true) with zsh-syntax-highlighting's styles, using zsh's own lexer, no widget wrapping and no forks; a keystroke re-highlights only the last words - Functions and scripts -- shell functions (
wayu function, sourced at startup) and standalone executables in any language (wayu script: swift compiled, python/ruby/node/bun/shells/... linked) on PATH; existing scripts can be imported - Backup & restore -- Automatic timestamped backups before every modification
- Shared shell entries -- Use the same PATH entries, aliases and constants in Bash, Zsh, and Fish
- Plugin reconstruction -- Restore missing checkouts from synced metadata, preserving recorded revisions and settings
- Dry-run mode -- Preview any change before applying it
- Scriptable -- BSD sysexits.h exit codes, no interactive prompts in CLI mode
- Standalone core -- No interpreter required for the CLI; plugins use Git, and scripts use their language's interpreter or compiler
brew tap dvrd/wayu
brew install wayu
wayu initPrebuilt for macOS 15 Sequoia or later (Apple silicon and Intel) and Linux (x86_64 and arm64, glibc); on other platforms build from source.
Tested with (anything else may work but isn't tested):
| Versions | |
|---|---|
| macOS | 15 (CI; Intel: CI smoke test), 26, 27 |
| Linux | Ubuntu 24.04 (CI; arm64: CI smoke test) |
| zsh | 5.9 |
| bash | 3.2 (macOS /bin/bash), 5.x |
| fish | 4.x |
On the same platforms, without Homebrew:
curl -fsSL https://wayu.dvrd.io/install.sh | sh
wayu initdocs/install.sh (POSIX sh) downloads the release
archive for your OS and CPU, verifies its SHA-256 (and its build provenance
attestation when gh is installed and logged in), and installs wayu to
~/.local/bin atomically. WAYU_VERSION=vX.Y.Z pins a release,
WAYU_INSTALL_DIR picks the directory, and it refuses to install next to a
Homebrew-managed wayu unless WAYU_FORCE=1. Run it again to upgrade.
Requires the Odin compiler at the
release named in .github/odin-release — the one CI
and releases are built with (download it from
Odin releases); ./build_it
warns when your odin is a different release.
# Bootstrap the build system, then build, install and run `wayu init`
odin build build -out:build_it && ./build_it install./build_it install puts the binary in $PREFIX/bin (default
~/.local/bin, which must be on your PATH), replacing it atomically, and
warns when another wayu earlier on PATH shadows it.
Use one install method. While Homebrew manages wayu, ./build_it install
and the install script refuse to run (--force / WAYU_FORCE=1
override): two copies on PATH mean the shell runs one version and you
upgrade the other. To switch from Homebrew to a source build or the script,
brew uninstall wayu first; to switch back, delete ~/.local/bin/wayu.
wayu init creates ~/.config/wayu/ (a wayu.toml scaffold and the other
files you edit) and the data dir ~/.local/share/wayu/ (your PATH entries,
aliases and constants, plus the generated files), and offers to add one line
to your rc file — or prints it when stdin is not a terminal:
| Shell | rc file | Line |
|---|---|---|
| zsh | ${ZDOTDIR:-~}/.zshrc |
source "${WAYU_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/wayu}/init.zsh" |
| bash | ~/.bash_profile if it exists, else ~/.bashrc |
source "${WAYU_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/wayu}/init.bash" |
| fish | ~/.config/fish/config.fish |
if test -n "$WAYU_DATA_DIR"; source $WAYU_DATA_DIR/init.fish; else if test -n "$XDG_DATA_HOME"; source $XDG_DATA_HOME/wayu/init.fish; else; source ~/.local/share/wayu/init.fish; end |
The line finds the data dir however it was chosen (WAYU_DATA_DIR,
XDG_DATA_HOME, or the default). The shell is detected from $SHELL;
wayu init --shell bash (or zsh, fish) picks another one. Run
wayu init once per shell you use; they share one wayu.toml and one set of
entries.
zsh: to give scripts (zsh -c, editors, cron) your PATH and env too, put the
line in ~/.zshenv instead of ~/.zshrc — once, not in both. A login shell
runs /etc/zprofile after .zshenv, and on macOS its path_helper moves the
system dirs ahead of yours; wayu puts its dirs back in front at the first
prompt, or right before the command in zsh -l -c … (dirs you prepend in
.zshrc stay ahead of them).
init.<ext> sources one precomputed file, core.<ext>, which wayu rewrites
after every change (wayu path|alias|const …, the TUI, wayu build). That
is the recommended setup. The alternatives:
| rc line | When |
|---|---|
source ".../wayu/init.zsh" (the line above) |
Default. Fast; picks up every wayu change. |
source "${WAYU_DATA_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/wayu}/turbo.zsh" |
Only for rc files that already use it: turbo.<ext> (zsh/bash, written by wayu export) is a copy of core.<ext>, kept current by wayu. |
eval "$(wayu export --eval)" |
Only constants, PATH entries and aliases, as shell code, without plugins, [tools], prompt or completions. For scripts, containers or CI that want the variables but none of the interactive setup. Writes nothing. |
After editing wayu.toml by hand, run wayu build (or wayu toml validate
first). PATH changes reach shells that are already open at their next
prompt (see PATH changes in open shells and
scripts); other changes apply to
new shells, or source the init file again.
Every key of wayu.toml, the entry store and the other config files is
described in docs/config-reference.md.
brew upgrade wayu # or, from source: git pull && ./build_it install
wayu init # refresh init.<ext> and regenerate core.<ext>
wayu doctor # check the resultwayu init keeps wayu.toml, extra.<ext> and your other files; an
unmodified init.<ext> from the previous release is replaced (the old one is
backed up). Any ordinary write (wayu alias add …) regenerates too. From
7.0 on, a release that changes a data format or moves a file converts or
moves yours automatically the first time it runs (backup first, one-time
notice); see docs/STABILITY.md for what each release
guarantees.
What changed in each release, and what you may need to adapt, is in docs/UPGRADING.md.
Tip: Running
wayuwith no arguments opens the interactive TUI.
# PATH
wayu path add /usr/local/bin
wayu path add ~/.cargo/bin
wayu path list
wayu path rm /usr/local/bin
wayu path clean --yes # remove entries pointing to missing directories
wayu path dedup --yes # remove duplicate entries
# Aliases
wayu alias add ll 'ls -la'
wayu alias add gs 'git status'
wayu alias list
wayu alias rm ll
# Environment variables
wayu constants add EDITOR nvim
wayu constants list # secret-looking values shown as ********
wayu constants list --reveal # show real values
wayu constants rm EDITOR
# Fuzzy matching - smart search with acronym support
wayu search api # search across all configs
wayu find faak # finds FIREWORKS_AI_API_KEY by acronym
wayu f git # short alias for search
# GET is exact-match only (safe for X=$(wayu const get NAME))
wayu const get FIREWORKS_AI_API_KEY # prints the value
wayu const get FIRE # exit 65, suggests names on stderr
# Completions
wayu completions add jj /path/to/_jj
wayu completions list
wayu completions generate # generate wayu self-completions (zsh + bash + fish)
# Backups
wayu backup list
wayu backup restore entries --yes # restore the latest entries.json backup
# Plugins
wayu plugin search # browse popular plugins
wayu plugin search syntax # filter by keyword
wayu plugin add autosuggestions # install popular plugin (registry key)
wayu plugin add https://github.com/user/plugin.git # install from URL
wayu plugin list # list installed plugins
wayu plugin enable zsh-autosuggestions
wayu plugin disable zsh-autosuggestions
wayu plugin priority zsh-autosuggestions 50 # lower = loads earlier
wayu plugin update --all
wayu plugin restore # reconstruct missing checkouts from synced metadata
wayu plugin remove zsh-autosuggestions --yes
# Extra configuration (scripts that run at shell startup end)
wayu config edit # Edit wayu.toml (declarative config)
wayu config extend # Edit extra.<shell> (custom scripts)
wayu config scan # Detect scripts in .zshrc to migrate
# Startup time (init.<shell> is already a single precomputed file)
wayu build profile # time each section of the generated init
wayu export # turbo.zsh: same content as core.zsh (kept for old rc files)
# Diagnostics
wayu doctor # Health check all configs
wayu doctor --fix --yes # Auto-fix issues (--dry-run to preview)
# TOML configuration (declarative mode)
wayu toml validate # Check wayu.toml syntax
# Hot reload (auto-regenerate static output on save)
wayu reload start # alias: wayu watch
wayu reload status
wayu reload stop
# Pre/post hooks (run custom commands around wayu operations)
wayu hooks # show configured hooks
wayu hooks edit # edit ~/.config/wayu/hooks.conf
# Functions and scripts (see "Functions and scripts" below)
wayu function add mkcd # shell function: seed a skeleton, open $EDITOR
wayu script new hello --lang python # executable on PATH: skeleton, $EDITOR, build
wayu script import ~/bin/* --dry-run # preview adopting existing scripts
# Templates (config presets)
wayu template list # available: developer, minimal, data-science, full
wayu template apply developer # apply preset to existing config
wayu template apply minimal # minimal preset
# Interactive mode
wayu # TUI opens by default with no args
wayu --tui # explicit flagwayu <command> [<action>] [arguments] [flags]
docs/cli.md documents every command, action and flag,
where flags are recognised (-- and the alias add / const add value
rule), the --json document shapes and the exit codes.
wayu help and wayu <command> help print the same from the binary.
| Command | Description |
|---|---|
path |
Manage PATH entries |
alias |
Manage aliases |
constants, const, env |
Manage constants (environment variables) |
search, find, f |
Fuzzy search across all configurations |
completions |
Manage shell completion scripts |
backup |
List, restore and prune backups |
plugin |
Install and manage shell plugins |
init |
Create the config and wire up your shell |
config |
Edit wayu.toml / extra., scan your rc file |
build |
Regenerate the init files; profile startup; clear the evalcache |
export |
Write turbo. or print env/PATH/aliases for eval |
toml |
Validate / show wayu.toml |
doctor |
Health check and diagnostics (--json, --fix) |
template |
Apply config presets (developer / minimal / data-science / full) |
hooks |
Pre/post operation hooks |
function, functions, func, fn |
Manage shell functions (data dir functions/) |
script, scripts |
Manage standalone scripts on PATH (data dir scripts/ + bin/) |
reload, watch, hot-reload |
Watch wayu.toml, entries.json, secrets.json and script sources; regenerate on change |
version |
Show version |
help |
Show help |
wayu includes intelligent fuzzy matching that makes finding configurations effortless:
Search across all your configurations simultaneously:
# Search by partial name
wayu search api
# Constants (2 found)
# ────────────────────────────────────
# OPENAI_API_KEY [substring] ★
# FIREWORKS_AI_API_KEY [substring] ★
# Search by acronym (first letter of each word)
wayu find faak # matches FIREWORKS_AI_API_KEY
wayu f oak # matches OPENAI_API_KEY
wayu f gcm # matches git commit aliases
# Search all configs at once
wayu search git
# Shows aliases, constants, and paths related to "git"get never guesses: it prints the value of the entry with exactly that name.
On a miss it exits 65 (EXIT_DATAERR) and lists similar names (never
values) on stderr, so X=$(wayu const get NAME) can't silently receive a
different secret.
wayu const get FIREWORKS_AI_API_KEY # prints the value
wayu const get FIRE
# ERROR: Constant not found: FIRE
# Did you mean:
# FIREWORKS_AI_API_KEY| Type | Description | Example |
|---|---|---|
exact |
Exact match | search API_KEY → API_KEY |
prefix |
Starts with query | search FIRE → FIREWORKS... |
substring |
Contains query | search WORKS → FIREWORKS... |
acronym |
First letters of the words | search faak → FIREWORKS_AI_API_KEY |
fuzzy |
General fuzzy match | search frwrks → FIREWORKS... |
Constants whose name looks like a credential (contains KEY, TOKEN,
SECRET, PASS, API, AUTH, CREDENTIAL, PRIVATE, ...) or whose value
looks like one (sk-..., ghp_..., scheme://user:pass@host, ...) are shown
as ******** in const list (text and --json, with or without --full;
external environment variables included), toml show, the TUI constants
view, search results and --dry-run previews. search matches constant
names only, never their values. Pass --reveal to const list / toml show
(or press v in the TUI constants view) to see real values; const get NAME
always prints the real value.
wayu const add NAME --secret reads the value from stdin (hidden on a
terminal) and stores it encrypted in secrets.json. Prefer the prompt or a
pipe: a value given as an argument also works, but is visible to other
local users in ps and saved in your shell history (wayu warns). Nothing
in the config or generated files holds the value in plaintext. The master key lives in the macOS keychain (Secret Service on
Linux, or a 0600 key file: [secrets] backend = "file"). Shells load
secrets from a per-session cache in $XDG_RUNTIME_DIR / $TMPDIR
(decrypted once, then sourced without forking); that cache is plaintext on
disk (0600) until wayu secrets lock or the next store change deletes it.
wayu const add OPENAI_API_KEY --secret # prompts, input hidden
wayu const get OLD_TOKEN | wayu const add OLD_TOKEN --secret # convert a plain one
wayu const get OPENAI_API_KEY # decrypts
wayu secrets list # names and mode, never values
wayu secrets rekey # new master key
wayu secrets lock # drop the decrypted session cacheA run-only secret (--run-only) is never exported to your shells; only
wayu secrets run NAME... -- CMD decrypts it, into that one command's
environment (exec, no shell):
wayu const add GH_TOKEN --run-only
wayu alias add gh 'wayu secrets run GH_TOKEN -- gh'★- High confidence match (score > 1000)◆- Medium confidence match (score > 500)
BSD sysexits.h values for scripting: 0 success, 64 usage error, 65
bad input, 66 missing input file, 78 configuration error, … — the full
table, with examples checked by the test suite, is in
docs/cli.md.
Launch with wayu (no args) or wayu --tui for an interactive terminal interface.
- Vim-style navigation (
j/k,h/l, arrow keys) - Inline fuzzy filtering with
/ - Source filter cycling with
s(all → wayu → inactive → external) - Add and delete entries with confirmation modals
- Tab-navigable forms with focus indicators
- Automatic backups before modifications
- Dashboard-style main menu with 8 views
Keybindings:
| Key | Context | Action |
|---|---|---|
j / k / ↑ / ↓ |
All views | Move selection |
l / Enter |
All views | Select / enter |
h / Esc |
All views | Go back |
q |
Main menu | Quit |
/ |
Data / plugin views | Start inline filter |
s |
PATH / Alias / Constants | Cycle source filter |
a |
PATH / Alias / Constants | Add entry (modal form) |
d / x |
PATH / Alias / Constants | Delete entry (with confirmation) |
v |
Constants | Reveal / hide secret-looking values (masked by default) |
Tab / t |
Plugins view | Switch Installed ↔ Registry tab |
| Space | Plugins (Installed) | Enable / disable selected plugin |
e / x |
Plugins (Installed) | Enable / disable selected plugin |
u |
Plugins (Installed) | Update selected plugin (Esc cancels) |
d |
Plugins (Installed) | Remove selected plugin (with confirmation) |
i |
Plugins (Registry) | Install selected plugin (with confirmation) |
c |
Backups view | Cleanup old backups |
| Ctrl+C | Anywhere | Quit |
Built from scratch with raw termios control, alternate screen buffer, differential rendering, and signal handling. No external TUI libraries.
wayu keeps the files you edit in ~/.config/wayu/ and the data it manages in
~/.local/share/wayu/:
~/.config/wayu/
# --- You edit these (version-control them) ---
wayu.toml # [shell], [settings], [tools], [prompt]
extra.{zsh,bash,fish} # custom scripts (conda init, tool evals, etc.)
tools.{zsh,bash,fish} # one-off tool setup not expressible as [tools]
alias-sources.conf # external alias sources (shell-agnostic, read-only)
hooks.conf # pre/post operation hooks
~/.local/share/wayu/ # ${XDG_DATA_HOME:-~/.local/share}/wayu
# --- wayu manages these (`wayu path|alias|const|plugin`, the TUI) ---
entries.json # PATH entries, aliases, constants
plugins.json # installed plugin metadata (JSON5)
# --- wayu generates these (safe to delete; regenerated on change) ---
init.{zsh,bash,fish} # entry point — source THIS in your RC file
core.{zsh,bash,fish} # the generated init loaded by init.<shell> (one precomputed file)
path_sync.{zsh,bash,fish} # PATH entry list re-read by the live PATH sync prompt hook
plugins.{zsh,bash,fish} # generated plugin loader
plugins/ # cloned plugin repos + runtime config
turbo.{zsh,bash,fish} # optional copy of core via `wayu export`
completions/ # shell completion scripts
backup/ # timestamped backups (last 5 per file)
# --- managed by commands (`wayu function`, `wayu script`) ---
functions/ # shell functions, sourced at startup
scripts/ # script sources (NAME.<ext>)
bin/ # what runs: links / compiled binaries, first on PATH
Shell is detected automatically from $SHELL. Override with --shell bash, --shell zsh, or --shell fish.
WAYU_CONFIG_DIR moves the files you edit and WAYU_DATA_DIR the data
dir. Every wayu.toml table and key ([tools], [prompt], …),
entries.json, hooks.conf, plugins.json and the other files are
described in
docs/config-reference.md.
Keep these source files together in your dotfiles manager (for example, chezmoi) or copy them into the corresponding directories on the new machine:
| From the config dir | From the data dir |
|---|---|
wayu.toml, hooks.conf, alias-sources.conf, extra.*, tools.* |
entries.json, plugins.json, functions/, scripts/, and any custom completion scripts |
Copy custom completions to <data>/completions/. Recreate generated files,
plugin checkouts and script binaries locally. entries.json can contain
plaintext constants; keep credentials out of a public dotfiles repository.
For encrypted constants, transfer entries.json and secrets.json together
using the multi-machine secrets workflow.
Each machine keeps its own keys: exclude secret.key, identity.key,
session caches, backups and generated runtime files from synchronization.
Install wayu and the tools your setup uses (Git for plugins, interpreters or
compilers for scripts, and programs named in [tools]), then run:
wayu plugin restore --dry-run
wayu plugin restore
wayu init --shell zsh # repeat for each shell you use: bash, fish
wayu script build # recreate links and compiled scripts
wayu build
wayu doctorRestore uses recorded plugin commits, preserves pins and disabled state,
and replaces saved checkout paths with paths under the current data dir.
Existing checkouts and local edits are kept; plugin update is the explicit
step to advance them. See the restore contract.
Use wayu path add ~/.local/bin --portable for home-relative entries you
intend to share. It stores $HOME/.local/bin; the directory must exist on
the machine adding it. The default still stores an absolute path. Absolute
entries, custom shell code, external script links and external tool
installations remain specific to each machine. See the
coexistence recipes for other shell tools.
Both live in the data dir and are managed with commands; the directory is the source of truth.
- Functions (
wayu function add|list|remove) are shell functions infunctions/<name>.<ext>, sourced bycore.<ext>: they run inside your shell and can change its state (cd, variables). - Scripts (
wayu script new|edit|list|remove|import|build) are standalone executables in any language: swift, python, ruby, node, bun, bash, zsh, fish, perl, lua, sh. The source isscripts/<name>.<ext>;bin/<name>runs it (a link for interpreted languages, aswiftc -Obinary for swift), andbin/is first among wayu's PATH entries in zsh, bash and fish.script newwrites the interpreter's absolute path as the shebang,wayu buildrebuilds scripts whose source changed, andscript importadopts existing scripts while skipping binaries, symlinks and package-manager launchers (a file that declares its own build command needs--allow-build). Default language:[scripts] default_lang(else swift).
wayu script new today --lang python # create, edit, link into bin/
today # on PATH (open shells: next prompt)
wayu script import ~/bin/* --dry-run # what would be imported / skipped
wayu script list --jsonwayu path add/rm (and hand edits of entries.json) reach already-open
zsh/bash shells at their next prompt: core.<ext> installs a prompt hook,
_wayu_paths_sync (zsh precmd, bash PROMPT_COMMAND, fish fish_prompt
event), that re-reads path_sync.<ext> only when the PATH entry list
changed.
Scripts never show a prompt, so the hook never runs. A script that sources
init.<ext> and changes PATH entries applies the change itself:
source "$HOME/.local/share/wayu/init.bash" # or init.zsh
wayu path add "$HOME/tools/bin"
_wayu_paths_sync # PATH now includes ~/tools/binA script that did not source init.<ext> has no _wayu_paths_sync; extend
PATH yourself (PATH="$HOME/tools/bin:$PATH") — wayu, a child process,
cannot change its caller's environment.
bash and PROMPT_COMMAND: wayu prepends _wayu_paths_sync to
PROMPT_COMMAND when init.bash is sourced. A later line that replaces
it (PROMPT_COMMAND='history -a') silently drops the hook. Append instead
(PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND;}history -a" or, in
bash ≥ 5.1, PROMPT_COMMAND+=(...)), or source init.bash after it.
wayu doctor warns about such lines in your bash startup files.
init.<shell> loads one generated file, core.<shell>: everything from
wayu.toml and entries.json is precomputed into straight-line code (zcompiled for zsh), and
the dynamic parts — [tools] lazy loaders, the native prompt, live PATH
sync — are function definitions and hooks, not work done at startup. zsh
runs compinit (with a cached, zcompiled .zcompdump) and sets up the
prompt in interactive shells only.
Measured with tests/benchmark/startup.sh (20 PATH entries, 60 aliases,
20 constants; macOS, hyperfine, empty zsh ≈ 3.5 ms, empty bash ≈ 2–3 ms):
| before (5.0) | now | |
|---|---|---|
zsh -f -c 'source init.zsh' |
22.8 ms | 9.3 ms |
zsh -f -i -c 'source init.zsh' (compinit) |
22.3 ms | 16.0 ms |
same + [tools] + native prompt, zsh -f -c / -i |
23.4 / 23.4 ms | 8.8 / 14.9 ms |
bash --norc -c 'source init.bash' |
9.3 ms | ≈ 5 ms |
Where the old time went (zsh): compinit ~14 ms (8 ms of it remains in
interactive shells, with the zcompiled dump), the [tools] evalcache lookup
${commands[...]} hashing every PATH dir ~2 ms, the PATH apply ~0.8 ms,
four extra files sourced (path_sync, helpers, lazy, login) ~0.3 ms. bash:
the PATH apply ~2 ms (here-strings write a temp file each in bash 3.2;
multibyte pattern matching). wayu build profile times each # === ... ===
section of your own core file.
alias-sources.conf lets you surface aliases from external tools (e.g. fabric patterns) in wayu alias list as read-only sections.
# Format: dir <path> <command_template>
# {name} is replaced with each directory entry name
dir ~/.config/fabric/patterns fabric --pattern {name}
- Lines starting with
#are comments - Only
dirtype is supported — one alias per subdirectory (or per file if no subdirectories exist) - Sources appear as labelled read-only tables after your managed aliases
- Missing directories are silently skipped
Uses bld, an Odin build system library. Development requires the pinned Odin compiler; the full test suite also uses Ruby, Python and the supported 7EB1 shells. See CONTRIBUTING.md for the workflow and SECURITY.md to report a vulnerability; contributor notes on the code are in AGENTS.md.
# Bootstrap (once)
odin build build -out:build_it
# Build & test
./build_it build # optimized release build
./build_it debug # debug build with symbols
./build_it test # unit tests; leaks fail them (NAME[,NAME] runs only those)
./build_it check # type-check only
./build_it dev path list # debug build + run
./build_it clean # remove build artifacts
./build_it install # build + install to ~/.local/bin ($PREFIX/bin) + wayu init
./build_it release [vX.Y.Z] # manual release override (version optional; see Releasing)
./build_it help # show all targets
# Integration Tests (Ruby)
ruby tests/integration/run_all.rbSee Validation before a release for the failure campaign, candidate acceptance gates and retained evidence. Tests cover failed writes, full filesystems, interruptions, concurrent mutations, upgrades and repeated fresh-shell sessions. Automated trials do not replace a dated daily-driver observation or the independent review of experimental secrets v2.
Day-to-day work lands on the develop branch (CI runs, nothing is
released). When a batch is ready to ship, develop is merged into main;
PRs into main are only accepted from develop or hotfix/*
(main-guard.yml).
Releases are automatic. Every push to main runs
.github/workflows/bump.yml, which:
- Runs full CI and startup budgets: unit/memory tracking, integration, AddressSanitizer, golden/TUI, strict compiler, compatibility, previous-binary upgrades, failure campaign, fresh installs and candidate session trials. Nothing is released unless the automated gates pass.
- Derives the next version from Conventional Commits
since the last tag via
git-cliff(feat→ minor,fix/refactor/etc. → patch,!/BREAKING CHANGE→ major). - Bumps
VERSIONinsrc/main.odin, regeneratesCHANGELOG.md, renames the## Unreleasedsection ofdocs/UPGRADING.mdto the version, commitschore: release vX.Y.Z, and tags it. - Builds the release binaries
(
release-build.yml: macOS arm64 and x86_64, Linux x86_64 and arm64; macOS x86_64 is cross-compiled on arm64, since Odin ships no macOS x86_64 toolchain), smoke-tests each on its own platform, attests them, publishes the GitHub release, and regenerates the Homebrew tap formula (dvrd/homebrew-wayu). CI runs the same build and smoke test on every push todevelopand every PR.
The workflow never deletes or moves an existing tag or release: if the target
version's tag already exists elsewhere it fails and prints the manual fix.
CI uses the Odin release pinned in .github/odin-release.
Behavior changes users must know about are marked breaking (fix(scope)!: or a
BREAKING CHANGE: footer): they force a major bump and are listed under
"⚠ Upgrade notes" in the changelog. The release page's "⚠ Upgrade notes" are
the version's section of docs/UPGRADING.md.
So you do not bump the version by hand — land your Conventional Commits on
develop and merge develop into main to ship. ./build_it release [vX.Y.Z] exists as a manual override (it also
auto-detects the version when the argument is omitted); the version argument is
only needed when git-cliff is unavailable.
MIT