invalid global options appearing in task shell completion

[twelvelabs]

I have a file based task w/ the following usage comments:

# [USAGE] flag "--env <name>" {
# [USAGE]   choices     "dev" "stage" "prod"
# [USAGE]   default     "dev"
# [USAGE] }
# [USAGE] flag "--bump <type>" {
# [USAGE]   choices     "auto" "major" "minor" "patch"
# [USAGE]   default     "auto"
# [USAGE] }
# [USAGE] flag "--output-dir <path>" {
# [USAGE] }

When triggering shell completion for it, I see a number of global options (in addition to the above):

$ mise run my:task --<tab><tab>

--bump        --env         --locked      --quiet       --silent      --yes         
--cd          --jobs        --output-dir  --raw         --verbose     

There are two issues:

1. Global options do not appear to be usable after the task name (only if placed before it):

$ mise run my:task --silent

[my:task] ERROR unexpected word: --silent
[my:task] ERROR task failed

2. Global options seem to be intercepting completion for options defined in the task. For example, trying to complete the env names defined above fails when the flag is named --env:

mise run my:task --env <tab><tab>

# lists files in the current directory 

... but works as expected when I change the option to --environment:

mise run my:task --environment <tab><tab>

dev    stage  prod   

I would expect mise to only offer valid completion options (and not intercept the ones from my task). 🤷

Output from mise doctor:

version: 2026.7.13 macos-arm64 (2026-07-24)
activated: yes
shims_on_path: yes
self_update_available: no

build_info:
  Target: aarch64-apple-darwin
  Features: default, native-tls, self_update
  Built: Fri, 24 Jul 2026 15:04:13 +0000
  Rust Version: rustc 1.97.1 (8bab26f4f 2026-07-14) (Homebrew)
  Profile: release

shell:
  /opt/homebrew/bin/bash
  GNU bash, version 5.3.15(1)-release (aarch64-apple-darwin25.4.0)
  Copyright (C) 2025 Free Software Foundation, Inc.
  License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

Note: I installed mise, bash (v5), and bash-completion@2 all from Homebrew.

[yhay81]

Your expectation is correct. This is a completion-spec bug, not a problem with the [USAGE] block.

The source explains both symptoms:

• top-level Cli defines --env/-E, --cd, --jobs, --locked, --quiet, --raw, --silent, --verbose, and --yes as global options;
• mise run defines positional task followed by variadic args, both with Clap's allow_hyphen_values = true.

Once the task name has been consumed, hyphen-prefixed words are deliberately task arguments. That is what allows a task to receive its own --env, --bump, etc. Consequently a mise/run option must be placed before the task positional:

mise --silent run my:task
# or
mise run --silent my:task

mise run my:task --silent is expected to pass --silent to my:task, so the task usage parser rejects it unless that task declares such a flag.

The incorrect part is completion: the generated usage tree continues offering the global/run flags after [TASK], although at that position they are no longer mise options. The --env name then collides with the global mise --env definition, and that definition wins the completion lookup; because it has no task choices, Bash falls back to filename completion. Renaming it to --environment avoids the collision, exactly as you observed.

Practical workarounds until this is fixed:

1. keep mise options before the task name;
2. rename the task flag to a non-global name such as --environment, or give the task an unambiguous short flag;
3. after upgrading to a release containing a completion fix, remove the cached generated spec once so Bash regenerates it:

rm -f "${TMPDIR:-/tmp}"/usage__usage_spec_mise_*.spec

The relevant generated Bash completion calls usage complete-word with the whole mise usage spec, while src/cli/mod.rs defines the global --env and src/cli/run.rs defines the hyphen-accepting task/args boundary. A correct fix should make completion enter the selected task's usage scope after [TASK] and stop suggesting mise/run flags there; it should also prefer the task-local flag when names collide in that scope.

So I would keep the report open as two related completion defects: stale parent-option suggestions after the task positional, and wrong-scope resolution of a task flag that shadows mise --env.

[jdx]

Thanks for the detailed report — both issues reproduce, and they turned out to be the same root cause. @yhay81's analysis above is spot on, including the part about allow_hyphen_values on run's positionals.

Status: fixed on both sides. The parser fix is released in usage 3.5.7 (jdx/usage#738), and the mise side (jdx/mise#11284) is merged — it will ship in the next mise release, after 2026.7.13.

What was happening. mise builds its completion spec by mounting your tasks into it, via mise tasks --usage. The usage parser was inheriting mise's own global flags into those mounted task commands, and an inherited global also took precedence over a task flag with the same name. That produced both symptoms: --cd/--env/--jobs/--silent/... were offered after the task name, and your --env was shadowed by mise's -E/--env, so completing its value fell through to file completion. Renaming to --environment worked because it no longer collided — good deduction on your part, that's what pinned it down.

On point 1, one part is intended and won't change: everything after the task name is forwarded to the task, so mise's own flags have to come before it — mise run --silent my:task, not mise run my:task --silent. That's what lets tasks define their own --silent, --env and so on. The bug was purely that completion offered them in a position where they can't work. The docs now say this explicitly.

After the fix, with your task unchanged:

$ mise run my:task --<TAB>
--bump  --env  --output-dir

$ mise run my:task --env <TAB>
dev  stage  prod

Same on mise tasks run my:task and the bare mise my:task form. No need to keep the --environment rename.

One more thing your report shook out: any non-global run flag placed before the task name was killing completion entirely — mise run --force build <TAB> failed with unexpected word: build and offered nothing, likewise for -f, -o <mode>, -n, -s, -t, --timeout. The parser stopped scanning for the task at the first such flag, so it never found it. Fixed in the same release.

Upgrading. Both halves are needed: a mise version containing #11284, and usage >= 3.5.7. If you installed usage through mise, note that mise up usage won't pick up 3.5.7 until it's 24h old — that's the minimum_release_age supply-chain default. mise use -g usage@3.5.7 gets it immediately. Homebrew users just need brew upgrade usage. Once mise itself is updated, it will warn during completion if the usage it finds is older than 3.5.7.

This comment was generated by an AI coding assistant.