Task Configuration

This is an exhaustive list of all the configuration options available for tasks in mise.toml or as file tasks.

Task properties

All examples are in toml-task format instead of file, however they apply in both except where otherwise noted.

run

• Type: string | (string | { task: string } | { tasks: string[] })[]

The command(s) to run. This is the only required property for a task.

You can now mix scripts with task references:

[tasks.grouped]
run = [
  { task = "t1" },          # run t1 (with its dependencies)
  { tasks = ["t2", "t3"] }, # run t2 and t3 in parallel (with their dependencies)
  "echo end",               # then run a script
]

Simple forms still work and are equivalent:

tasks.a = "echo hello"
tasks.b = ["echo hello"]
tasks.c.run = "echo hello"
[tasks.d]
run = "echo hello"
[tasks.e]
run = ["echo hello"]

run_windows

• Type: string | (string | { task: string } | { tasks: string[] })[]

Windows-specific variant of run supporting the same structured syntax:

[tasks.build]
run = "cargo build"
run_windows = "cargo build --features windows"

description

• Type: string

A description of the task. This is used in (among other places) the help output, completions, mise run (without arguments), and mise tasks.

[tasks.build]
description = "Build the CLI"
run = "cargo build"

alias

• Type: string | string[]

An alias for the task so you can run it with mise run <alias> instead of the full task name.

[tasks.build]
alias = "b" # run with `mise run b`
run = "cargo build"

depends

• Type: string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]

Tasks that must be run before this task. This is a list of task names or aliases. Arguments can be passed to the task, e.g.: depends = ["build --release"]. If multiple tasks have the same dependency, that dependency will only be run once. mise will run whatever it can in parallel (up to --jobs) through the use of depends and related properties.

[tasks.build]
run = "cargo build"
[tasks.test]
depends = ["build"]
run = "cargo test"

Passing environment variables to dependencies

You can pass environment variables to specific dependencies using two syntaxes:

Shell-style inline:

[tasks.test]
depends = ["NODE_ENV=test setup"]
run = "npm test"

[tasks.setup]
run = 'echo "Setting up for $NODE_ENV"'

Structured object format:

[tasks.test]
depends = [
  { task = "setup", env = { NODE_ENV = "test", DEBUG = "true" } }
]
run = "npm test"

The structured format also supports combining env vars with arguments:

[tasks.deploy]
depends = [
  { task = "build", args = ["--release"],
    env = { RUSTFLAGS = "-C opt-level=3" } }
]
run = "./deploy.sh"

Note: These environment variables are passed only to the specified dependency, not to the current task or other dependencies.

depends_post

• Type: string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]

Like depends but these tasks run after this task and its dependencies complete. For example, you may want a postlint task that you can run individually without also running lint:

[tasks.lint]
run = "eslint ."
depends_post = ["postlint"]
[tasks.postlint]
run = "echo 'linting complete'"

Supports the same argument and environment variable syntax as depends.

wait_for

• Type: string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]

Similar to depends, it will wait for these tasks to complete before running however they won't be added to the list of tasks to run. This is essentially optional dependencies.

[tasks.lint]
wait_for = ["render"] # creates some js files, so if it's running, wait for it to finish
run = "eslint ."

Supports the same argument and environment variable syntax as depends.

wait_for matches tasks differently depending on whether args or env vars are specified:

• wait_for = ["setup"] — matches by name, regardless of args or env overrides. If another task runs depends = ["DEBUG=1 setup"], this will still match and wait for it.
• wait_for = ["setup arg1"] or wait_for = ["DEBUG=1 setup"] — matches only tasks running with that exact args/env configuration.

env

• Type: { [key]: string | int | bool }

Environment variables specific to this task. These will not be passed to depends tasks.

[tasks.test]
env.TEST_ENV_VAR = "ABC"
run = [
    "echo $TEST_ENV_VAR",
    "mise run some-other-task", # running tasks like this _will_ have TEST_ENV_VAR set of course
]

