Tab Completion

Mage supports tab completion for all of its built-in flags as well as your project’s targets. Pressing Tab after typing mage will suggest available targets in the current directory, so you never have to remember exact names.

Quick Install

The easiest way to get tab completion is the built-in installer. Run mage -install with the name of your shell:

mage -install bash
mage -install zsh
mage -install fish
mage -install powershell   # also accepts "pwsh"

The installer will:

  1. Write a completion script to ~/.config/mage/ (or the appropriate platform-specific config directory).
  2. Add a source line to your shell’s startup file (.bashrc, .zshrc, PowerShell $PROFILE, etc.) so completions load automatically in every new session.
  3. Print a message telling you to restart your shell (or source the config file) to activate completions immediately.

If mage can’t update your shell config file for any reason, it will print the line you need to add manually — so the command is always safe to run.

Running mage -install again for the same shell is safe. It replaces the previous completion block rather than duplicating it.

Shell-Specific Notes

Bash — the installer sources the completion script from your .bashrc (preferred) or .bash_profile. It uses the standard complete built-in, so no extra packages are required.

Zsh — the installer sources the script from your .zshrc (honoring $ZDOTDIR if set). If compdef is not yet available when the script loads, it automatically calls compinit first.

Fish — completions are placed in $XDG_CONFIG_HOME/fish/completions/mage.fish (defaulting to ~/.config/fish/completions/). Fish loads files from this directory automatically, so no startup-file modification is needed.

PowerShell — the installer writes a .ps1 script and sources it from your $PROFILE. Both PowerShell Core (pwsh) and Windows PowerShell are supported. If the profile file or its parent directory doesn’t exist yet, mage creates them.

The -autocomplete Flag

Under the hood, all of the completion scripts call:

mage -autocomplete

This prints a plain list of targets (one per line) for the current directory and exits. You can run it yourself to see what completions would be offered:

$ mage -autocomplete
build
clean
deploy
test

Custom / Advanced Usage

If you use a shell that isn’t directly supported, or you want to integrate mage completions into a custom tool, you can wire up mage -autocomplete yourself. The contract is simple:

  • It prints target names separated by newlines to stdout.
  • It returns exit code 0 on success.
  • It reads magefiles from the current working directory, so make sure the completion function cds to the project directory (or runs mage there) before invoking it.

For example, a minimal POSIX-shell completion function might look like:

_mage_complete() {
    COMPREPLY=( $(mage -autocomplete 2>/dev/null) )
}
complete -F _mage_complete mage

Adapt this pattern for any environment that can execute a command and consume its line-delimited output.