Skip to content

feat(environments): install the usage CLI so mise completions work - #106

Merged
inkatze merged 1 commit into
mainfrom
chore/mise-usage-cli
Aug 7, 2026
Merged

feat(environments): install the usage CLI so mise completions work#106
inkatze merged 1 commit into
mainfrom
chore/mise-usage-cli

Conversation

@inkatze

@inkatze inkatze commented Aug 7, 2026

Copy link
Copy Markdown
Owner

Adds the usage CLI (5.0.0) to the environments role, so mise's shell
completions work.

Why

mise completion fish does not emit a completion script of its own. It emits
one generated by usage-cli, and that script's first act is to check for the
usage binary and give up:

# @generated by usage-cli from usage spec

# if "usage" is not installed show an error
if ! type -p usage &> /dev/null
    echo "Error: usage CLI not found. This is required for completions to work in mise." >&2
    return 1

roles/fish/files/fish/config.fish:158 regenerates that file into
~/.config/fish/completions/mise.fish on every interactive shell. So the
completion file exists and looks installed, and does nothing.

The gap is invisible to the obvious check: mise doctor reports "No problems
found"
, and it is right to — from mise's point of view nothing is wrong. It is
the generated completion script, not mise, that needs the binary.

Cross-platform, not Linux-only

No Brewfile declares usage, so the Macs have exactly the same dead
completions. apt has no usage package either. That leaves mise as the route on
both platforms, which is why this goes in roles/environments/ rather than
roles/linux/files/mise/linux.toml.

Declared in two places, deliberately

usage is added to both files/mise.toml and
defaults/main.yml's environments_mise_tools.

defaults/main.yml already carries a note about this, from when lua and
rust were added to mise.toml alone:

They must be listed for the mise ls --missing gate in tasks/main.yml to
converge: an undeclared but missing tool would keep the gate open forever
without ever being installed.

A mise.toml-only version of this change would leave mise ls --missing
reporting usage on every run while the install loop never reaches it, so the
role could never reach changed=0. That convergence is precisely what
specs/dev-services Task 7 has to demonstrate, so the one-file version would
have quietly blocked it.

Verification

  • usage@5.0.0 installed on this host rather than trusting that the registry
    entry (aqua:jdx/usage) resolves. It does.
  • yamllint, gitleaks, syntax-check, ansible-lint all pass.
  • Checked that every entry in environments_mise_tools has a matching
    mise.toml entry, so this change does not reintroduce the lua/rust skew it
    cites.

Activation note

~/.config/mise.toml is a symlink into the primary checkout:

/home/inkatze/.config/mise.toml -> /home/inkatze/dev/dotfiles/roles/environments/files/mise.toml

So merging this and pulling in the primary checkout activates it directly. No
Ansible run is required for the config itself, and in particular no
mise run linux — which matters right now, because the power tasks in that
tag are currently able to deadlock the kernel on this host's Thunderbolt eGPU.
A fresh host still needs mise run environments to install the binary.

`mise completion fish` does not emit a completion script of its own. It
emits one generated by usage-cli, whose first act is to check for the
`usage` binary and bail:

    if ! type -p usage &> /dev/null
        echo "Error: usage CLI not found. This is required for
        completions to work in mise." >&2
        return 1

roles/fish/files/fish/config.fish regenerates that file into
~/.config/fish/completions/mise.fish on every interactive shell, so
without the binary the completion file exists, looks installed, and
refuses to do anything. Nothing reports the gap: `mise doctor` says "No
problems found", correctly, since from mise's own point of view nothing
is wrong. It is the generated script that needs the binary.

Cross-platform rather than Linux-only. No Brewfile declares usage, so
the Macs have the same dead completions, and apt has no usage package
either, which leaves mise as the route on both.

Declared in BOTH files/mise.toml and defaults/main.yml, which the latter
already warns about for lua and rust: an entry in mise.toml alone leaves
`mise ls --missing` reporting the tool on every run while the install
loop never reaches it, so the role could never converge to changed=0.
That convergence is what specs/dev-services Task 7 has to demonstrate,
so a one-file version of this change would have quietly blocked it.

Verified by installing 5.0.0 on this host rather than trusting the
registry entry resolves.

Claude-Session: https://claude.ai/code/session_01F8oKrXASMQSXMVjSvuJpn9
@inkatze
inkatze merged commit b43330d into main Aug 7, 2026
2 checks passed
@inkatze
inkatze deleted the chore/mise-usage-cli branch August 7, 2026 18:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant