MISE(1) General Commands Manual MISE(1)

mise - The front-end to your dev env

mise [OPTIONS] [<TASK>] [<TASK_ARGS>] ... [<TASK_ARGS_LAST>] ... [COMMAND]

mise manages dev tools, env vars, and runs tasks. https://github.com/jdx/mise

Continue running tasks even if one fails
Change directory before running command
Set the environment for loading `mise.<ENV>.toml`
Force the operation
Set the log output verbosity
How many jobs to run in parallel [default: 8]
Dry run, don't actually do anything
Set the profile (environment)
Suppress non-error messages
Tool(s) to run in addition to what is in mise.toml files e.g.: node@20 python@3.10
Show extra output (use -vv for even more)
Answer yes to all confirmation prompts
Sets log level to debug
Do not load any config files

Can also use `MISE_NO_CONFIG=1`

Do not load environment variables from config files

Can also use `MISE_NO_ENV=1`

Do not execute hooks from config files

Can also use `MISE_NO_HOOKS=1`

Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

Read/write directly to stdin/stdout/stderr instead of by line
Require lockfile URLs to be present during installation

Fails if tools don't have pre-resolved URLs in the lockfile for the current platform. This prevents API calls to GitHub, aqua registry, etc. Can also be enabled via MISE_LOCKED=1 or settings.locked=true

Suppress all task output and mise non-error messages
Shows elapsed time after each task completes

Default to always show with `MISE_TASK_TIMINGS=1`

Sets log level to trace

<TASK>
Task to run.

Shorthand for `mise tasks run <TASK>`.

<TASK_ARGS>
Task arguments

Initializes mise in the current shell session
Manage tool version aliases.
Show an alias for a plugin
List tool version aliases
Aliases: list
Add/update an alias for a backend/plugin
Aliases: add, create
Clears an alias for a backend/plugin
Aliases: rm, remove, delete, del
Manage backends
Aliases: b
List built-in backends
Aliases: list
List all the active runtime bin paths
Manage the mise cache
Deletes all cache files in mise
Aliases: c
Show the cache directory path
Aliases: dir
Removes stale mise cache files
Aliases: p
Generate shell completions
Manage config files
Aliases: cfg
Display the value of a setting in a mise.toml file
List config files currently in use
Aliases: list
Set the value of a setting in a mise.toml file
Disable mise for current shell session
Check mise installation for possible problems
Aliases: dr
Print the current PATH entries mise is providing
Starts a new shell with the mise environment built from the current configuration
Exports env vars to activate mise a single time
Aliases: e
Execute a command with tool(s) set
Aliases: x
Formats mise.toml
Generate files for various tools/services
Aliases: gen
Generate a script to download+execute mise
Generate a mise.toml file
Generate a devcontainer to execute mise
Generate a git pre-commit hook
Aliases: pre-commit
Generate a GitHub Action workflow file
Generate documentation for tasks in a project
Generates shims to run mise tasks
Generate a tool stub for HTTP-based tools
Removes mise CLI and all related data
Edit mise.toml interactively
Install a tool version
Aliases: i
Install a tool version to a specific path
Gets the latest available version for a plugin
Symlinks a tool version into mise
Aliases: ln
Update lockfile checksums and URLs for all specified platforms
List installed and active tool versions
Aliases: list
List runtime versions available for install.
[experimental] Run Model Context Protocol (MCP) server
Shows outdated tool versions
Manage plugins
Aliases: p
Install a plugin
Aliases: i, a, add
Symlinks a plugin into mise
Aliases: ln
List installed plugins
Aliases: list
Aliases: list-remote, list-all
Removes a plugin
Aliases: remove, rm
Updates a plugin to the latest version
Aliases: up, upgrade
[experimental] Ensure project dependencies are ready
Aliases: prep
Delete unused versions of tools
List available tools to install
Creates new shims based on bin paths from currently installed tools.
Run task(s)
Aliases: r
Search for tools in the registry
Updates mise itself.
Set environment variables in mise.toml
Show current settings
Adds a setting to the configuration file
Show a current setting
Show current settings
Aliases: list
Add/update a setting
Aliases: create
Clears a setting
Aliases: rm, remove, delete, del
Sets a tool version for the current session.
Aliases: sh
Manage shell aliases.
Show the command for a shell alias
List shell aliases
Aliases: list
Add/update a shell alias
Aliases: add, create
Removes a shell alias
Aliases: rm, remove, delete, del
Synchronize tools from other version managers with mise
Symlinks all tool versions from an external tool into mise
Symlinks all tool versions from an external tool into mise
Symlinks all ruby tool versions from an external tool into mise
Manage tasks
Aliases: t
Create a new task
Display a tree visualization of a dependency graph
Edit a task with $EDITOR
Get information about a task
List available tasks to execute
Run task(s)
Aliases: r
Validate tasks for common errors and issues
Test a tool installs and executes
Gets information about a tool
Execute a tool stub
Marks a config file as trusted
Removes installed tool versions
Remove environment variable(s) from the config file.
Removes installed tool versions from mise.toml
Aliases: rm, remove
Upgrades outdated tools
Aliases: up
Installs a tool and adds the version to mise.toml.
Aliases: u
Display the version of mise
Aliases: v
Run task(s) and watch for changes to rerun it
Aliases: w
Display the installation path for a tool
Shows the path that a tool's bin points to.

Initializes mise in the current shell session

This should go into your shell's rc file or login shell. Otherwise, it will only take effect in the current session. (e.g. ~/.zshrc, ~/.zprofile, ~/.zshenv, ~/.bashrc, ~/.bash_profile, ~/.profile, ~/.config/fish/config.fish, or $PROFILE for powershell)

Typically, this can be added with something like the following:


echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

However, this requires that "mise" is in your PATH. If it is not, you need to specify the full path like this:


echo 'eval "$(/path/to/mise activate zsh)"' >> ~/.zshrc

Customize status output with `status` settings.

Usage: mise activate [OPTIONS] [<SHELL_TYPE>]

Options:

Suppress non-error messages
Shell type to generate the script for
Do not automatically call hook-env

This can be helpful for debugging mise. If you run `eval "$(mise activate --no-hook-env)"`, then you can call `mise hook-env` manually which will output the env vars to stdout without actually modifying the environment. That way you can do things like `mise hook-env --trace` to get more information or just see the values that hook-env is outputting.

Use shims instead of modifying PATH Effectively the same as:


PATH="$HOME/.local/share/mise/shims:$PATH"

`mise activate --shims` does not support all the features of `mise activate`. See https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path for more information

Show "mise: <PLUGIN>@<VERSION>" message when changing directories Arguments:
<SHELL_TYPE>
Shell type to generate the script for

Manage tool version aliases.

Usage: mise tool-alias [OPTIONS] [COMMAND]

Options:

filter aliases by plugin
Don't show table header

Show an alias for a plugin

This is the contents of a tool_alias.<PLUGIN> entry in ~/.config/mise/config.toml

Usage: mise tool-alias get <PLUGIN> <ALIAS>

Arguments:

<PLUGIN>
The plugin to show the alias for
<ALIAS>
The alias to show

List tool version aliases Shows the aliases that can be specified. These can come from user config or from plugins in `bin/list-aliases`.

For user config, aliases are defined like the following in `~/.config/mise/config.toml`:


[tool_alias.node.versions]
lts = "22.0.0"

Usage: mise tool-alias ls [OPTIONS] [<TOOL>]

Options:

Don't show table header Arguments:
<TOOL>
Show aliases for <TOOL>

Add/update an alias for a backend/plugin

This modifies the contents of ~/.config/mise/config.toml

Usage: mise tool-alias set <PLUGIN> <ALIAS> [<VALUE>]

Arguments:

<PLUGIN>
The backend/plugin to set the alias for
<ALIAS>
The alias to set
<VALUE>
The value to set the alias to

Clears an alias for a backend/plugin

This modifies the contents of ~/.config/mise/config.toml

Usage: mise tool-alias unset <PLUGIN> [<ALIAS>]

Arguments:

<PLUGIN>
The backend/plugin to remove the alias from
<ALIAS>
The alias to remove

List all the active runtime bin paths

Usage: mise bin-paths [<TOOL@VERSION>] ...

Arguments:

<TOOL@VERSION>
Tool(s) to look up e.g.: ruby@3

Deletes all cache files in mise

Usage: mise cache clear [OPTIONS] [<PLUGIN>] ...

Options:

Mark all cache files as old Arguments:
<PLUGIN>
Plugin(s) to clear cache for e.g.: node, python

Removes stale mise cache files

By default, this command will remove files that have not been accessed in 30 days. Change this with the MISE_CACHE_PRUNE_AGE environment variable.

Usage: mise cache prune [OPTIONS] [<PLUGIN>] ...

Options:

Show pruned files
Just show what would be pruned Arguments:
<PLUGIN>
Plugin(s) to clear cache for e.g.: node, python

Generate shell completions

Usage: mise completion [OPTIONS] [<SHELL>]

Options:

Shell type to generate completions for
Include the bash completion library in the bash completion script

