docs: update task documentation (#3651)

* docs: update task documentation

* fix

* [autofix.ci] apply automated fixes

* update documentation

* fix

* typo

* fix

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

docs/faq.md

@@ -182,3 +182,13 @@ We also urge users to look after the plugins they use, and urge plugin authors t
 the users they serve.
 
 For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md).
+
+## What is usage?
+
+usage (<https://usage.jdx.dev/>) is a spec and CLI for defining CLI tools.
+
+Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like OpenAPI (swagger) for CLIs.
+
+`usage` can be installed with `mise` using `mise use -g usage` and is required to get the autocompetion working. See [autocompletion](/installing-mise.html#autocompletion).
+
+You can leverage usage in file tasks to get auto-completion working, see [file tasks arguments](/tasks/file-tasks.html#arguments).

docs/getting-started.md

@@ -23,8 +23,6 @@ You can verify the installation by running:
 
 - `~/.local/bin` does not need to be in `PATH`. mise will automatically add its own directory to `PATH`
   when activated.
-- mise respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
-  to change these locations.
 
 == Brew
 Using [brew](https://brew.sh/) package manager
@@ -41,6 +39,7 @@ winget install jdx.mise
 ```
 
 ```shell [scoop]
+# https://github.com/ScoopInstaller/Main/pull/6374
 scoop install mise
 ```
 
@@ -60,7 +59,7 @@ sudo apt install -y mise
 ```
 
 ```sh [arm64]
-sudo apt update -y && apt install -y gpg sudo wget curl
+sudo apt update -y && sudo apt install -y gpg sudo wget curl
 sudo install -dm 755 /etc/apt/keyrings
 wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
 echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/mise.list
@@ -70,6 +69,9 @@ sudo apt install -y mise
 
 :::
 
+`mise` respects [`MISE_DATA_DIR`](/configuration) and [`XDG_DATA_HOME`](/configuration) if you'd like
+to change these locations.
+
 ## 2. Activate `mise`
 
 Now that `mise` is installed, you can optionally activate it or add its [shims](dev-tools/shims.md) to `PATH`.
@@ -118,14 +120,14 @@ echo 'eval "$(/opt/homebrew/bin/mise activate zsh)"' >> ~/.zshrc
 ```
 
 - Activation will be handled automatically if you use `fish` shell and installed via `homebrew`. This can be disabled with `set -Ux MISE_FISH_AUTO_ACTIVATE 0`.
-- Make sure you restart your shell session after modifying your rc file in order for it to take effect.-
+- Make sure you restart your shell session after modifying your rc file in order for it to take effect.
 
 == Windows
 
 Only shims are supported for now on Windows.
 
 - When using `scoop`, the shims are automatically added to your `PATH`.
-- With `winget`, Add this directory to PATH: `<homedir>\AppData\Local\mise\shims`.
+- With `winget`, you need to add `<homedir>\AppData\Local\mise\shims` to your `PATH`.
 
   ```powershell
   $shimPath = "$env:USERPROFILE\AppData\Local\mise\shims"

docs/tasks/file-tasks.md

@@ -8,7 +8,7 @@ In addition to defining tasks through the configuration, they can also be define
 - `.mise/tasks/:task_name`
 - `.config/mise/tasks/:task_name`
 
-Note that you can include additional directories using the [task_config](/tasks/#task-configuration) section.
+Note that you can include additional directories using the [task_config](/tasks/task-configuration.html#task-config-options) section.
 
 Here is an example of a file task that builds a Rust CLI:
 
@@ -35,7 +35,7 @@ of course they'll need to find a different way to install their dev tools the ta
 
 ## Task Configuration
 
-The same configuration options as for [TOML tasks](/tasks/toml-tasks.html) are supported.
+All configuration options can be found here [task configuration](/tasks/task-configuration)
 You can provide additional configuration for file tasks by adding `#MISE` comments at the top of the file.
 
 ```bash
@@ -58,18 +58,21 @@ You can also use it to run the script with various programming languages.
 
 ```js [node]
 #!/usr/bin/env node
+//MISE description="Hello, World in Node.js"
 
 console.log("Hello, World!");
 ```
 
 ```python
 #!/usr/bin/env python
+#MISE description="Hello, World in Python"
 
 print('Hello, World!')
 ```
 
 ```ts [deno]
 #!/usr/bin/env -S deno run --allow-env
+//MISE description="Hello, World in Deno"
 
 console.log(`PATH, ${Deno.env.get("PATH")}`);
 ```
@@ -87,9 +90,7 @@ File tasks in `mise-tasks`, `.mise/tasks`, `mise/tasks`, or `.config/mise/tasks`
 sub-directories which will automatically apply prefixes to their names
 when loaded.
 
-### Example
+**Example**: With a folder structure like below:
-
-With a folder structure like below:
 
 ```text
 mise-tasks
@@ -120,6 +121,8 @@ The `usage` CLI is not required to execute mise tasks with the usage spec.
 However, for completions to work, the `usage` CLI must be installed and available in the PATH.
 :::
 
+### Example file task with arguments
+
 Here is an example of a file task that builds a Rust CLI using some of the features of usage:
 
 ```bash [mise-tasks/build]
@@ -141,11 +144,68 @@ fi
 cargo build --profile "${usage_profile:-debug}" --target "$usage_target"
 ```
 
-Completions will now be enabled for your task. In this example, `mise run build --profile <tab><tab>`
+If you have installed `usage`, completions will be enabled for your task. In this example,
-will show `debug` and `release` as options. The `--user` flag will also show completions generated by the output of `mycli users`.
+
+- `mise run build --profile <tab><tab>`
+  will show `debug` and `release` as options.
+- The `--user` flag will also show completions generated by the output of `mycli users`.
 
 (Note that cli and markdown help for tasks is not yet implemented in mise as of this writing but that is planned.)
 
+:::tip
+If you don't get any autocomplete suggestions, use the `-v` (verbose) flag to see what's going on.
+For example, if you use `mise run build -v` and have an invalid `usage` spec, you will see an error message such as `DEBUG failed to parse task file with usage`
+:::
+
+### Example of a NodeJS file task with arguments
+
+Here is how you can use [usage](https://usage.jdx.dev/cli/scripts#usage-scripts) to parse arguments in a Node.js script:
+
+```js [mise-tasks/greet]
+#!/usr/bin/env -S node
+//MISE description="Write a greeting to a file"
+//USAGE flag "-f --force" help="Overwrite existing <file>"
+//USAGE flag "-u --user <user>" help="User to run as"
+//USAGE arg "<output_file>" help="The file to write" default="file.txt" {
+//USAGE   choices "greeting.txt" "file.txt"
+//USAGE }
+
+const fs = require("fs");
+
+const { usage_user, usage_force, usage_output_file } = process.env;
+
+if (usage_force === "true") {
+  fs.rmSync(usage_file, { force: true });
+}
+
+const user = usage_user ?? "world";
+fs.appendFileSync(usage_file, `Hello, ${user}\n`);
+console.log(`Greeting written to ${usage_file}`);
+```
+
+Run it with:
+
+```shell
+mise run greet greeting.txt --user Alice
+# Greeting written to file.txt
+```
+
+If you pass an invalid argument, you will get an error message:
+
+```shell
+mise run greet invalid.txt --user Alice
+# [greet] ERROR
+#   0: Invalid choice for arg output_file: invalid.txt, expected one of greeting.txt, file.txt
+```
+
+Autocomplete will show the available choices for the `output_file` argument if `usage` is installed.
+
+```shell
+mise run <TAB>
+# > greeting.txt
+#   file.txt
+```
+
 ## CWD
 
 mise sets the current working directory to the directory of `mise.toml` before running tasks.

docs/tasks/toml-tasks.md

@@ -43,7 +43,27 @@ description = 'Cut a new release'
 file = 'scripts/release.sh' # execute an external script
 ```
 
-## run
+## Adding tasks
+
+You can edit the `mise.toml` file directly or using [`mise tasks add`](/cli/tasks/add)
+
+```shell
+mise task add pre-commit --depends "test" --depends "render" -- echo pre-commit
+```
+
+will add the following to `mise.toml`:
+
+```shell
+[tasks.pre-commit]
+depends = ["test", "render"]
+run = "echo pre-commit"
+```
+
+## Common options
+
+For an exhaustive list, see [task configuration](/tasks/task-configuration).
+
+### Run command
 
 Provide the script to run. Can be a single command or an array of commands:
 
@@ -62,8 +82,6 @@ run = [
 ]
 ```
 
-### run_windows
-
 You can specify an alternate command to run on Windows by using the `run_windows` key:
 
 ```toml
@@ -72,7 +90,7 @@ run = 'cargo test'
 run_windows = 'cargo test --features windows'
 ```
 
-## dir
+### Specifying which directory to use
 
 Tasks are executed with `cwd` set to the directory containing `mise.toml`. You can use the directory
 from where the task was run with `dir = "{{cwd}}"`:
@@ -85,17 +103,19 @@ dir = "{{cwd}}"
 
 Also, `MISE_ORIGINAL_CWD` is set to the original working directory and will be passed to the task.
 
-## description
+### Adding a description and alias
 
-You can add a description to a task:
+You can add a description to a task and alias for a task.
 
 ```toml
 [tasks.build]
 description = 'Build the CLI'
 run = "cargo build"
+alias = 'b' # `mise run b`
 ```
 
-The description will for example be displayed when running [`mise tasks ls`](/cli/tasks/ls.html) or [`mise run`](/cli/run.html)` with no arguments.
+- This alias can be used to run the task
+- The description will be displayed when running [`mise tasks ls`](/cli/tasks/ls.html) or [`mise run`](/cli/run.html)` with no arguments.
 
 ```shell
 ❯ mise run
@@ -105,7 +125,7 @@ Tasks
 #   test   Run the tests
 ```
 
-## depends
+### Dependencies
 
 You can specify dependencies for a task. Dependencies are run before the task itself. If a dependency fails, the task will not run.
 
@@ -117,41 +137,9 @@ run = 'cargo build'
 depends = ['build']
 ```
 
-## wait_for
+There are other ways to specify dependencies, see [wait_for](/tasks/task-configuration.html#wait-for) and [depends_post](/tasks/task-configuration.html#depends-post)
 
-If a task must run after another task, you can use `wait_for`:
+### Environment variables
-
-```toml
-[tasks.clean]
-run = 'cargo clean'
-
-[tasks.build]
-run = 'cargo build'
-wait_for = ['clean']
-```
-
-## hide
-
-You can hide a task from the list of available tasks by setting `hide = true`:
-
-```toml
-[tasks.cleancache]
-run = "rm -rf .cache"
-hide = true # hide this task from mise tasks ls / mise run
-```
-
-## alias
-
-You can specify an alias for a task. This alias can be used to run the task:
-
-```toml
-[tasks.build]
-description = 'Build the CLI'
-run = "cargo build"
-alias = 'b' # `mise run b`
-```
-
-## env
 
 You can specify environment variables for a task:
 
@@ -166,7 +154,7 @@ cargo clippy
 """
 ```
 
-## sources / outputs
+### Sources / Outputs
 
 If you want to skip executing a task if certain files haven't changed (up-to-date), you should specify `sources` and `outputs`:
 
@@ -180,7 +168,7 @@ outputs = ['target/debug/mycli']
 
 You can use `sources` alone if with [`mise watch`](/cli/watch.html) to run the task when the sources change.
 
-## shell / shebang
+## Specifying a shell or an interpreter
 
 Tasks are executed with `set -e` (`set -o erropt`) if the shell is `sh`, `bash`, or `zsh`. This means that the script
 will exit if any command fails. You can disable this by running `set +e` in the script.
@@ -334,7 +322,7 @@ Example: `#!/usr/bin/env -S python -u` will run Python with unbuffered output.
 
 :::
 
-## file
+## Using a file or remote script
 
 You can specify a file to run as a task:
 
@@ -356,21 +344,6 @@ file = "https://example.com/build.sh"
 Currently, they're fetched everytime they're executed, but we may add some cache support later.
 This could be extended with other protocols like mentioned in [this ticket](https://github.com/jdx/mise/issues/2488) if there were interest.
 
-## raw
-
-Stdin is not read by default. To enable this, set `raw = true` on the task that needs it. This will prevent
-it running in parallel with any other task. A RWMutex will get a write lock in this case.
-
-```toml
-[tasks.build]
-raw = true
-run = 'echo "Enter your name:"; read name; echo "Hello, $name!"'
-```
-
-## quiet
-
-Set `quiet = true` to suppress mise additional output.
-
 ## Arguments
 
 By default, arguments are passed to the last script in the `run` array. So if a task was defined as:

docs/walkthrough.md

@@ -126,9 +126,11 @@ _See [Environments](/environments/) for more information on working with environ
 
 ## Tasks
 
-Tasks are defined in a project to execute commands. They are defined in `mise.toml`:
+Tasks are defined in a project to execute commands.
 
-```toml
+You can define tasks in a `mise.toml`:
+
+```toml [mise.toml]
 [tasks]
 build = "npm run build"
 test = "npm test"
@@ -149,35 +151,47 @@ mise run test
 ```
 
 :::tip
-`mise run` setups up the "mise environment" before running the task (tools and environment variables).
+`mise run` sets up the "mise environment" before running the task (tools and environment variables).
 So if you'd rather not activate mise in your shell, you can use `mise run` to run tasks, and it will
 have the tools in PATH and the environment variables from `mise.toml` set.
 :::
 
-mise is paired with [usage](https://usage.jdx.dev) which provides lots of features for documenting and running tasks.
+`mise` is paired with [usage](https://usage.jdx.dev) which provides lots of features for documenting and running tasks.
 
 Here is an example of a task with usage spec:
 
-```bash [mise-tasks/users]
+```bash [mise-tasks/greet]
-#!/bin/bash
+#!/usr/bin/env bash
-#USAGE flag "-f --force" "Force the greeting to be displayed"
+set -e
-#USAGE flag "-u --user <user>" "The user to greet"
-#USAGE flag "-p --port <port>" default=8080 "The port to listen on"
-#USAGE flag "-c --color <color>" "The color to use" {
-#USAGE     choices "red" "green" "blue"
-#USAGE }
-#USAGE arg "message" "The message to greet the user with"
-#USAGE complete "user" run="mycli users"
 
-echo "Hello, $usage_user! Your message is: $usage_message"
+#MISE description="Greet a user with a message"
+#USAGE flag "-g --greeting <greeting>" help="The greeting word to use" {
+#USAGE   choices "hi" "hello" "hey"
+#USAGE }
+#USAGE flag "-u --user <user>" help="The user to greet"
+#USAGE flag "--dir <dir>" help="The directory to greet from" default="."
+#USAGE complete "dir" run="find . -maxdepth 1 -type d"
+#USAGE arg "<message>" help="Greeting message"
+
+echo "all available options are in the env with the prefix 'usage_'"
+env | grep usage_
+
+echo "$usage_greeting, $usage_user! Your message is: $usage_message"
 ```
 
-The options will all be passed as environment variables prefixed with `usage_` like `usage_user`.
+This task can be run like so:
-Help is available with `mise run my-task --help` and will show the options defined in the task.
-Completions are available like you'd expect, so typing `mise run my-task --color <tab>` will show "red", "green", and "blue"
-as options. `mise run my-task --user <tab>` will execute `mycli users` and use the output as completions.
 
-No extra setup is required for completions so long as [mise completions](/cli/completion) are otherwise set up.
+```shell
+mise run greet --user jdx -g "hey" "How are you?"
+```
+
+- The options will all be passed as environment variables prefixed with `usage_` like `usage_user`.
+- Help is available with `mise run greet --help` and will show the options defined in the task.
+- Completions are available like you'd expect, so typing `mise run greet --greeting <tag>` will show `hi`, `hello`, and `hey`
+  as options.
+- [Custom completion](https://usage.jdx.dev/spec/reference/complete) can be provided by a CLI. `mise run greet --dir <tab>` will execute `find . -maxdepth 1 -type d` to provide completions.
+
+To get the autocopletion working, set up [mise autocompletions](/installing-mise.html#autocompletion).
 
 _See [Tasks](/tasks/) for more information on working with tasks._