Skip to content

TOML-based Tasks

Tasks can be defined in mise.toml files in different ways:

toml
[tasks.cleancache]
run = "rm -rf .cache"
hide = true # hide this task from the list

[tasks.clean]
depends = ['cleancache']
run = "cargo clean" # runs as a shell command

[tasks.build]
description = 'Build the CLI'
run = "cargo build"
alias = 'b' # `mise run b`

[tasks.test]
description = 'Run automated tests'
run = [# multiple commands are run in series
    'cargo test',
    './scripts/test-e2e.sh',
]
dir = "{{cwd}}" # run in user's cwd, default is the project's base directory

[tasks.lint]
description = 'Lint with clippy'
env = { RUST_BACKTRACE = '1' } # env vars for the script
# specify a shell command to run the script with (default is 'sh -c')
shell = 'bash -c'
# you can specify a multiline script instead of individual commands
run = """
#!/usr/bin/env bash
cargo clippy
"""

[tasks.ci] # only dependencies to be run
description = 'Run CI tasks'
depends = ['build', 'lint', 'test']

[tasks.release]
description = 'Cut a new release'
file = 'scripts/release.sh' # execute an external script

Task execution

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.

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 = "":

toml
[tasks.test]
run = 'cargo test'
dir = "{{cwd}}"

Also, MISE_ORIGINAL_CWD is set to the original working directory and will be passed to the task.

Arguments

By default, arguments are passed to the last script in the run array. So if a task was defined as:

toml
[tasks.test]
run = ['cargo test', './scripts/test-e2e.sh']

Then running mise run test foo bar will pass foo bar to ./scripts/test-e2e.sh but not to cargo test.

You can also define arguments using templates:

toml
[tasks.test]
run = [
    'cargo test {{arg(name="cargo_test_args", var=true)}}',
    './scripts/test-e2e.sh {{option(name="e2e_args")}}',
]

Then running mise run test foo bar will pass foo bar to cargo test. mise run test --e2e-args baz will pass baz to ./scripts/test-e2e.sh. If any arguments are defined with templates then mise will not pass the arguments to the last script in the run array.

TIP

Using templates to define arguments will make them work with completion and help messages.

Positional Arguments

These are defined in scripts with {{arg()}}. They are used for positional arguments where the order matters.

Example:

toml
[tasks.test]
run = 'cargo test {{arg(name="file")}}'
# execute: mise run test my-test-file
# runs: cargo test my-test-file
  • i: The index of the argument. This can be used to specify the order of arguments. Defaults to the order they're defined in the scripts.
  • name: The name of the argument. This is used for help/error messages.
  • var: If true, multiple arguments can be passed.
  • default: The default value if the argument is not provided.

Options

These are defined in scripts with {{option()}}. They are used for named arguments where the order doesn't matter.

Example:

toml
[tasks.test]
run = 'cargo test {{option(name="file")}}'
# execute: mise run test --file my-test-file
# runs: cargo test my-test-file
  • name: The name of the argument. This is used for help/error messages.
  • var: If true, multiple values can be passed.
  • default: The default value if the option is not provided.

Flags

Flags are like options except they don't take values. They are defined in scripts with {{flag()}}.

Example:

toml
[tasks.echo]
run = 'echo {{flag(name=("myflag")}}'
# execute: mise run echo --myflag
# runs: echo true
  • name: The name of the flag. This is used for help/error messages.

The value will be true if the flag is passed, and false otherwise.

Windows

You can specify an alternate command to run on Windows by using the run_windows key:

toml
[tasks.test]
run = 'cargo test'
run_windows = 'cargo test --features windows'

Licensed under the MIT License. Maintained by @jdx and friends.