This is required for completions to work in bash, but it is not included by default you may source it separately or enable this flag to enable it in the script.

Always use usage for completions. Currently, usage is the default for fish and bash but not zsh since it has a few quirks to work out first.

This requires the `usage` CLI to be installed. https://usage.jdx.dev Arguments:

<SHELL>
Shell type to generate completions for

Manage config files

Usage: mise config [OPTIONS] [COMMAND]

Options:

Output in JSON format
Do not print table header
List all tracked config files

Display the value of a setting in a mise.toml file

Usage: mise config get [OPTIONS] [<KEY>]

Options:

The path to the mise.toml file to edit

If not provided, the nearest mise.toml file will be used Arguments:

<KEY>
The path of the config to display

List config files currently in use

Usage: mise config ls [OPTIONS]

Options:

Output in JSON format
Do not print table header
List all tracked config files

Set the value of a setting in a mise.toml file

Usage: mise config set [OPTIONS] <KEY> [<VALUE>]

Options:

The path to the mise.toml file to edit

If not provided, the nearest mise.toml file will be used

Default: infer
Arguments:
<KEY>
The path of the config to display
<VALUE>
The value to set the key to (optional if provided as KEY=VALUE)

Check mise installation for possible problems

Usage: mise doctor [OPTIONS] [COMMAND]

Options:

Print the current PATH entries mise is providing

Usage: mise doctor path [OPTIONS]

Options:

Print all entries including those not provided by mise

Starts a new shell with the mise environment built from the current configuration

This is an alternative to `mise activate` that allows you to explicitly start a mise session. It will have the tools and environment variables in the configs loaded. Note that changing directories will not update the mise environment.

Usage: mise en [OPTIONS] [<DIR>]

Options:

Shell to start

Defaults to $SHELL Arguments:

<DIR>
Directory to start the shell in
Default: .

Exports env vars to activate mise a single time

Use this if you don't want to permanently install mise. It's not necessary to use this if you have `mise activate` in your shell rc file.

Usage: mise env [OPTIONS] [<TOOL@VERSION>] ...

Options:

Output in dotenv format
Output in JSON format
Shell type to generate environment variables for
Output in JSON format with additional information (source, tool)
Only show redacted environment variables
Only show values of environment variables Arguments:
<TOOL@VERSION>
Tool(s) to use

Execute a command with tool(s) set

use this to avoid modifying the shell session or running ad-hoc commands with mise tools set.

Tools will be loaded from mise.toml, though they can be overridden with <RUNTIME> args Note that only the plugin specified will be overridden, so if a `mise.toml` file includes "node 20" but you run `mise exec python@3.11`; it will still load node@20.

The "--" separates runtimes from the commands to pass along to the subprocess.

Usage: mise exec [OPTIONS] [<TOOL@VERSION>] ... [<COMMAND>] ...

Options:

Command string to execute
Number of jobs to run in parallel [default: 4]
Bypass the environment cache and recompute the environment
Skip automatic dependency preparation
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Arguments:
<TOOL@VERSION>
Tool(s) to start e.g.: node@20 python@3.10
<COMMAND>
Command string to execute (same as --command)

Formats mise.toml

Sorts keys and cleans up whitespace in mise.toml

Usage: mise fmt [OPTIONS]

Options:

Format all files from the current directory
Check if the configs are formatted, no formatting is done
Read config from stdin and write its formatted version into stdout

Generate a script to download+execute mise

This is designed to be used in a project where contributors may not have mise installed.

Usage: mise generate bootstrap [OPTIONS]

Options:

Sandboxes mise internal directories like MISE_DATA_DIR and MISE_CACHE_DIR into a `.mise` directory in the project

This is necessary if users may use a different version of mise outside the project.

Specify mise version to fetch
instead of outputting the script to stdout, write to a file and make it executable
Directory to put localized data into
Default: .mise

Generate a mise.toml file

Usage: mise generate config [OPTIONS] [<PATH>]

Options:

Show what would be generated without writing to file
Path to a .tool-versions file to import tools from Arguments:
<PATH>
Path to the config file to create

Generate a devcontainer to execute mise

Usage: mise generate devcontainer [OPTIONS]

Options:

The image to use for the devcontainer
Bind the mise-data-volume to the devcontainer
The name of the devcontainer
write to .devcontainer/devcontainer.json

Generate a git pre-commit hook

This command generates a git pre-commit hook that runs a mise task like `mise run pre-commit` when you commit changes to your repository.

Staged files are passed to the task as `STAGED`.

For more advanced pre-commit functionality, see mise's sister project: https://hk.jdx.dev/

Usage: mise generate git-pre-commit [OPTIONS]

Options:

The task to run when the pre-commit hook is triggered
Default: pre-commit
write to .git/hooks/pre-commit and make it executable
Which hook to generate (saves to .git/hooks/$hook)
Default: pre-commit

Generate a GitHub Action workflow file

This command generates a GitHub Action workflow file that runs a mise task like `mise run ci` when you push changes to your repository.

Usage: mise generate github-action [OPTIONS]

Options:

The task to run when the workflow is triggered
Default: ci
write to .github/workflows/$name.yml
the name of the workflow to generate
Default: ci

Generate documentation for tasks in a project

Usage: mise generate task-docs [OPTIONS]

Options:

inserts the documentation into an existing file

This will look for a special comment, `<!-- mise-tasks -->`, and replace it with the generated documentation. It will replace everything between the comment and the next comment, `<!-- /mise-tasks -->` so it can be run multiple times on the same file to update the documentation.

write only an index of tasks, intended for use with `--multi`
render each task as a separate document, requires `--output` to be a directory
writes the generated docs to a file/directory
root directory to search for tasks
Default: simple

Generates shims to run mise tasks

By default, this will build shims like ./bin/<task>. These can be paired with `mise generate bootstrap` so contributors to a project can execute mise tasks without installing mise into their system.

Usage: mise generate task-stubs [OPTIONS]

Options:

Directory to create task stubs inside of
Default: bin
Path to a mise bin to use when running the task stub.

Use `--mise-bin=./bin/mise` to use a mise bin generated from `mise generate bootstrap`

Default: mise

Generate a tool stub for HTTP-based tools

This command generates tool stubs that can automatically download and execute tools from HTTP URLs. It can detect checksums, file sizes, and binary paths automatically by downloading and analyzing the tool.

When generating stubs with platform-specific URLs, the command will append new platforms to existing stub files rather than overwriting them. This allows you to incrementally build cross-platform tool stubs.

Usage: mise generate tool-stub [OPTIONS] <OUTPUT>

Options:

Binary path within the extracted archive

If not specified and the archive is downloaded, will auto-detect the most likely binary

Wrap stub in a bootstrap script that installs mise if not already present

When enabled, generates a bash script that: 1. Checks if mise is installed at the expected path 2. If not, downloads and installs mise using the embedded installer 3. Executes the tool stub using mise

Specify mise version for the bootstrap script

By default, uses the latest version from the install script. Use this to pin to a specific version (e.g., "2025.1.0").

Fetch checksums and sizes for an existing tool stub file

This reads an existing stub file and fills in any missing checksum/size fields by downloading the files. URLs must already be present in the stub.

HTTP backend type to use
Default: http
Resolve and embed lockfile data (exact version + platform URLs/checksums) into an existing stub file for reproducible installs without runtime API calls
Platform-specific binary paths in the format platform:path

Examples: --platform-bin windows-x64:tool.exe --platform-bin linux-x64:bin/tool

Platform-specific URLs in the format platform:url or just url (auto-detect platform)

When the output file already exists, new platforms will be appended to the existing platforms table. Existing platform URLs will be updated if specified again.

If only a URL is provided (without platform:), the platform will be automatically detected from the URL filename.

Examples: --platform-url linux-x64:https://... --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz

Skip downloading for checksum and binary path detection (faster but less informative)
URL for downloading the tool

Example: https://github.com/owner/repo/releases/download/v2.0.0/tool-linux-x64.tar.gz

Version of the tool
Default: latest
Arguments:
<OUTPUT>
Output file path for the tool stub

Removes mise CLI and all related data

Skips config directory by default.

Usage: mise implode [OPTIONS]

Options:

List directories that would be removed without actually removing them
Also remove config directory

Edit mise.toml interactively

Usage: mise edit [OPTIONS] [<PATH>]

Options:

Show what would be generated without writing to file
Path to a .tool-versions file to import tools from Arguments:
<PATH>
Path to the config file to create

Install a tool version

Installs a tool version to `~/.local/share/mise/installs/<PLUGIN>/<VERSION>` Installing alone will not activate the tools so they won't be in PATH. To install and/or activate in one command, use `mise use` which will create a `mise.toml` file in the current directory to activate this tool when inside the directory. Alternatively, run `mise exec <TOOL>@<VERSION> -- <COMMAND>` to execute a tool without creating config files.

