docs(tasks): clarify shebang argument behavior

[jdx]

Summary

• recommend usage definitions for precise, validated task interfaces
• clarify argument forwarding for run arrays, inline shell commands, and shebang scripts
• document that shebang tasks receive normal interpreter arguments such as $1 and $@
• add E2E coverage that preserves argument boundaries for shebang TOML tasks

Motivation

Discussion #11334 highlighted that “arguments are passed to the last command” could be read as the last line of a multiline script. In the implementation, it refers to the last entry of a run array. Shebang bodies are executed as script files, so forwarded arguments are exposed through the interpreter's normal argv mechanism.

This documents the existing behavior while steering tasks that need a precise argument contract toward the usage field.

Validation

• mise run test:e2e tasks/test_task_shell
• mise run lint-fix

---

Note

Low Risk
Documentation and e2e test only; no production code paths changed.

Overview
Documents how extra task arguments are forwarded when there is no usage spec, replacing the single “last command only” line with three cases: last entry of a run array, append for inline shell, and normal script argv ($1 / $@) for shebang tasks.

Shebang section in TOML tasks gains a short explanation plus a greet example showing mise run greet world.

E2E adds bashshebangargs to assert forwarded args reach $@ with spaces preserved.

^{Reviewed by Cursor Bugbot for commit 6ca734e. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation

  • Clarified how task arguments are forwarded when no usage definition is provided.
  • Added guidance and examples for shebang-based tasks and positional script arguments.
  • Recommended defining precise, validated task interfaces with the usage field.

• Tests

  • Added coverage confirming that shebang-based tasks correctly receive multiple arguments, including arguments containing spaces.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b4cdf2a-906b-4293-b501-15a8a8a6718c

📥 Commits

Reviewing files that changed from the base of the PR and between 0703ad7 and 6ca734e.

📒 Files selected for processing (3)

• docs/tasks/running-tasks.md
• docs/tasks/toml-tasks.md
• e2e/tasks/test_task_shell

---

📝 Walkthrough

Walkthrough

The changes document task argument forwarding across execution styles, add a Bash shebang example, and verify multiple-argument handling—including spaces—with an end-to-end test.

Changes

Shebang task arguments

Layer / File(s)	Summary
Argument forwarding documentation docs/tasks/running-tasks.md, docs/tasks/toml-tasks.md	Documents validated usage interfaces and positional argument behavior for run-array, inline shell, and shebang tasks, with a Bash example.
Shebang argument forwarding test e2e/tasks/test_task_shell	Adds a Bash shebang task and verifies forwarding of multiple arguments, including an argument containing spaces.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: jambalaya56562

Poem

A bunny hops through scripts so bright,
Passing carrots left and right.
$@ carries each one through,
Even spaces make it too.
Docs and tests now dance in tune!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the main change: clarifying shebang task argument behavior in task docs and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Clarifies how extra task arguments are forwarded and adds E2E coverage for preserving argument boundaries in TOML shebang tasks.

• Recommends usage definitions for precise, validated task interfaces.
• Distinguishes argument forwarding for run arrays, inline shell commands, and shebang scripts.
• Demonstrates Bash positional arguments in the TOML task documentation.
• Adds a shebang-task assertion covering a quoted argument containing spaces and a second argument.

Confidence Score: 5/5

The PR appears safe to merge with no actionable defects identified.

The documentation matches the task runner’s shebang argument behavior, and the added E2E fixture correctly verifies separate positional arguments while preserving spaces.

Important Files Changed

Filename	Overview
docs/tasks/running-tasks.md	Accurately clarifies argument-forwarding behavior across task execution forms and points users toward validated usage interfaces.
docs/tasks/toml-tasks.md	Adds a focused shebang example showing that forwarded arguments are exposed through ordinary interpreter positional parameters.
e2e/tasks/test_task_shell	Adds valid E2E coverage confirming that shebang task arguments retain their boundaries, including embedded spaces.

_{Reviews (1): Last reviewed commit: "docs(tasks): clarify shebang argument be..." | Re-trigger Greptile}

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.14 x -- echo	18.4 ± 0.9	16.5	21.2	1.00
mise x -- echo	19.8 ± 1.6	17.5	45.7	1.08 ± 0.10

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.14 env	17.1 ± 0.9	15.5	21.9	1.00
mise env	18.2 ± 0.8	16.4	22.9	1.07 ± 0.07

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.14 hook-env	17.8 ± 0.9	16.3	22.1	1.00
mise hook-env	19.1 ± 1.0	17.4	23.2	1.08 ± 0.08

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.14 ls	15.4 ± 0.8	14.2	20.8	1.00
mise ls	16.5 ± 0.8	15.0	19.8	1.07 ± 0.08

xtasks/test/perf

Command	mise-2026.7.14	mise	Variance
install (cached)	153ms	161ms	-4%
ls (cached)	57ms	59ms	-3%
bin-paths (cached)	59ms	62ms	-4%
task-ls (cached)	121ms	127ms	-4%