fix(cli): intercept --help flag to show task help instead of executing task

[jdx]

Summary

Fixes the issue where mise run --cd <dir> <task> --help would execute the task with --help as an argument instead of displaying help for the task.

Problem

When running commands like:

mise run --cd services/coder/templates push-devbox --help

The --help flag was being passed to the task script as an argument, causing the task to run instead of showing help. This was particularly problematic for tasks without usage specifications (no arg() calls).

Solution

• Intercept --help and -h flags in Run::run() before task execution
• Use usage::docs::cli::render_help() to consistently display task help
• Works for both mise run task --help and naked runs like mise task --help

Changes

1. Modified src/cli/run.rs:

   • Added early check for --help/-h in args before task execution
   • Strip these flags from args and resolve the task
   • Render help using the usage library's help renderer

2. Added e2e/tasks/test_task_help_with_cd:

   • Tests --help with --cd flag
   • Tests both tasks with and without usage specifications
   • Verifies help is shown instead of task execution

3. Updated e2e/tasks/test_task_help:

   • Reflects new behavior where --help always shows help
   • Updated assertions for tasks without usage specs

Behavior Changes

Before: Tasks without usage specs would pass --help to the script

$ mise run build --help
[build] $ echo "Building project" --help
Building project --help

After: All tasks show help when --help is provided

$ mise run build --help
Usage: build

$ mise run deploy --help
Usage: deploy <env>

Arguments:
  <env>

Testing

• ✅ Existing tests pass with updated assertions
• ✅ New test covers --cd flag usage
• ✅ Lint checks pass

🤖 Generated with Claude Code

---

Note

Intercepts --help/-h in mise run to display task help (respecting -- passthrough), adds --cd e2e coverage, and updates help-related tests.

• CLI run behavior:
  • In src/cli/run.rs, detect --help/-h in self.args before execution (excluding args after --), strip them, resolve the task, and render help via usage::docs::cli::render_help; fallback to run command help if no task is found.
• Tests:
  • Add e2e/tasks/test_task_help_with_cd to verify mise run --cd <dir> <task> --help, passthrough behavior with --, and tasks with/without usage specs.
  • Update e2e/tasks/test_task_help to assert help is shown for tasks (including extra args) and to clarify -- passes --help to the task script.

^{Written by Cursor Bugbot for commit a2161bf. This will update automatically on new commits. Configure here.}

[Copilot]

Pull Request Overview

This PR fixes a bug where mise run --cd <dir> <task> --help would execute the task with --help as an argument instead of displaying the task's help information.

Key Changes:

• Added early interception of --help/-h flags in Run::run() to show task help before execution
• Modified behavior to consistently display help for all tasks, regardless of whether they have usage specifications
• Added test coverage for the --cd flag scenario and updated existing help tests

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/cli/run.rs	Intercepts --help/-h flags before task execution and renders help using the usage library
e2e/tasks/test_task_help_with_cd	New test verifying --help works correctly with --cd flag for tasks with and without usage specs
e2e/tasks/test_task_help	Updated assertions to reflect new behavior where --help always shows help instead of being passed to task scripts

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

After removing --help/-h from self.args on lines 209-210, these flags are still present in self.args_last. The args construction here doesn't use self.args_last, which could cause the task resolution to miss arguments that were originally in self.args_last. Consider chaining self.args_last as well, similar to how it's done elsewhere in the run logic.

Suggested change

	.chain(self.args.clone())
	.chain(self.args.clone())
	.chain(self.args_last.clone())

[Copilot]

Mutating self.args and self.args_last could have unintended side effects if these fields are used later. Consider using local variables with filtered values instead of mutating the struct fields directly.

Suggested change

	// Remove --help/-h from args to get the task
	self.args.retain(|arg| arg != "--help" && arg != "-h");
	self.args_last.retain(|arg| arg != "--help" && arg != "-h");
	// Build args list to get the task
	let args = once(self.task.clone())
	.chain(self.args.clone())
	// Remove --help/-h from args to get the task using local variables
	let filtered_args = self.args.iter().filter(|arg| *arg != "--help" && *arg != "-h").cloned();
	let filtered_args_last = self.args_last.iter().filter(|arg| *arg != "--help" && *arg != "-h").cloned();
	// Build args list to get the task
	let args = once(self.task.clone())
	.chain(filtered_args)

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.3 x -- echo	19.1 ± 1.6	18.0	37.4	1.02 ± 0.09
mise x -- echo	18.6 ± 0.3	18.0	19.9	1.00

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.3 env	18.0 ± 0.4	17.4	21.7	1.00
mise env	18.3 ± 0.4	17.6	21.3	1.02 ± 0.03

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.3 hook-env	18.2 ± 0.7	17.5	29.1	1.00
mise hook-env	18.5 ± 0.5	17.7	21.6	1.01 ± 0.05

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.3 ls	16.0 ± 0.5	15.2	17.4	1.00
mise ls	16.0 ± 0.7	15.1	24.1	1.00 ± 0.05

xtasks/test/perf

Command	mise-2025.11.3	mise	Variance
install (cached)	104ms	105ms	+0%
ls (cached)	66ms	66ms	+0%
bin-paths (cached)	72ms	73ms	-1%
task-ls (cached)	420ms	426ms	-1%