Tools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1`

Usage: mise install [OPTIONS] [<TOOL@VERSION>] ...

Options:

Force reinstall even if already installed
Number of jobs to run in parallel [default: 4]
Show what would be installed without actually installing
Show installation output

This argument will print plugin output such as download, configuration, and compilation output.

Only install versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".

Like --dry-run but exits with code 1 if there are tools to install

This is useful for scripts to check if tools need to be installed.

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Arguments:
<TOOL@VERSION>
Tool(s) to install e.g.: node@20

Install a tool version to a specific path

Used for building a tool to a directory for use outside of mise

Usage: mise install-into <TOOL@VERSION> <PATH>

Arguments:

<TOOL@VERSION>
Tool to install e.g.: node@20
<PATH>
Path to install the tool into

Gets the latest available version for a plugin

Supports prefixes such as `node@20` to get the latest version of node 20.

Usage: mise latest [OPTIONS] <TOOL@VERSION> [<ASDF_VERSION>]

Options:

Show latest installed instead of available version Arguments:
<TOOL@VERSION>
Tool to get the latest version of
<ASDF_VERSION>
The version prefix to use when querying the latest version same as the first argument after the "@" used for asdf compatibility

Symlinks a tool version into mise

Use this for adding installs either custom compiled outside mise or built with a different tool.

Usage: mise link [OPTIONS] <TOOL@VERSION> <PATH>

Options:

Overwrite an existing tool version if it exists Arguments:
<TOOL@VERSION>
Tool name and version to create a symlink for
<PATH>
The local path to the tool version e.g.: ~/.nvm/versions/node/v20.0.0

Update lockfile checksums and URLs for all specified platforms

Updates checksums and download URLs for all platforms already specified in the lockfile. If no lockfile exists, shows what would be created based on the current configuration. This allows you to refresh lockfile data for platforms other than the one you're currently on. Operates on the lockfile in the current config root. Use TOOL arguments to target specific tools.

Usage: mise lock [OPTIONS] [<TOOL>] ...

Options:

Number of jobs to run in parallel
Show what would be updated without making changes
Comma-separated list of platforms to target e.g.: linux-x64,macos-arm64,windows-x64 If not specified, all platforms already in lockfile will be updated
Update mise.local.lock instead of mise.lock Use for tools defined in .local.toml configs Arguments:
<TOOL>
Tool(s) to update in lockfile e.g.: node python If not specified, all tools in lockfile will be updated

List installed and active tool versions

This command lists tools that mise "knows about". These may be tools that are currently installed, or those that are in a config file (active) but may or may not be installed.

It's a useful command to get the current state of your tools.

Usage: mise ls [OPTIONS] [<INSTALLED_TOOL>] ...

Options:

Only show tool versions currently specified in a mise.toml
Only show tool versions currently specified in the global mise.toml
Only show tool versions that are installed (Hides tools defined in mise.toml but not installed)
Output in JSON format
Only show tool versions currently specified in the local mise.toml
Display missing tool versions
Don't fetch information such as outdated versions
Display all tracked config sources for tools
Don't display headers
Display whether a version is outdated
Display versions matching this prefix
List only tools that can be pruned with `mise prune` Arguments:
<INSTALLED_TOOL>
Only show tool versions from [TOOL]

List runtime versions available for install.

Note that the results may be cached, run `mise cache clean` to clear the cache and get fresh results.

Usage: mise ls-remote [OPTIONS] [<TOOL@VERSION>] [<PREFIX>]

Options:

Show all installed plugins and versions
Output in JSON format (includes version metadata like created_at timestamps when available) Arguments:
<TOOL@VERSION>
Tool to get versions for
<PREFIX>
The version prefix to use when querying the latest version same as the first argument after the "@"

Shows outdated tool versions

See `mise upgrade` to upgrade these versions.

Usage: mise outdated [OPTIONS] [<TOOL@VERSION>] ...

Options:

Output in JSON format
Compares against the latest versions available, not what matches the current config

For example, if you have `node = "20"` in your config by default `mise outdated` will only show other 20.x versions, not 21.x or 22.x versions.

Using this flag, if there are 21.x or newer versions it will display those instead of 20.x.

Don't show table header Arguments:
<TOOL@VERSION>
Tool(s) to show outdated versions for e.g.: node@20 python@3.10 If not specified, all tools in global and local configs will be shown

Manage plugins

Usage: mise plugins [OPTIONS] [COMMAND]

Options:

list all available remote plugins

same as `mise plugins ls-remote`

The built-in plugins only Normally these are not shown
Show the git url for each plugin e.g.: https://github.com/asdf-vm/asdf-nodejs.git
Show the git refs for each plugin e.g.: main 1234abc
List installed plugins

This is the default behavior but can be used with --core to show core and user plugins

Install a plugin

note that mise automatically can install plugins when you install a tool e.g.: `mise install node@20` will autoinstall the node plugin

This behavior can be modified in ~/.config/mise/config.toml

Usage: mise plugins install [OPTIONS] [<NEW_PLUGIN>] [<GIT_URL>] [<REST>] ...

Options:

Install all missing plugins This will only install plugins that have matching shorthands. i.e.: they don't need the full git repo url
Reinstall even if plugin exists
Number of jobs to run in parallel
Show installation output Arguments:
<NEW_PLUGIN>
The name of the plugin to install e.g.: node, ruby Can specify multiple plugins: `mise plugins install node ruby python`
<GIT_URL>
The git url of the plugin

Symlinks a plugin into mise

This is used for developing a plugin.

Usage: mise plugins link [OPTIONS] <NAME> [<DIR>]

Options:

Overwrite existing plugin Arguments:
<NAME>
The name of the plugin e.g.: node, ruby
<DIR>
The local path to the plugin e.g.: ./mise-node

List installed plugins

Can also show remotely available plugins to install.

Usage: mise plugins ls [OPTIONS]

Options:

List all available remote plugins Same as `mise plugins ls-remote`
The built-in plugins only Normally these are not shown
Show the git url for each plugin e.g.: https://github.com/asdf-vm/asdf-nodejs.git
Show the git refs for each plugin e.g.: main 1234abc
List installed plugins

List all available remote plugins

The full list is here: https://github.com/jdx/mise/blob/main/registry/

Examples:


$ mise plugins ls-remote

Usage: mise plugins ls-remote [OPTIONS]

Options:

Show the git url for each plugin e.g.: https://github.com/mise-plugins/mise-poetry.git
Only show the name of each plugin by default it will show a "*" next to installed plugins

Removes a plugin

Usage: mise plugins uninstall [OPTIONS] [<PLUGIN>] ...

Options:

Remove all plugins
Also remove the plugin's installs, downloads, and cache Arguments:
<PLUGIN>
Plugin(s) to remove

Updates a plugin to the latest version

note: this updates the plugin itself, not the runtime versions

Usage: mise plugins update [OPTIONS] [<PLUGIN>] ...

Options:

Number of jobs to run in parallel Default: 4 Arguments:
<PLUGIN>
Plugin(s) to update

[experimental] Ensure project dependencies are ready

Runs all applicable prepare steps for the current project. This checks if dependency lockfiles are newer than installed outputs (e.g., package-lock.json vs node_modules/) and runs install commands if needed.

Providers with `auto = true` are automatically invoked before `mise x` and `mise run` unless skipped with the --no-prepare flag.

Usage: mise prepare [OPTIONS]

Options:

Force run all prepare steps even if outputs are fresh
Show what prepare steps are available
Only check if prepare is needed, don't run commands
Run specific prepare rule(s) only
Skip specific prepare rule(s)

Delete unused versions of tools

mise tracks which config files have been used in ~/.local/state/mise/tracked-configs Versions which are no longer the latest specified in any of those configs are deleted. Versions installed only with environment variables `MISE_<PLUGIN>_VERSION` will be deleted, as will versions only referenced on the command line `mise exec <PLUGIN>@<VERSION>`.

You can list prunable tools with `mise ls --prunable`

Usage: mise prune [OPTIONS] [<INSTALLED_TOOL>] ...

Options:

Do not actually delete anything
Prune only tracked and trusted configuration links that point to non-existent configurations
Like --dry-run but exits with code 1 if there are tools to prune

This is useful for scripts to check if tools need to be pruned.

Prune only unused versions of tools Arguments:
<INSTALLED_TOOL>
Prune only these tools

List available tools to install

This command lists the tools available in the registry as shorthand names.

For example, `poetry` is shorthand for `asdf:mise-plugins/mise-poetry`.

Usage: mise registry [OPTIONS] [<NAME>]

Options:

Show only tools for this backend
Print all tools with descriptions for shell completions
Hide aliased tools
Output in JSON format Arguments:
<NAME>
Show only the specified tool's full name

Creates new shims based on bin paths from currently installed tools.

This creates new shims in ~/.local/share/mise/shims for CLIs that have been added. mise will try to do this automatically for commands like `npm i -g` but there are other ways to install things (like using yarn or pnpm for node) that mise does not know about and so it will be necessary to call this explicitly.

If you think mise should automatically call this for a particular command, please open an issue on the mise repo. You can also setup a shell function to reshim automatically (it's really fast so you don't need to worry about overhead):


npm() {
command npm "$@"
mise reshim
}

Note that this creates shims for _all_ installed tools, not just the ones that are currently active in mise.toml.

Usage: mise reshim [OPTIONS] [<PLUGIN>] [<VERSION>]

Options:

Removes all shims before reshimming

Run task(s)

This command will run a task, or multiple tasks in parallel. Tasks may have dependencies on other tasks or on source files. If source is configured on a task, it will only run if the source files have changed.

Tasks can be defined in mise.toml or as standalone scripts. In mise.toml, tasks take this form:


[tasks.build]
run = "npm run build"
sources = ["src/**/*.ts"]
outputs = ["dist/**/*.js"]

Alternatively, tasks can be defined as standalone scripts. These must be located in `mise-tasks`, `.mise-tasks`, `.mise/tasks`, `mise/tasks` or `.config/mise/tasks`. The name of the script will be the name of the tasks.


$ cat .mise/tasks/build<<EOF
#!/usr/bin/env bash
npm run build
EOF
$ mise run build

Usage: mise run [OPTIONS]

Options:

Continue running tasks even if one fails
Change to this directory before executing the command
Force the tasks to run even if outputs are up to date
Print directly to stdout/stderr instead of by line Defaults to true if --jobs == 1 Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Number of tasks to run in parallel [default: 4] Configure with `jobs` config or `MISE_JOBS` env var
Don't actually run the task(s), just print them in order of execution
Change how tasks information is output when running tasks

- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `replacing` - Stdout is replaced each time, stderr is printed as is - `timed` - Only show stdout lines if they are displayed for more than 1 second - `keep-order` - Print stdout/stderr by line, prefixed with the task's label, but keep the order of the output - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors

Print stdout/stderr by line, prefixed with the task's label Defaults to true if --jobs > 1 Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Don't show extra output
Read/write directly to stdin/stdout/stderr instead of by line Redactions are not applied with this option Configure with `raw` config or `MISE_RAW` env var
Shell to use to run toml tasks

Defaults to `sh -c -o errexit -o pipefail` on unix, and `cmd /c` on Windows Can also be set with the setting `MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS` or `MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS` Or it can be overridden with the `shell` property on a task.

Don't show any output except for errors
Tool(s) to run in addition to what is in mise.toml files e.g.: node@20 python@3.10
Bypass the environment cache and recompute the environment
Do not use cache on remote tasks
Skip automatic dependency preparation
Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

Run only the specified tasks skipping all dependencies
Timeout for the task to complete e.g.: 30s, 5m
Shows elapsed time after each task completes

Default to always show with `MISE_TASK_TIMINGS=1`

Search for tools in the registry

This command searches a tool in the registry.

By default, it will show all tools that fuzzy match the search term. For non-fuzzy matches, use the `--match-type` flag.

Usage: mise search [OPTIONS] [<NAME>]

Options:

Show interactive search
Match type: equal, contains, or fuzzy
Default: fuzzy
Don't display headers Arguments:
<NAME>
The tool to search for

Updates mise itself.

Uses the GitHub Releases API to find the latest release and binary. By default, this will also update any installed plugins. Uses the `GITHUB_API_TOKEN` environment variable if set for higher rate limits.

This command is not available if mise is installed via a package manager.

Usage: mise self-update [OPTIONS] [<VERSION>]

Options:

Update even if already up to date
Skip confirmation prompt
Disable auto-updating plugins Arguments:
<VERSION>
Update to a specific version

Set environment variables in mise.toml

By default, this command modifies `mise.toml` in the current directory. If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`), the lowest precedence file (`mise.toml`) will be used. See https://mise.jdx.dev/configuration.html#target-file-for-write-operations

