Getting Started

amoxide (am) is a shell alias manager that brings direnv-like functionality to aliases. Instead of managing shell aliases in static dotfiles, define them per project, per toolchain, or globally — and the right ones load automatically.

Quick Start

1. Install amoxide:

Homebrew

brew install sassman/tap/amoxide sassman/tap/amoxide-tui

Shell Script

curl -fsSL https://github.com/sassman/amoxide-rs/releases/latest/download/amoxide-installer.sh | sh
curl -fsSL https://github.com/sassman/amoxide-rs/releases/latest/download/amoxide-tui-installer.sh | sh

PowerShell

powershell -ExecutionPolicy Bypass -c "irm https://github.com/sassman/amoxide-rs/releases/latest/download/amoxide-installer.ps1 | iex"
powershell -ExecutionPolicy Bypass -c "irm https://github.com/sassman/amoxide-rs/releases/latest/download/amoxide-tui-installer.ps1 | iex"

Cargo (pre-built)

cargo binstall amoxide amoxide-tui

Cargo

cargo install amoxide amoxide-tui

2. Set up your shell:

am setup fish          # or: zsh, bash, brush, powershell

This detects your profile file, shows exactly what it will add, and asks for confirmation. See Shell Setup for the manual approach.

3. Add your first alias:

am add gs git status

That's it — gs is now available in your shell, no restart needed.

Recommended Workflow

I personally start with project-local aliases, so I can be super lazy in the context I'm working in.

For example in this project I have:

• installing the binary by i does a cargo install --path crates/am
• running tests by t does a cargo test
• running lint checks by l does a cargo clippy --all-targets --all-features -- -D warning

Step 1 Add local / project aliases with -l:

am add -l t cargo test
#  ^^^ ^^ ^ ^--------^
#   |   | |       |
#   |   | |       +---- the command to alias
#   |   | +---- the alias name
#   |   +---- local, writes to .aliases in the current directory
#   +---- adding an alias

am add -l l cargo clippy --all-targets --all-features -- -D warning
am add -l i cargo install --path crates/am

These local aliases live in a .aliases file in the project root and are loaded/unloaded automatically on cd.

Step 2 — Refactor: After a while I notice t and l are the same in every rust project. Time to extract them into a reusable profile — a named collection of aliases you can activate anywhere:

am profile add rust
am add -p rust t cargo test
#      ^-----^
#         |
#         + ---- we add the alias to the profile "rust"

am add -p rust l cargo clippy --all-targets --all-features -- -D warning

# activate it
am profile use rust

TIP

am tui allows to move the aliases from project to profile level (by select and m)

Now t and l are available everywhere (not just this project). The project .aliases keeps only project-specific ones like i.

Step 3 — Use multiple profiles. I also want git aliases everywhere. Just activate both:

# git profile with a signing commit alias
am profile add git
am add -p git gm "git commit -S --signoff -m"

# activate both — order matters: the last one activated wins on conflicts
am profile use git
am profile use rust

Now I have git aliases and rust aliases loaded at the same time. If both profiles had an alias with the same name, the last-activated one (rust) would take precedence.

TIP

All verbs have short forms to save typing, e.g. am a -l t cargo test or am p a rust.

What's Next?

• Installation — all installation methods in detail
• Shell Setup — how the shell integration works
• Profiles — organize aliases into reusable groups
• Project Aliases — auto-loading .aliases files