Alias Scripts

Turn shell aliases into real executable scripts so non-interactive shells and agents can use them.

Works by reading alias definitions from your shell rc file(s) and generating small wrapper scripts with the same names.

Quick start (from repo)

bun

cd /Users/iannuttall/dev/repos/alias-scripts

bun install

bun run alias-scripts -- generate

npm

cd /Users/iannuttall/dev/repos/alias-scripts

npm install

npm run alias-scripts -- generate

Usage

Show help

bun run alias-scripts -- --help

By default, aliases are read only from the shell's rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish). Sourced files are not parsed unless you pass them via --rc.

Generate scripts (default command)

bun run alias-scripts -- generate

Choose output directory

bun run alias-scripts -- generate --out ~/.local/bin

List aliases (from rc file)

bun run alias-scripts -- list

Report shell + PATH + conflicts (rc aliases only)

bun run alias-scripts -- report

Clean generated scripts

bun run alias-scripts -- clean

Generate scripts and disable aliases in your rc file

bun run alias-scripts -- generate --disable-aliases

List backups

bun run alias-scripts -- backups

Restore latest backup

bun run alias-scripts -- restore

Restore by id

bun run alias-scripts -- restore --id 20260107-120102-abcd

Restore uses the latest backup by default. Use --id to pick a specific one.

Options

Pick a shell explicitly

bun run alias-scripts -- generate --shell zsh

Allow shadowing existing commands

bun run alias-scripts -- generate --allow-shadow

Overwrite existing files in output dir

bun run alias-scripts -- generate --force

Pick a specific rc file

bun run alias-scripts -- generate --disable-aliases --rc ~/.zshrc

Multiple rc files

bun run alias-scripts -- generate --disable-aliases --rc ~/.zshrc,~/.zprofile

Backup directory

bun run alias-scripts -- generate --backup-dir ~/.config/alias-scripts/backups

Restore to a different output dir

bun run alias-scripts -- restore --out ~/tmp/alias-scripts

Dry run

bun run alias-scripts -- generate --dry-run

Filter by name

bun run alias-scripts -- generate --include "g*,c*" --exclude "gs"

JSON output

bun run alias-scripts -- report --json

Notes

Make sure your output directory is on PATH for non-interactive shells.

Backups are created whenever an existing file would be overwritten (when using --force).

If you use --disable-aliases, the tool comments out matching alias lines and creates a backup so you can restore.

Aliases are only disabled for scripts that were created in this run or already exist as generated scripts in the output directory.

Check PATH in a non-interactive login shell

zsh -lc 'echo $PATH'

Default output directory

echo ~/.local/bin

Default backup directory

echo ~/.config/alias-scripts/backups

Limitations

• Aliases that rely on interactive-only state may behave differently.
• cd inside a generated script will not change your current shell directory.
• If an alias uses shell-specific syntax, the generated script runs under the same shell to preserve behavior.

License

MIT