Use `-E <env>` to create/modify environment-specific config files like `mise.<env>.toml`.

Usage: mise set [OPTIONS] [<ENV_VAR>] ...

Options:

Create/modify an environment-specific config file like .mise.<env>.toml
Set the environment variable in the global config file
[experimental] Encrypt the value with age before storing
[experimental] Age identity file for encryption

Defaults to ~/.config/mise/age.txt if it exists

[experimental] Age recipient (x25519 public key) for encryption

Can be used multiple times. Requires --age-encrypt.

[experimental] SSH recipient (public key or path) for age encryption

Can be used multiple times. Requires --age-encrypt.

Render completions
The TOML file to update

Can be a file path or directory. If a directory is provided, will create/use mise.toml in that directory. Defaults to MISE_DEFAULT_CONFIG_FILENAME environment variable, or `mise.toml`.

Prompt for environment variable values
Remove the environment variable from config file

Can be used multiple times.

Read the value from stdin (for multiline input)

When using --stdin, provide a single key without a value. The value will be read from stdin until EOF. Arguments:

<ENV_VAR>
Environment variable(s) to set e.g.: NODE_ENV=production

Show current settings

This is the contents of ~/.config/mise/config.toml

Note that aliases are also stored in this file but managed separately with `mise tool-alias`

Usage: mise settings [OPTIONS] [<SETTING>] [<VALUE>] [COMMAND]

Options:

List all settings
Output in JSON format
Use the local config file instead of the global one
Output in TOML format
Print all settings with descriptions for shell completions
Output in JSON format with sources Arguments:
<SETTING>
Name of setting
<VALUE>
Setting value to set

Adds a setting to the configuration file

Used with an array setting, this will append the value to the array. This modifies the contents of ~/.config/mise/config.toml

Usage: mise settings add [OPTIONS] <SETTING> [<VALUE>]

Options:

Use the local config file instead of the global one Arguments:
<SETTING>
The setting to set
<VALUE>
The value to set (optional if provided as KEY=VALUE)

Show a current setting

This is the contents of a single entry in ~/.config/mise/config.toml

Note that aliases are also stored in this file but managed separately with `mise tool-alias get`

Usage: mise settings get [OPTIONS] <SETTING>

Options:

Use the local config file instead of the global one Arguments:
<SETTING>
The setting to show

Show current settings

This is the contents of ~/.config/mise/config.toml

Note that aliases are also stored in this file but managed separately with `mise tool-alias`

Usage: mise settings ls [OPTIONS] [<SETTING>]

Options:

List all settings
Output in JSON format
Use the local config file instead of the global one
Output in TOML format
Print all settings with descriptions for shell completions
Output in JSON format with sources Arguments:
<SETTING>
Name of setting

Add/update a setting

This modifies the contents of ~/.config/mise/config.toml by default. With `--local`, modifies the local config file instead. See https://mise.jdx.dev/configuration.html#target-file-for-write-operations

Usage: mise settings set [OPTIONS] <SETTING> [<VALUE>]

Options:

Use the local config file instead of the global one Arguments:
<SETTING>
The setting to set
<VALUE>
The value to set (optional if provided as KEY=VALUE)

Clears a setting

This modifies the contents of ~/.config/mise/config.toml

Usage: mise settings unset [OPTIONS] <KEY>

Options:

Use the local config file instead of the global one Arguments:
<KEY>
The setting to remove

Sets a tool version for the current session.

Only works in a session where mise is already activated.

This works by setting environment variables for the current shell session such as `MISE_NODE_VERSION=20` which is "eval"ed as a shell function created by `mise activate`.

Usage: mise shell [OPTIONS] <TOOL@VERSION> ...

Options:

Number of jobs to run in parallel [default: 4]
Removes a previously set version
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Arguments:
<TOOL@VERSION>
Tool(s) to use

Manage shell aliases.

Usage: mise shell-alias [OPTIONS] [COMMAND]

Options:

Don't show table header

Show the command for a shell alias

Usage: mise shell-alias get <shell_alias>

Arguments:

<shell_alias>
The alias to show

List shell aliases

Shows the shell aliases that are set in the current directory. These are defined in `mise.toml` under the `[shell_alias]` section.

Usage: mise shell-alias ls [OPTIONS]

Options:

Don't show table header

Add/update a shell alias

This modifies the contents of ~/.config/mise/config.toml

Usage: mise shell-alias set <shell_alias> [<COMMAND>]

Arguments:

<shell_alias>
The alias name
<COMMAND>
The command to run (optional if provided as ALIAS=COMMAND)

Removes a shell alias

This modifies the contents of ~/.config/mise/config.toml

Usage: mise shell-alias unset <shell_alias>

Arguments:

<shell_alias>
The alias to remove

Symlinks all tool versions from an external tool into mise

For example, use this to import all Homebrew node installs into mise

This won't overwrite any existing installs but will overwrite any existing symlinks

Usage: mise sync node [OPTIONS]

Options:

Get tool versions from Homebrew
Get tool versions from nodenv
Get tool versions from nvm

Symlinks all tool versions from an external tool into mise

For example, use this to import all pyenv installs into mise

This won't overwrite any existing installs but will overwrite any existing symlinks

Usage: mise sync python [OPTIONS]

Options:

Get tool versions from pyenv
Sync tool versions with uv (2-way sync)

Symlinks all ruby tool versions from an external tool into mise

Usage: mise sync ruby [OPTIONS]

Options:

Get tool versions from Homebrew

Manage tasks

