Shell setup

Two things worth doing once, after magus is installed and on your PATH: tab-completion, and the mgs shorthand. Both work under either name.

Shell completion

magus completion <shell> prints a completion script for bash, zsh, fish, or powershell (pwsh is accepted too). Every script registers both magus and the mgs shorthand, so you set this up once and get it under both names.

What it completes

• Subcommands, and the subcommands under graph, config, server, self, and man.
• Targets after run and affected: ls, build, test, lint, format, clean, generate, ci.
• Project paths, live from the workspace. The script shells out to magus ls -o name, so it offers the projects this repo actually has rather than a baked-in list, and it stays correct as you add them.
• Nouns after describe (spell, charm, target, project, workspace, module, mcp-tool) and lenses after insight (hotspots, affinity, ownership, trend, report).
• Flags per subcommand, so magus affected --<TAB> offers --base, --plan, --bisect, and the rest rather than nothing.

Outside a workspace the project completions are simply empty. Nothing errors.

bash

Source it from your rc. The script is re-read from the binary on every new shell, so it cannot go stale after an upgrade:

echo 'source <(magus completion bash)' >> ~/.bashrc

zsh

Install it onto your $fpath as _magus:

mkdir -p ~/.zsh/completions
magus completion zsh > ~/.zsh/completions/_magus

Then in ~/.zshrc, before compinit runs:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Do not append the zsh script to ~/.zshrc. It ends by invoking its own completion function, which only means something inside a completion context; sourced from an rc it runs at shell startup and registers nothing.

Unlike the bash recipe this writes a snapshot, so regenerate it after a magus self update to pick up new subcommands and flags.

fish

Drop it in the completions directory, where fish loads it on demand:

magus completion fish > ~/.config/fish/completions/magus.fish

PowerShell

Append it to your profile:

magus completion powershell >> $PROFILE

Full reference: magus completion.

mgs shorthand

The de facto shorthand for magus is mgs: three left-hand keys, fast to type, and collision-free.

The install script creates it for you unless you pass --no-shorthand. To add it to an existing install:

magus self install-shorthand

That symlinks mgs next to the binary itself, so it is on your PATH if magus is. An existing mgs is left alone unless you pass --force, and --dir puts the link somewhere else. Full flag reference: magus self.

A symlink rather than a shell alias, because an alias only exists in interactive shells: mgs in a script, a Makefile, or a CI step would not resolve. The link also survives magus self update, which resolves symlinks before swapping the binary underneath.