tools

• Type: { [key]: string }

Tools to install and activate before running the task. This is useful for tasks that require a specific tool to be installed or a tool with a different version. It will only be used for that task, not dependencies.

[tasks.build]
tools.rust = "1.50.0"
run = "cargo build"

dir

• Type: string
• Default: "{{ config_root }}" - the directory containing mise.toml, or in the case of something like ~/src/myproj/.config/mise.toml, it will be ~/src/myproj.

The directory to run the task from. The most common way this is used is when you want the task to execute in the user's current directory:

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

hide

• Type: bool
• Default: false

Hide the task from help, completion, and other output like mise tasks. Useful for deprecated or internal tasks you don't want others to easily see.

[tasks.internal]
hide = true
run = "echo my internal task"

confirm

• Type: string

A message to show before running the task. This is useful for tasks that are destructive or take a long time to run. The user will be prompted to confirm before the task is run.

[tasks.release]
confirm = "Are you sure you want to cut a release?"
description = 'Cut a new release'
file = 'scripts/release.sh'

The confirm message supports Tera templates and can reference usage arguments:

[tasks.deploy]
usage = '''
arg "<environment>" help="Environment to deploy to"
flag "--force" help="Force deployment"
'''
confirm = "Deploy to {{ usage.environment }}?{% if usage.force %} (forced){% endif %}"
run = "deploy.sh ${usage_environment}"

raw

• Type: bool
• Default: false

Connects the task directly to the shell's stdin/stdout/stderr. This is useful for tasks that need to accept input or output in a way that mise's normal task handling doesn't support. This is not recommended to use because it really screws up the output whenever mise runs tasks in parallel. Ensure when using this that no other tasks are running at the same time.

In the future we could have a property like single = true or something that prevents multiple tasks from running at the same time. If that sounds useful, search/file a ticket.

sources

• Type: string | string[]

Files or directories that this task uses as input, if this and outputs is defined, mise will skip executing tasks where the modification time of the oldest output file is newer than the modification time of the newest source file. This is useful for tasks that are expensive to run and only need to be run when their inputs change.

The task itself will be automatically added as a source, so if you edit the definition that will also cause the task to be run.

This is also used in mise watch to know which files/directories to watch.

This can be specified with relative paths to the config file and/or with glob patterns, e.g.: src/**/*.rs. Ensure you don't go crazy with adding a ton of files in a glob though—mise has to scan each and every one to check the timestamp.

[tasks.build]
run = "cargo build"
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = ["target/debug/mycli"]

Running the above will only execute cargo build if mise.toml, Cargo.toml, or any ".rs" file in the src directory has changed since the last build.

The task_source_files function can be used to iterate over a task's sources within its template context.

outputs

• Type: string | string[] | { auto = true }
• Default: { auto = true }

The counterpart to sources, these are the files or directories that the task will create/modify after it executes.