Usage: mise tasks [OPTIONS] [<TASK>] [COMMAND]

Options:

Only show global tasks
Output in JSON format
Only show non-global tasks
Show all columns
Load all tasks from the entire monorepo, including sibling directories. By default, only tasks from the current directory hierarchy are loaded.
Display tasks for usage completion
Show hidden tasks
Do not print table header
Sort by column. Default is name.
Sort order. Default is asc.
Arguments:
<TASK>
Task name to get info of

Create a new task

Adds a task to the local mise.toml file. See https://mise.jdx.dev/configuration.html#target-file-for-write-operations

Usage: mise tasks add [OPTIONS] <TASK> [<RUN>] ...

Options:

Other names for the task
Add dependencies to the task
Run the task in a specific directory
Create a file task instead of a toml task
Hide the task from `mise tasks` and completions
Do not print the command before running
Directly connect stdin/stdout/stderr
Glob patterns of files this task uses as input
Wait for these tasks to complete if they are to run
Dependencies to run after the task runs
Description of the task
Glob patterns of files this task creates, to skip if they are not modified
Command to run on windows
Run the task in a specific shell
Do not print the command or its output Arguments:
<TASK>
Tasks name to add

Display a tree visualization of a dependency graph

Usage: mise tasks deps [OPTIONS] [<TASKS>] ...

Options:

Display dependencies in DOT format
Show hidden tasks Arguments:
<TASKS>
Tasks to show dependencies for Can specify multiple tasks by separating with spaces e.g.: mise tasks deps lint test check

Edit a task with $EDITOR

The task will be created as a standalone script if it does not already exist.

Usage: mise tasks edit [OPTIONS] <TASK>

Options:

Display the path to the task instead of editing it Arguments:
<TASK>
Task to edit

Get information about a task

Usage: mise tasks info [OPTIONS] <TASK>

Options:

Output in JSON format Arguments:
<TASK>
Name of the task to get information about

List available tasks to execute These may be included from the config file or from the project's .mise/tasks directory mise will merge all tasks from all parent directories into this list.

So if you have global tasks in `~/.config/mise/tasks/*` and project-specific tasks in ~/myproject/.mise/tasks/*, then they'll both be available but the project-specific tasks will override the global ones if they have the same name.

Usage: mise tasks ls [OPTIONS]

Options:

Only show global tasks
Output in JSON format
Only show non-global tasks
Show all columns
Load all tasks from the entire monorepo, including sibling directories. By default, only tasks from the current directory hierarchy are loaded.
Display tasks for usage completion
Show hidden tasks
Do not print table header
Sort by column. Default is name.
Sort order. Default is asc.

Run task(s)

This command will run a task, or multiple tasks in parallel. Tasks may have dependencies on other tasks or on source files. If source is configured on a task, it will only run if the source files have changed.

Tasks can be defined in mise.toml or as standalone scripts. In mise.toml, tasks take this form:


[tasks.build]
run = "npm run build"
sources = ["src/**/*.ts"]
outputs = ["dist/**/*.js"]

Alternatively, tasks can be defined as standalone scripts. These must be located in `mise-tasks`, `.mise-tasks`, `.mise/tasks`, `mise/tasks` or `.config/mise/tasks`. The name of the script will be the name of the tasks.


$ cat .mise/tasks/build<<EOF
#!/usr/bin/env bash
npm run build
EOF
$ mise run build

Usage: mise tasks run [OPTIONS] [<TASK>] [<ARGS>] ... [<ARGS_LAST>] ...

Options:

Continue running tasks even if one fails
Change to this directory before executing the command
Force the tasks to run even if outputs are up to date
Print directly to stdout/stderr instead of by line Defaults to true if --jobs == 1 Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Number of tasks to run in parallel [default: 4] Configure with `jobs` config or `MISE_JOBS` env var
Don't actually run the task(s), just print them in order of execution
Change how tasks information is output when running tasks

- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `replacing` - Stdout is replaced each time, stderr is printed as is - `timed` - Only show stdout lines if they are displayed for more than 1 second - `keep-order` - Print stdout/stderr by line, prefixed with the task's label, but keep the order of the output - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors

Print stdout/stderr by line, prefixed with the task's label Defaults to true if --jobs > 1 Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Don't show extra output
Read/write directly to stdin/stdout/stderr instead of by line Redactions are not applied with this option Configure with `raw` config or `MISE_RAW` env var
Shell to use to run toml tasks

Defaults to `sh -c -o errexit -o pipefail` on unix, and `cmd /c` on Windows Can also be set with the setting `MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS` or `MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS` Or it can be overridden with the `shell` property on a task.

Don't show any output except for errors
Tool(s) to run in addition to what is in mise.toml files e.g.: node@20 python@3.10
Bypass the environment cache and recompute the environment
Do not use cache on remote tasks
Skip automatic dependency preparation
Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

Run only the specified tasks skipping all dependencies
Timeout for the task to complete e.g.: 30s, 5m
Shows elapsed time after each task completes

Default to always show with `MISE_TASK_TIMINGS=1` Arguments:

<TASK>
Tasks to run Can specify multiple tasks by separating with `:::` e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
Default: default
<ARGS>
Arguments to pass to the tasks. Use ":::" to separate tasks
<ARGS_LAST>
Arguments to pass to the tasks. Use ":::" to separate tasks

Validate tasks for common errors and issues

Usage: mise tasks validate [OPTIONS] [<TASKS>] ...

Options:

Only show errors (skip warnings)
Output validation results in JSON format Arguments:
<TASKS>
Tasks to validate If not specified, validates all tasks

Test a tool installs and executes

Usage: mise test-tool [OPTIONS] [<TOOLS>] ...

Options:

Test every tool specified in registry/
Number of jobs to run in parallel [default: 4]
Test all tools specified in config files
Also test tools not defined in registry/, guessing how to test it
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Arguments:
<TOOLS>
Tool(s) to test

Gets information about a tool

Usage: mise tool [OPTIONS] <TOOL>

Options:

Output in JSON format
Only show active versions
Only show backend field
Only show config source
Only show description field
Only show installed versions
Only show requested versions
Only show tool options Arguments:
<TOOL>
Tool name to get information about

Execute a tool stub

Tool stubs are executable files containing TOML configuration that specify which tool to run and how to run it. They provide a convenient way to create portable, self-contained executables that automatically manage tool installation and execution.

A tool stub consists of: - A shebang line: #!/usr/bin/env -S mise tool-stub - TOML configuration specifying the tool, version, and options - Optional comments describing the tool's purpose

Example stub file: #!/usr/bin/env -S mise tool-stub # Node.js v20 development environment

tool = "node" version = "20.0.0" bin = "node"

The stub will automatically install the specified tool version if missing and execute it with any arguments passed to the stub.

For more information, see: https://mise.jdx.dev/dev-tools/tool-stubs.html

Usage: mise tool-stub <FILE> [<ARGS>] ...

Arguments:

<FILE>
Path to the TOML tool stub file to execute

The stub file must contain TOML configuration specifying the tool and version to run. At minimum, it should specify a 'version' field. Other common fields include 'tool', 'bin', and backend-specific options.

<ARGS>
Arguments to pass to the tool

All arguments after the stub file path will be forwarded to the underlying tool. Use '--' to separate mise arguments from tool arguments if needed.

Marks a config file as trusted

This means mise will parse the file with potentially dangerous features enabled.

This includes: - environment variables - templates - `path:` plugin versions

Usage: mise trust [OPTIONS] [<CONFIG_FILE>]

Options:

Trust all config files in the current directory and its parents
Do not trust this config and ignore it in the future
Show the trusted status of config files from the current directory and its parents. Does not trust or untrust any files.
No longer trust this config, will prompt in the future Arguments:
<CONFIG_FILE>
The config file to trust

Removes installed tool versions

This only removes the installed version, it does not modify mise.toml.

Usage: mise uninstall [OPTIONS] [<INSTALLED_TOOL@VERSION>] ...

Options:

Delete all installed versions
Do not actually delete anything
Like --dry-run but exits with code 1 if there are tools to uninstall

This is useful for scripts to check if tools need to be uninstalled. Arguments:

<INSTALLED_TOOL@VERSION>
Tool(s) to remove

Remove environment variable(s) from the config file.

By default, this command modifies `mise.toml` in the current directory.

Usage: mise unset [OPTIONS] [<ENV_KEY>] ...

Options:

Specify a file to use instead of `mise.toml`
Use the global config file Arguments:
<ENV_KEY>
Environment variable(s) to remove e.g.: NODE_ENV

Removes installed tool versions from mise.toml

