mise-completions-sync¶

Automatically sync shell completions for tools managed by mise.

The Problem¶

When mise installs a tool like kubectl or gh, you don't automatically get shell completions. You'd have to manually run the tool's completion command and configure your shell.

The Solution¶

mise-completions-sync automatically generates completions for all your mise-installed tools.

Installation¶

The package is named mise-completions-sync; the binary it installs is misecompsync (mise reserves mise-* names for itself, so the shim can't forward to a binary that starts with mise-).

Homebrew¶

brew install alltuner/tap/mise-completions-sync

Cargo¶

cargo install mise-completions-sync

Using mise¶

mise use -g github:alltuner/mise-completions-sync

From GitHub Releases¶

Download the appropriate binary for your platform from the releases page.

Shell Setup¶

Add the completions directory to your shell configuration.

ZSH¶

Add to ~/.zshrc before compinit:

fpath=(${XDG_DATA_HOME:-$HOME/.local/share}/mise-completions/zsh $fpath)

Bash¶

Add to ~/.bashrc:

for f in ${XDG_DATA_HOME:-$HOME/.local/share}/mise-completions/bash/*; do
  [[ -f "$f" ]] && source "$f"
done

Fish¶

Add to ~/.config/fish/config.fish:

set -gx fish_complete_path $fish_complete_path ~/.local/share/mise-completions/fish

Custom Output Dirs¶

By default, completions are synced to $XDG_DATA_HOME/mise-completions/<shell>. However, you can override the output directories using environment variables:

# Override default base output directory
export MISE_COMPLETIONS_SYNC_HOME="$XDG_DATA_HOME/custom-vendor-completions"

Or you can override output targets on a per-shell basis (these take precedence over the base override above):

# Bash completions to standard bash location
export MISE_COMPLETIONS_SYNC_BASH_DIR="$XDG_DATA_HOME/bash-completion/completions"

# ZSH completions to standard zsh location
export MISE_COMPLETIONS_SYNC_ZSH_DIR="$XDG_DATA_HOME/zsh/site-functions"

# Fish completions to standard fish locations.
# (pick one or the other, both are autoloaded by fish)
export MISE_COMPLETIONS_SYNC_FISH_DIR="$XDG_DATA_HOME/fish/vendor_completions.d"

Note: Target directories will be created if they don't already exist. Don't forget to update your shell setup above.

Custom Registry¶

The supported tool list is built into the binary, but you can extend it without waiting for a release. Put a registry.toml at $XDG_DATA_HOME/mise-completions-sync/registry.toml, or next to the misecompsync executable, and it is laid on top of the built-in registry:

schema_version = 1

[tools]
# a tool the built-in registry doesn't cover
graphite-cli = { zsh = "gt completion zsh", bash = "gt completion bash" }

# built-in patterns are available to your own entries
mytool = "standard"

# override a built-in entry
yq = { zsh = "yq shell-completion zsh" }

Entries are merged with the built-in ones rather than replacing them, so the tools you don't mention keep working. schema_version is required. See How It Works for the full registry format.

Updating¶

Homebrew¶

brew upgrade mise-completions-sync

Cargo¶

cargo install --force mise-completions-sync

mise¶

mise upgrade github:alltuner/mise-completions-sync

Or pin a specific version with mise:

mise use -g github:alltuner/[email protected]

Automatic Sync¶

Set up a mise hook to automatically sync completions when tools are installed:

mkdir -p ~/.config/mise && cat >> ~/.config/mise/config.toml << 'EOF'

[hooks]
postinstall = "misecompsync"
EOF

Initial Sync¶

After setup, run the initial sync:

misecompsync

Usage¶

# Sync completions for all installed tools (all shells)
misecompsync

# Sync only for specific shell
misecompsync --shell zsh

# Sync specific tool(s)
misecompsync kubectl helm

# List tools with completion support
misecompsync list

# Show completion directory for a shell
misecompsync dir zsh

# Clean up completions for uninstalled tools
misecompsync clean

Additional Flags¶

By default, completions are synced for every installed tool. You can narrow the set with the following scope flags that mise ls accepts — they're passed straight through:

# Only tools in global mise config files
misecompsync --global   # or -g

# Only tools in local (project) mise config files
misecompsync --local    # or -l

# Only tools currently in mise config files (not just with `mise install`)
misecompsync --current  # or -c

--global and --local are mutually exclusive (same as mise ls)
Scope flags also apply to clean — caution: misecompsync --global clean would remove completions for tools not in the global config, which may include locally-installed tools if they both use the same MISE_COMPLETIONS_SYNC_HOME.
Scope flags conflict with explicit tool args and --new-only

License¶

MIT

Built at All Tuner Labs by David Poblador i Garcia