auto = true is an alternative to specifying output files manually. In that case, mise will touch an internally tracked file based on the hash of the task definition (stored in ~/.local/state/mise/task-outputs/<hash> if you're curious). This is useful if you want mise run to execute when sources change but don't want to have to manually touch a file for sources to work.

[tasks.build]
run = "cargo build"
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = { auto = true } # this is the default when sources is defined

shell

• Type: string
• Default: unix_default_inline_shell_args or windows_default_inline_shell_args
• Note: Only applies to toml-tasks.

The shell to use to run the task. This is useful if you want to run a task with a different shell than the default such as fish, zsh, or pwsh. Generally though, it's recommended to use a shebang instead because that will allow IDEs with mise support to show syntax highlighting and linting for the script.

[tasks.hello]
run = '''
#!/usr/bin/env node
console.log('hello world')
'''

quiet

• Type: bool
• Default: false

Suppress mise's output for the task such as showing the command that is run, e.g.: [build] $ cargo build. When this is set, mise won't show any output other than what the script itself outputs. If you'd also like to hide even the output that the task emits, use silent.

silent

• Type: bool | "stdout" | "stderr"
• Default: false

Suppress all output from the task. If set to "stdout" or "stderr", only that stream will be suppressed.

usage

• Type: string

TIP

For comprehensive information about task arguments and the usage field, see the dedicated Task Arguments page.

More advanced usage specs can be added to the task's usage field. This only applies to toml-tasks.

[tasks.test]
usage = '''
arg "<file>" help="The file to test" default="src/main.rs"
'''
run = 'cargo test ${usage_file?}'

Environment Variable Support for Args and Flags

Both args and flags in usage specs can specify an environment variable as an alternative source for their value. This allows task arguments to be provided through environment variables when not specified on the command line.

The precedence order is:

1. CLI arguments/flags (highest priority)
2. Environment variables (middle priority)
3. Default values (lowest priority)

For positional arguments:

[tasks.deploy]
usage = '''
arg "<environment>" env="DEPLOY_ENV" help="Target environment" default="staging"
arg "<region>" env="AWS_REGION" help="AWS region" default="us-east-1"
'''

run = '''
echo "Deploying to ${usage_environment?} in ${usage_region?}"
'''

Usage examples:

# Using CLI args (highest priority)
mise run deploy production us-west-2

# Using environment variables
export DEPLOY_ENV=production
export AWS_REGION=us-west-2
mise run deploy

# Using defaults (lowest priority)
mise run deploy  # deploys to staging in us-east-1

# CLI overrides environment variable
export DEPLOY_ENV=staging
mise run deploy production  # deploys to production

For flags:

[tasks.build]
usage = '''
flag "-p --profile <profile>" env="BUILD_PROFILE" help="Build profile" default="dev"
flag "-v --verbose" env="VERBOSE" help="Verbose output"
'''

run = '''
echo "Building with profile: ${usage_profile?}"
echo "Verbose: ${usage_verbose:-false}"
'''

Usage examples:

# Using CLI flags
mise run build --profile release --verbose

# Using environment variables
export BUILD_PROFILE=release
export VERBOSE=true
mise run build

# Mixed usage - env var provides one, CLI provides another
export BUILD_PROFILE=release
mise run build --verbose

File tasks (tasks defined as executable files in mise-tasks/ or .mise/tasks/) also support the env attribute:

#!/usr/bin/env bash
#USAGE arg "<input>" env="INPUT_FILE" help="Input file to process"
#USAGE flag "-o --output <file>" env="OUTPUT_FILE" help="Output file" default="out.txt"

echo "Processing ${usage_input?} -> ${usage_output?}"

Required arguments:

Environment variables can satisfy required argument checks. If an argument is marked as required (using angle brackets <arg>), providing its value through the environment variable specified in the env attribute fulfills that requirement:

[tasks.deploy]
usage = '''
arg "<api-key>" env="API_KEY" help="API key for deployment"
'''
run = 'deploy --api-key ${usage_api_key?}'

# This will fail - no API_KEY provided
mise run deploy

# This succeeds - API_KEY provided via environment
export API_KEY=secret123
mise run deploy

# This also succeeds - provided via CLI
mise run deploy secret123

Vars

Vars are variables that can be shared between tasks like environment variables but they are not passed as environment variables to the scripts. They are defined in the vars section of the mise.toml file.

[vars]
e2e_args = '--headless'

[tasks.test]
run = './scripts/test-e2e.sh {{vars.e2e_args}}'

Like most configuration in mise, vars can be defined across several files. So for example, you could put some vars in your global mise config ~/.config/mise/config.toml, use them in a task at ~/src/work/myproject/mise.toml. You can also override those vars in "later" config files such as ~/src/work/myproject/mise.local.toml and they will be used inside tasks of any config file.

As of this writing vars are only supported in TOML tasks. I want to add support for file tasks, but I don't want to turn all file tasks into tera templates just for this feature.

[task_config] options

Options available in the top-level mise.toml [task_config] section. These apply to all tasks which are included by that config file or use the same root directory, e.g.: ~/src/myprojec/mise.toml's [task_config] applies to file tasks like ~/src/myproject/mise-tasks/mytask but not to tasks in ~/src/myproject/subproj/mise.toml.

task_config.dir

Change the default directory tasks are run from.

[task_config]
dir = "{{cwd}}"

task_config.includes

Add toml files containing toml tasks, or file tasks to include when looking for tasks.

[task_config]
includes = [
    "tasks.toml", # a task toml file
    "mytasks"     # a directory containing file tasks (in addition to the default file tasks directories)
]

If using included task toml files, note that they have a different format than the mise.toml file. They are just a list of tasks. The file should be the same format as the [tasks] section of mise.toml but without the [task] prefix:

tasks.toml

task1 = "echo task1"
task2 = "echo task2"
task3 = "echo task3"

[task4]
run = "echo task4"

If you want auto-completion/validation in included toml tasks files, you can use the following JSON schema: https://mise.jdx.dev/schema/mise-task.json

Remote Git Includes experimental

You can include directories of tasks from git repositories using the git:: URL syntax:

ssh

[task_config]
includes = [
    "git::ssh://git@github.com/myorg/shared-tasks.git//tasks?ref=v1.0.0"
]

https

[task_config]
includes = [
    "git::https://github.com/myorg/shared-tasks.git//tasks?ref=main"
]

URL format: git::<protocol>://<url>//<path>?<ref>

Required fields:

• protocol: The git protocol (ssh or https).
• url: The git repository URL.
• path: The path to the directory in the repository.

Optional fields:

• ref: The git reference (branch, tag, commit). Defaults to the repository's default branch.

The repository will be cloned and cached in MISE_CACHE_DIR/remote-git-tasks-cache. Tasks from the included directory will be loaded as if they were local file tasks. You can disable caching with MISE_TASK_REMOTE_NO_CACHE=true or the --no-cache flag.

Monorepo Support experimental

mise supports monorepo-style task organization with target path syntax. Enable it by setting experimental_monorepo_root = true in your root mise.toml.

For complete documentation on monorepo tasks including:

• Task path syntax and wildcards
• Tool layering from parent configs
• Performance tuning
• Best practices and troubleshooting

See the dedicated Monorepo Tasks documentation.

redactions experimental

• Type: string[]

Redactions are a way to hide sensitive information from the output of tasks. This is useful for things like API keys, passwords, or other sensitive information that you don't want to accidentally leak in logs or other output.

A list of environment variables to redact from the output.

redactions = ["API_KEY", "PASSWORD"]

Running the above task will output echo [redacted] instead.

You can also specify these as a glob pattern, e.g.: redactions.env = ["SECRETS_*"].

[vars] options

Vars are variables that can be shared between tasks like environment variables but they are not passed as environment variables to the scripts. They are defined in the vars section of the mise.toml file.

[vars]
e2e_args = '--headless'
[tasks.test]
run = './scripts/test-e2e.sh {{vars.e2e_args}}'

Like [env], vars can also be read in as a file:

[vars]
_.file = ".env"

Secrets are also supported as vars.

Task Configuration Settings

The following settings control task behavior. These can be set globally in ~/.config/mise/config.toml or per-project in mise.toml:

task

task.disable_paths

• Type: string[]
• Env: MISE_TASK_DISABLE_PATHS(colon separated)
• Default: []

Paths that mise will not look for tasks in.

task.disable_spec_from_run_scripts

• Type: boolean
• Env: MISE_TASK_DISABLE_SPEC_FROM_RUN_SCRIPTS
• Default: false

When enabled, arg(), option(), and flag() Tera functions in run scripts will not contribute to the task's usage spec—only the explicit usage field is used.

This is useful for:

• Skipping the extra template pass over run scripts (performance)
• Avoiding two-pass parsing quirks where template functions return empty strings during spec collection
• Early opt-out before Tera template arguments are removed in 2026.11.0

task.monorepo_depth

• Type: integer
• Env: MISE_TASK_MONOREPO_DEPTH
• Default: 5

When using monorepo mode (experimental_monorepo_root = true), this controls how deep mise will search for task files in subdirectories.

Depth levels:

• 1 = immediate children only (monorepo_root/projects/)
• 2 = grandchildren (monorepo_root/projects/frontend/)
• 5 = default (5 levels deep)

Performance tip: Reduce this value if you have a very large monorepo and notice slow task discovery. For example, if your projects are all at projects/*, set to 2.

Example:

[settings]
task.monorepo_depth = 3  # Only search 3 levels deep

Or via environment variable:

export MISE_TASK_MONOREPO_DEPTH=3

task.monorepo_exclude_dirs

• Type: string[]
• Env: MISE_TASK_MONOREPO_EXCLUDE_DIRS(comma separated)
• Default: []

If empty (default), uses default exclusions: node_modules, target, dist, build. If you specify any patterns, ONLY those patterns will be excluded (defaults are NOT included). For example, setting to [".temp", "vendor"] will exclude only those two directories.

task.monorepo_respect_gitignore

• Type: boolean
• Env: MISE_TASK_MONOREPO_RESPECT_GITIGNORE
• Default: true

When enabled, mise will skip directories that are ignored by .gitignore files when discovering tasks in a monorepo.

task.output

• Type: string(optional)
• Env: MISE_TASK_OUTPUT
• Default: None
• Choices:
  • prefix – (default if jobs > 1) print by line with the prefix of the task name
  • interleave – (default if jobs == 1 or all tasks run sequentially) print output as it comes in
  • keep-order – stream one task's output live while buffering others, printing in definition order as tasks complete
  • replacing – replace stdout each time a line is printed-this uses similar logic as `mise install`
  • timed – only show stdout lines that take longer than 1s to complete
  • quiet – print only stdout/stderr from tasks and nothing from mise
  • silent – print nothing from tasks or mise

Change output style when executing tasks. This controls the output of mise run.

task.remote_no_cache

• Type: boolean(optional)
• Env: MISE_TASK_REMOTE_NO_CACHE
• Default: None

Mise will always fetch the latest tasks from the remote, by default the cache is used.

task.run_auto_install

• Type: boolean
• Env: MISE_TASK_RUN_AUTO_INSTALL
• Default: true

Automatically install missing tools when executing tasks.

task.show_full_cmd

• Type: boolean
• Env: MISE_TASK_SHOW_CMD_NO_TRUNC
• Default: false

Disable truncation of command lines in task execution output. When true, the full command line will be shown.

task.skip

• Type: string[]
• Env: MISE_TASK_SKIP
• Default: []

Tasks to skip when running mise run.

task.skip_depends

• Type: boolean
• Env: MISE_TASK_SKIP_DEPENDS
• Default: false

Run only specified tasks skipping all dependencies.

task.source_freshness_equal_mtime_is_fresh

• Type: boolean
• Env: MISE_TASK_SOURCE_FRESHNESS_EQUAL_MTIME_IS_FRESH
• Default: false

When source mtime equals output mtime, consider sources fresh (use <=). Default false uses strict < comparison.

task.source_freshness_hash_contents

• Type: boolean
• Env: MISE_TASK_SOURCE_FRESHNESS_HASH_CONTENTS
• Default: false

Use content hashing (blake3) instead of metadata for source freshness. More accurate but slower.

task.timeout

• Type: string(optional)
• Env: MISE_TASK_TIMEOUT
• Default: None

Default timeout for tasks. Can be overridden by individual tasks.

task.timings

• Type: boolean(optional)
• Env: MISE_TASK_TIMINGS
• Default: None

Show completion message with elapsed time for each task on mise run. Default shows when output type is prefix.