By default, this will use the `mise.toml` file that has the tool defined. If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`), the lowest precedence file (`mise.toml`) will be used. See https://mise.jdx.dev/configuration.html#target-file-for-write-operations

In the following order:
- If `--global` is set, it will use the global config file.
- If `--path` is set, it will use the config file at the given path.
- If `--env` is set, it will use `mise.<env>.toml`.
- If `MISE_DEFAULT_CONFIG_FILENAME` is set, it will use that instead.
- If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, it will the first from that list.
- Otherwise just "mise.toml" or global config if cwd is home directory.

Will also prune the installed version if no other configurations are using it.

Usage: mise unuse [OPTIONS] <INSTALLED_TOOL@VERSION> ...

Options:

Create/modify an environment-specific config file like .mise.<env>.toml
Use the global config file (`~/.config/mise/config.toml`) instead of the local one
Specify a path to a config file or directory

If a directory is specified, it will look for a config file in that directory following the rules above.

Do not also prune the installed version Arguments:
<INSTALLED_TOOL@VERSION>
Tool(s) to remove

Upgrades outdated tools

By default, this keeps the range specified in mise.toml. So if you have node@20 set, it will upgrade to the latest 20.x.x version available. See the `--bump` flag to use the latest version and bump the version in mise.toml.

This will update mise.lock if it is enabled, see https://mise.jdx.dev/configuration/settings.html#lockfile

Usage: mise upgrade [OPTIONS] [<INSTALLED_TOOL@VERSION>] ...

Options:

Display multiselect menu to choose which tools to upgrade
Number of jobs to run in parallel [default: 4]
Upgrades to the latest version available, bumping the version in mise.toml

For example, if you have `node = "20.0.0"` in your mise.toml but 22.1.0 is the latest available, this will install 22.1.0 and set `node = "22.1.0"` in your config.

It keeps the same precision as what was there before, so if you instead had `node = "20"`, it would change your config to `node = "22"`.

Just print what would be done, don't actually do it
Tool(s) to exclude from upgrading e.g.: go python
Only upgrade to versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y". This can be useful for reproducibility or security purposes.

This only affects fuzzy version matches like "20" or "latest". Explicitly pinned versions like "22.5.0" are not filtered.

Like --dry-run but exits with code 1 if there are outdated tools

This is useful for scripts to check if tools need to be upgraded.

Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 Arguments:
<INSTALLED_TOOL@VERSION>
Tool(s) to upgrade e.g.: node@20 python@3.10 If not specified, all current tools will be upgraded

Installs a tool and adds the version to mise.toml.

This will install the tool version if it is not already installed. By default, this will use a `mise.toml` file in the current directory. If multiple config files exist (e.g., both `mise.toml` and `mise.local.toml`), the lowest precedence file (`mise.toml`) will be used. See https://mise.jdx.dev/configuration.html#target-file-for-write-operations

In the following order:
- If `--global` is set, it will use the global config file.
- If `--path` is set, it will use the config file at the given path.
- If `--env` is set, it will use `mise.<env>.toml`.
- If `MISE_DEFAULT_CONFIG_FILENAME` is set, it will use that instead.
- If `MISE_OVERRIDE_CONFIG_FILENAMES` is set, it will the first from that list.
- Otherwise just "mise.toml" or global config if cwd is home directory.

Use the `--global` flag to use the global config file instead.

Usage: mise use [OPTIONS] [<TOOL@VERSION>] ...

Options:

Create/modify an environment-specific config file like .mise.<env>.toml
Force reinstall even if already installed
Use the global config file (`~/.config/mise/config.toml`) instead of the local one
Number of jobs to run in parallel [default: 4]
Perform a dry run, showing what would be installed and modified without making changes
Specify a path to a config file or directory

If a directory is specified, it will look for a config file in that directory following the rules above.

Only install versions released before this date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".

Like --dry-run but exits with code 1 if there are changes to make

This is useful for scripts to check if tools need to be added or removed.

Save fuzzy version to config file

e.g.: `mise use --fuzzy node@20` will save 20 as the version this is the default behavior unless `MISE_PIN=1`

Save exact version to config file e.g.: `mise use --pin node@20` will save 20.0.0 as the version Set `MISE_PIN=1` to make this the default behavior

Consider using mise.lock as a better alternative to pinning in mise.toml: https://mise.jdx.dev/configuration/settings.html#lockfile

Directly pipe stdin/stdout/stderr from plugin to user Sets `--jobs=1`
Remove the plugin(s) from config file Arguments:
<TOOL@VERSION>
Tool(s) to add to config file

e.g.: node@20, cargo:ripgrep@latest npm:prettier@3 If no version is specified, it will default to @latest

Tool options can be set with this syntax:


mise use ubi:BurntSushi/ripgrep[exe=rg]

Display the version of mise

Displays the version, os, architecture, and the date of the build.

If the version is out of date, it will display a warning.

Usage: mise version [OPTIONS]

Options:

Print the version information in JSON format

Run task(s) and watch for changes to rerun it

This command uses the `watchexec` tool to watch for changes to files and rerun the specified task(s). It must be installed for this command to work, but you can install it with `mise use -g watchexec@latest`.

For more advanced process management (daemon management, auto-restart, readiness checks, cron scheduling), see mise's sister project: https://pitchfork.jdx.dev

Usage: mise watch [OPTIONS] [<TASK>] [<ARGS>] ...

Options:

Tasks to run
Files to watch Defaults to sources from the task(s)
Run only the specified tasks skipping all dependencies
Watch a specific file or directory

By default, Watchexec watches the current directory.

When watching a single file, it's often better to watch the containing directory instead, and filter on the filename. Some editors may replace the file with a new one when saving, and some platforms may not detect that or further changes.

Upon starting, Watchexec resolves a "project origin" from the watched paths. See the help for '--project-origin' for more information.

This option can be specified multiple times to watch multiple files or directories.

The special value '/dev/null', provided as the only path watched, will cause Watchexec to not watch any paths. Other event sources (like signals or key events) may still be used.

Watch a specific directory, non-recursively

Unlike '-w', folders watched with this option are not recursed into.

This option can be specified multiple times to watch multiple directories non-recursively.

Watch files and directories from a file

Each line in the file will be interpreted as if given to '-w'.

For more complex uses (like watching non-recursively), use the argfile capability: build a file containing command-line options and pass it to watchexec with `@path/to/argfile`.

The special value '-' will read from STDIN; this in incompatible with '--stdin-quit'.

Clear screen before running command

If this doesn't completely clear the screen, try '--clear=reset'.

What to do when receiving events while the command is running

Default is to 'do-nothing', which ignores events while the command is running, so that changes that occur due to the command are ignored, like compilation outputs. You can also use 'queue' which will run the command once again when the current run has finished if any events occur while it's running, or 'restart', which terminates the running command and starts a new one. Finally, there's 'signal', which only sends a signal; this can be useful with programs that can reload their configuration without a full restart.

The signal can be specified with the '--signal' option.

Default: do-nothing
Restart the process if it's still running

This is a shorthand for '--on-busy-update=restart'.

Send a signal to the process when it's still running

Specify a signal to send to the process when it's still running. This implies '--on-busy-update=signal'; otherwise the signal used when that mode is 'restart' is controlled by '--stop-signal'.

See the long documentation for '--stop-signal' for syntax.

Signals are not supported on Windows at the moment, and will always be overridden to 'kill'. See '--stop-signal' for more on Windows "signals".

Signal to send to stop the command

This is used by 'restart' and 'signal' modes of '--on-busy-update' (unless '--signal' is provided). The restart behaviour is to send the signal, wait for the command to exit, and if it hasn't exited after some time (see '--timeout-stop'), forcefully terminate it.

The default on unix is "SIGTERM".

Input is parsed as a full signal name (like "SIGTERM"), a short signal name (like "TERM"), or a signal number (like "15"). All input is case-insensitive.

On Windows this option is technically supported but only supports the "KILL" event, as Watchexec cannot yet deliver other events. Windows doesn't have signals as such; instead it has termination (here called "KILL" or "STOP") and "CTRL+C", "CTRL+BREAK", and "CTRL+CLOSE" events. For portability the unix signals "SIGKILL", "SIGINT", "SIGTERM", and "SIGHUP" are respectively mapped to these.

Time to wait for the command to exit gracefully

This is used by the 'restart' mode of '--on-busy-update'. After the graceful stop signal is sent, Watchexec will wait for the command to exit. If it hasn't exited after this time, it is forcefully terminated.

Takes a unit-less value in seconds, or a time span value such as "5min 20s". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

The default is 10 seconds. Set to 0 to immediately force-kill the command.

This has no practical effect on Windows as the command is always forcefully terminated; see '--stop-signal' for why.

Default: 10s
Translate signals from the OS to signals to send to the command

Takes a pair of signal names, separated by a colon, such as "TERM:INT" to map SIGTERM to SIGINT. The first signal is the one received by watchexec, and the second is the one sent to the command. The second can be omitted to discard the first signal, such as "TERM:" to not do anything on SIGTERM.

If SIGINT or SIGTERM are mapped, then they no longer quit Watchexec. Besides making it hard to quit Watchexec itself, this is useful to send pass a Ctrl-C to the command without also terminating Watchexec and the underlying program with it, e.g. with "INT:INT".

This option can be specified multiple times to map multiple signals.

Signal syntax is case-insensitive for short names (like "TERM", "USR2") and long names (like "SIGKILL", "SIGHUP"). Signal numbers are also supported (like "15", "31"). On Windows, the forms "STOP", "CTRL+C", and "CTRL+BREAK" are also supported to receive, but Watchexec cannot yet deliver other "signals" than a STOP.

Time to wait for new events before taking action

When an event is received, Watchexec will wait for up to this amount of time before handling it (such as running the command). This is essential as what you might perceive as a single change may actually emit many events, and without this behaviour, Watchexec would run much too often. Additionally, it's not infrequent that file writes are not atomic, and each write may emit an event, so this is a good way to avoid running a command while a file is partially written.

An alternative use is to set a high value (like "30min" or longer), to save power or bandwidth on intensive tasks, like an ad-hoc backup script. In those use cases, note that every accumulated event will build up in memory.

Takes a unit-less value in milliseconds, or a time span value such as "5sec 20ms". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

The default is 50 milliseconds. Setting to 0 is highly discouraged.

Default: 50ms
Exit when stdin closes

This watches the stdin file descriptor for EOF, and exits Watchexec gracefully when it is closed. This is used by some process managers to avoid leaving zombie processes around.

Don't load gitignores

Among other VCS exclude files, like for Mercurial, Subversion, Bazaar, DARCS, Fossil. Note that Watchexec will detect which of these is in use, if any, and only load the relevant files. Both global (like '~/.gitignore') and local (like '.gitignore') files are considered.

This option is useful if you want to watch files that are ignored by Git.

Don't load project-local ignores

This disables loading of project-local ignore files, like '.gitignore' or '.ignore' in the watched project. This is contrasted with '--no-vcs-ignore', which disables loading of Git and other VCS ignore files, and with '--no-global-ignore', which disables loading of global or user ignore files, like '~/.gitignore' or '~/.config/watchexec/ignore'.

Supported project ignore files:


- Git: .gitignore at project root and child directories, .git/info/exclude, and the file pointed to by `core.excludesFile` in .git/config.
- Mercurial: .hgignore at project root and child directories.
- Bazaar: .bzrignore at project root.
- Darcs: _darcs/prefs/boring
- Fossil: .fossil-settings/ignore-glob
- Ripgrep/Watchexec/generic: .ignore at project root and child directories.

VCS ignore files (Git, Mercurial, Bazaar, Darcs, Fossil) are only used if the corresponding VCS is discovered to be in use for the project/origin. For example, a .bzrignore in a Git repository will be discarded.

Don't load global ignores

This disables loading of global or user ignore files, like '~/.gitignore', '~/.config/watchexec/ignore', or '%APPDATA%\Bazzar\2.0\ignore'. Contrast with '--no-vcs-ignore' and '--no-project-ignore'.

Supported global ignore files


- Git (if core.excludesFile is set): the file at that path
- Git (otherwise): the first found of $XDG_CONFIG_HOME/git/ignore, %APPDATA%/.gitignore, %USERPROFILE%/.gitignore, $HOME/.config/git/ignore, $HOME/.gitignore.
- Bazaar: the first found of %APPDATA%/Bazzar/2.0/ignore, $HOME/.bazaar/ignore.
- Watchexec: the first found of $XDG_CONFIG_HOME/watchexec/ignore, %APPDATA%/watchexec/ignore, %USERPROFILE%/.watchexec/ignore, $HOME/.watchexec/ignore.

Like for project files, Git and Bazaar global files will only be used for the corresponding VCS as used in the project.

Don't use internal default ignores

Watchexec has a set of default ignore patterns, such as editor swap files, `*.pyc`, `*.pyo`, `.DS_Store`, `.bzr`, `_darcs`, `.fossil-settings`, `.git`, `.hg`, `.pijul`, `.svn`, and Watchexec log files.

Don't discover ignore files at all

This is a shorthand for '--no-global-ignore', '--no-vcs-ignore', '--no-project-ignore', but even more efficient as it will skip all the ignore discovery mechanisms from the get go.

Note that default ignores are still loaded, see '--no-default-ignore'.

Don't ignore anything at all

This is a shorthand for '--no-discover-ignore', '--no-default-ignore'.

Note that ignores explicitly loaded via other command line options, such as '--ignore' or '--ignore-file', will still be used.

Wait until first change before running command

By default, Watchexec will run the command once immediately. With this option, it will instead wait until an event is detected before running the command as normal.

Sleep before running the command

This option will cause Watchexec to sleep for the specified amount of time before running the command, after an event is detected. This is like using "sleep 5 && command" in a shell, but portable and slightly more efficient.

Takes a unit-less value in seconds, or a time span value such as "2min 5s". Providing a unit-less value is deprecated and will warn; it will be an error in the future.

Poll for filesystem changes

By default, and where available, Watchexec uses the operating system's native file system watching capabilities. This option disables that and instead uses a polling mechanism, which is less efficient but can work around issues with some file systems (like network shares) or edge cases.

Optionally takes a unit-less value in milliseconds, or a time span value such as "2s 500ms", to use as the polling interval. If not specified, the default is 30 seconds. Providing a unit-less value is deprecated and will warn; it will be an error in the future.

Aliased as '--force-poll'.

Use a different shell

By default, Watchexec will use '$SHELL' if it's defined or a default of 'sh' on Unix-likes, and either 'pwsh', 'powershell', or 'cmd' (CMD.EXE) on Windows, depending on what Watchexec detects is the running shell.

With this option, you can override that and use a different shell, for example one with more features or one which has your custom aliases and functions.

If the value has spaces, it is parsed as a command line, and the first word used as the shell program, with the rest as arguments to the shell.

The command is run with the '-c' flag (except for 'cmd' on Windows, where it's '/C').

The special value 'none' can be used to disable shell use entirely. In that case, the command provided to Watchexec will be parsed, with the first word being the executable and the rest being the arguments, and executed directly. Note that this parsing is rudimentary, and may not work as expected in all cases.

Using 'none' is a little more efficient and can enable a stricter interpretation of the input, but it also means that you can't use shell features like globbing, redirection, control flow, logic, or pipes.

Examples:

Use without shell:

$ watchexec -n -- zsh -x -o shwordsplit scr

Use with powershell core:

$ watchexec --shell=pwsh -- Test-Connection localhost

Use with CMD.exe:

$ watchexec --shell=cmd -- dir

Use with a different unix shell:

$ watchexec --shell=bash -- 'echo $BASH_VERSION'

Use with a unix shell and options:

$ watchexec --shell='zsh -x -o shwordsplit' -- scr

Shorthand for '--shell=none'
Configure event emission

Watchexec can emit event information when running a command, which can be used by the child process to target specific changed files.

One thing to take care with is assuming inherent behaviour where there is only chance. Notably, it could appear as if the `RENAMED` variable contains both the original and the new path being renamed. In previous versions, it would even appear on some platforms as if the original always came before the new. However, none of this was true. It's impossible to reliably and portably know which changed path is the old or new, "half" renames may appear (only the original, only the new), "unknown" renames may appear (change was a rename, but whether it was the old or new isn't known), rename events might split across two debouncing boundaries, and so on.

This option controls where that information is emitted. It defaults to 'none', which doesn't emit event information at all. The other options are 'environment' (deprecated), 'stdio', 'file', 'json-stdio', and 'json-file'.

The 'stdio' and 'file' modes are text-based: 'stdio' writes absolute paths to the stdin of the command, one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`, or `other:`, then closes the handle; 'file' writes the same thing to a temporary file, and its path is given with the $WATCHEXEC_EVENTS_FILE environment variable.

There are also two JSON modes, which are based on JSON objects and can represent the full set of events Watchexec handles. Here's an example of a folder being created on Linux:

```json
{
"tags": [
{
"kind": "path",
"absolute": "/home/user/your/new-folder",
"filetype": "dir"
},
{
"kind": "fs",
"simple": "create",
"full": "Create(Folder)"
},
{
"kind": "source",
"source": "filesystem",
}
],
"metadata": {
"notify-backend": "inotify"
}
} ```

The fields are as follows:


- `tags`, structured event data.
- `tags[].kind`, which can be:
* 'path', along with:
+ `absolute`, an absolute path.
+ `filetype`, a file type if known ('dir', 'file', 'symlink', 'other').
* 'fs':
+ `simple`, the "simple" event type ('access', 'create', 'modify', 'remove', or 'other').
+ `full`, the "full" event type, which is too complex to fully describe here, but looks like 'General(Precise(Specific))'.
* 'source', along with:
+ `source`, the source of the event ('filesystem', 'keyboard', 'mouse', 'os', 'time', 'internal').
* 'keyboard', along with:
+ `keycode`. Currently only the value 'eof' is supported.
* 'process', for events caused by processes:
+ `pid`, the process ID.
* 'signal', for signals sent to Watchexec:
+ `signal`, the normalised signal name ('hangup', 'interrupt', 'quit', 'terminate', 'user1', 'user2').
* 'completion', for when a command ends:
+ `disposition`, the exit disposition ('success', 'error', 'signal', 'stop', 'exception', 'continued').
+ `code`, the exit, signal, stop, or exception code.
- `metadata`, additional information about the event.

The 'json-stdio' mode will emit JSON events to the standard input of the command, one per line, then close stdin. The 'json-file' mode will create a temporary file, write the events to it, and provide the path to the file with the $WATCHEXEC_EVENTS_FILE environment variable.

Finally, the 'environment' mode was the default until 2.0. It sets environment variables with the paths of the affected files, for filesystem events:

$WATCHEXEC_COMMON_PATH is set to the longest common path of all of the below variables, and so should be prepended to each path to obtain the full/real path. Then:


- $WATCHEXEC_CREATED_PATH is set when files/folders were created
- $WATCHEXEC_REMOVED_PATH is set when files/folders were removed
- $WATCHEXEC_RENAMED_PATH is set when files/folders were renamed
- $WATCHEXEC_WRITTEN_PATH is set when files/folders were modified
- $WATCHEXEC_META_CHANGED_PATH is set when files/folders' metadata were modified
- $WATCHEXEC_OTHERWISE_CHANGED_PATH is set for every other kind of pathed event

Multiple paths are separated by the system path separator, ';' on Windows and ':' on unix. Within each variable, paths are deduplicated and sorted in binary order (i.e. neither Unicode nor locale aware).

This is the legacy mode, is deprecated, and will be removed in the future. The environment is a very restricted space, while also limited in what it can usefully represent. Large numbers of files will either cause the environment to be truncated, or may error or crash the process entirely. The $WATCHEXEC_COMMON_PATH is also unintuitive, as demonstrated by the multiple confused queries that have landed in my inbox over the years.

Default: none
Only emit events to stdout, run no commands.

This is a convenience option for using Watchexec as a file watcher, without running any commands. It is almost equivalent to using `cat` as the command, except that it will not spawn a new process for each event.

This option requires `--emit-events-to` to be set, and restricts the available modes to `stdio` and `json-stdio`, modifying their behaviour to write to stdout instead of the stdin of the command.

Add env vars to the command

This is a convenience option for setting environment variables for the command, without setting them for the Watchexec process itself.

Use key=value syntax. Multiple variables can be set by repeating the option.

Configure how the process is wrapped

By default, Watchexec will run the command in a process group in Unix, and in a Job Object in Windows.

Some Unix programs prefer running in a session, while others do not work in a process group.

Use 'group' to use a process group, 'session' to use a process session, and 'none' to run the command directly. On Windows, either of 'group' or 'session' will use a Job Object.

Default: group
Alert when commands start and end

With this, Watchexec will emit a desktop notification when a command starts and ends, on supported platforms. On unsupported platforms, it may silently do nothing, or log a warning.

When to use terminal colours

Setting the environment variable `NO_COLOR` to any value is equivalent to `--color=never`.

Default: auto
Print how long the command took to run

This may not be exactly accurate, as it includes some overhead from Watchexec itself. Use the `time` utility, high-precision timers, or benchmarking tools for more accurate results.

Don't print starting and stopping messages

By default Watchexec will print a message when the command starts and stops. This option disables this behaviour, so only the command's output, warnings, and errors will be printed.

Ring the terminal bell on command completion
Set the project origin

Watchexec will attempt to discover the project's "origin" (or "root") by searching for a variety of markers, like files or directory patterns. It does its best but sometimes gets it it wrong, and you can override that with this option.

The project origin is used to determine the path of certain ignore files, which VCS is being used, the meaning of a leading '/' in filtering patterns, and maybe more in the future.

When set, Watchexec will also not bother searching, which can be significantly faster.

Set the working directory

By default, the working directory of the command is the working directory of Watchexec. You can change that with this option. Note that paths may be less intuitive to use with this.

Filename extensions to filter to

This is a quick filter to only emit events for files with the given extensions. Extensions can be given with or without the leading dot (e.g. 'js' or '.js'). Multiple extensions can be given by repeating the option or by separating them with commas.

Filename patterns to filter to

Provide a glob-like filter pattern, and only events for files matching the pattern will be emitted. Multiple patterns can be given by repeating the option. Events that are not from files (e.g. signals, keyboard events) will pass through untouched.

Files to load filters from

Provide a path to a file containing filters, one per line. Empty lines and lines starting with '#' are ignored. Uses the same pattern format as the '--filter' option.

This can also be used via the $WATCHEXEC_FILTER_FILES environment variable.

[experimental] Filter programs.

/!\ This option is EXPERIMENTAL and may change and/or vanish without notice.

Provide your own custom filter programs in jaq (similar to jq) syntax. Programs are given an event in the same format as described in '--emit-events-to' and must return a boolean. Invalid programs will make watchexec fail to start; use '-v' to see program runtime errors.

In addition to the jaq stdlib, watchexec adds some custom filter definitions:

- 'path | file_meta' returns file metadata or null if the file does not exist.

- 'path | file_size' returns the size of the file at path, or null if it does not exist.

- 'path | file_read(bytes)' returns a string with the first n bytes of the file at path. If the file is smaller than n bytes, the whole file is returned. There is no filter to read the whole file at once to encourage limiting the amount of data read and processed.

- 'string | hash', and 'path | file_hash' return the hash of the string or file at path. No guarantee is made about the algorithm used: treat it as an opaque value.

- 'any | kv_store(key)', 'kv_fetch(key)', and 'kv_clear' provide a simple key-value store. Data is kept in memory only, there is no persistence. Consistency is not guaranteed.

- 'any | printout', 'any | printerr', and 'any | log(level)' will print or log any given value to stdout, stderr, or the log (levels = error, warn, info, debug, trace), and pass the value through (so '[1] | log("debug") | .[]' will produce a '1' and log '[1]').

All filtering done with such programs, and especially those using kv or filesystem access, is much slower than the other filtering methods. If filtering is too slow, events will back up and stall watchexec. Take care when designing your filters.

If the argument to this option starts with an '@', the rest of the argument is taken to be the path to a file containing a jaq program.

Jaq programs are run in order, after all other filters, and short-circuit: if a filter (jaq or not) rejects an event, execution stops there, and no other filters are run. Additionally, they stop after outputting the first value, so you'll want to use 'any' or 'all' when iterating, otherwise only the first item will be processed, which can be quite confusing!

Find user-contributed programs or submit your own useful ones at https://github.com/watchexec/watchexec/discussions/592.

## Examples:

Regexp ignore filter on paths:

'all(.tags[] | select(.kind == "path"); .absolute | test("[.]test[.]js$")) | not'

Pass any event that creates a file:

'any(.tags[] | select(.kind == "fs"); .simple == "create")'

Pass events that touch executable files:

'any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | metadata | .executable)'

Ignore files that start with shebangs:

'any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | read(2) == "#!") | not'

Filename patterns to filter out

Provide a glob-like filter pattern, and events for files matching the pattern will be excluded. Multiple patterns can be given by repeating the option. Events that are not from files (e.g. signals, keyboard events) will pass through untouched.

Files to load ignores from

Provide a path to a file containing ignores, one per line. Empty lines and lines starting with '#' are ignored. Uses the same pattern format as the '--ignore' option.

This can also be used via the $WATCHEXEC_IGNORE_FILES environment variable.

Filesystem events to filter to

This is a quick filter to only emit events for the given types of filesystem changes. Choose from 'access', 'create', 'remove', 'rename', 'modify', 'metadata'. Multiple types can be given by repeating the option or by separating them with commas. By default, this is all types except for 'access'.

This may apply filtering at the kernel level when possible, which can be more efficient, but may be more confusing when reading the logs.

Default: create,remove,rename,modify,metadata
Don't emit fs events for metadata changes

This is a shorthand for '--fs-events create,remove,rename,modify'. Using it alongside the '--fs-events' option is non-sensical and not allowed.

Print events that trigger actions

This prints the events that triggered the action when handling it (after debouncing), in a human readable form. This is useful for debugging filters.

Use '-vvv' instead when you need more diagnostic information.

Show the manual page

This shows the manual page for Watchexec, if the output is a terminal and the 'man' program is available. If not, the manual page is printed to stdout in ROFF format (suitable for writing to a watchexec.1 file). Arguments:

<TASK>
Tasks to run Can specify multiple tasks by separating with `:::` e.g.: `mise run task1 arg1 arg2 ::: task2 arg1 arg2`
<ARGS>
Task and arguments to run

Display the installation path for a tool

The tool must be installed for this to work.

Usage: mise where <TOOL@VERSION> [<ASDF_VERSION>]

Arguments:

<TOOL@VERSION>
Tool(s) to look up e.g.: ruby@3 if "@<PREFIX>" is specified, it will show the latest installed version that matches the prefix otherwise, it will show the current, active installed version
<ASDF_VERSION>
the version prefix to use when querying the latest version same as the first argument after the "@" used for asdf compatibility

Shows the path that a tool's bin points to.

Use this to figure out what version of a tool is currently active.

Usage: mise which [OPTIONS] [<BIN_NAME>]

Options:

Use a specific tool@version e.g.: `mise which npm --tool=node@20`
Show the plugin name instead of the path
Show the version instead of the path Arguments:
<BIN_NAME>
The bin to look up