Walkthrough
Once you've completed the Getting Started guide, you're ready to start using mise. This document offers a quick overview on some initial things you may want to try out.
Installing Dev Tools
The main command for working with tools in mise is mise use|u
. This does 2 main things:
- Installs tools (if not already installed)
- Adds the tool to the
mise.toml
configuration file—in mise I say the tool is "active" if it's inmise.toml
WARNING
Both of these are required to use a tool. If you simply install a tool via mise install
, it won't be available in your shell. It must also be added to mise.toml
—which is why I promote using mise use
since it does both.
You use it like so (note that mise
must be activated for this to work):
mkdir example-project && cd example-project
mise use node@22
node -v
# v22.0.0
And you'll also note that you now have a mise.toml
file with the following content:
cat mise.toml
[tools]
node = "22"
- If this file is in the root of a project,
node
will be installed whenever someone runsmise install|i
. - This is the command you want to run when you first clone a project or when you want to update installed tools.
mise.toml
Configuration
Use mise.toml
to share your tool configurations with others. This file should be committed to version control and contains the common toolset needed for your project.
For tools or settings you want to keep private, use mise.local.toml
. This file should be added to .gitignore
and is perfect for personal preferences or configurations.
mise
supports nested configuration files that cascade from broad to specific settings:
~/.config/mise/config.toml
- Global settings for all projects~/work/mise.toml
- Work-specific settings~/work/project/mise.toml
- Project-specific settings~/work/project/mise.local.toml
- Project-specific settings that should not be shared
mise
will use all the parent directories together to determine the set of tools—overriding configuration as it goes lower in the hierarchy.
TIP
Use mise config ls
to see the configuration files currently used by mise
.
In general, it's preferred to use loose versions like this in mise
so that other people working on a project don't have to worry about the exact version of a tool you're using. If you'd like to pin the version to enforce a specific version, use mise use --pin
or the lockfile
setting.
If you leave out the version, then mise will default to node@latest
.
Dev Tool Backends
Tools are installed with a variety of backends like asdf
, ubi
, or vfox
. See registry for the full list of shorthands like node
you can use.
You can also use other backends like npm
or cargo
which can install any package from their respective registries:
mise use npm:@antfu/ni
mise use cargo:starship
Upgrading Dev Tools
Upgrading tool versions can be done with mise upgrade|up
. By default, it will respect the version prefix in mise.toml
. If a lockfile exists, mise will update mise.lock
to the latest version of the tool with the prefix from mise.toml
.
So if you have node = "22"
in mise.toml
, then mise upgrade node
will upgrade to the latest version of node 22
.
If you'd like to upgrade to the latest version of node, you can use mise upgrade --bump node
. It will set the version at the same specificity as the current version, so if you have node = "22"
, but use mise upgrade --bump node
to update to node@24
, then it will set node = "24"
in mise.toml
.
See Dev Tools for more information on working with tools.
Setting Environment Variables
mise can also be used to set environment variables for your project. You can set environment variables with the CLI:
mise set MY_VAR=123
echo $MY_VAR
# 123
Or by directly modifying mise.toml
:
[env]
MY_VAR = "123"
Some examples on where this can be used:
- Setting
NODE_ENV
for a Node.js project - Setting
DATABASE_URL
for a database connection - Setting
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
for AWS - Setting
RUST_TEST_THREADS=1
to run cargo tests in series
You can also modify PATH
with mise.toml
. This example makes CLIs installed with npm
available:
[env]
_.path = "./node_modules/.bin"
This will add ./node_modules/.bin
to the PATH for the project—with "." here referring to the directory the mise.toml
file is in so if you enter a subdirectory, it will still work.
See Environments for more information on working with environment variables.
Tasks
Tasks are defined in a project to execute commands. They are defined in mise.toml
:
[tasks]
build = "npm run build"
test = "npm test"
Or in a mise-tasks
directory as a standalone file, such as mise-tasks/build
:
#!/bin/bash
npm run build
Tasks are executed with mise run|r
:
mise run build
mise run test
TIP
mise run
setups up the "mise environment" before running the task (tools and environment variables). So if you'd rather not activate mise in your shell, you can use mise run
to run tasks, and it will have the tools in PATH and the environment variables from mise.toml
set.
mise is paired with usage which provides lots of features for documenting and running tasks.
Here is an example of a task with usage spec:
#!/bin/bash
#USAGE flag "-f --force" "Force the greeting to be displayed"
#USAGE flag "-u --user <user>" "The user to greet"
#USAGE flag "-p --port <port>" default=8080 "The port to listen on"
#USAGE flag "-c --color <color>" "The color to use" {
#USAGE choices "red" "green" "blue"
#USAGE }
#USAGE arg "message" "The message to greet the user with"
#USAGE complete "user" run="mycli users"
echo "Hello, $usage_user! Your message is: $usage_message"
The options will all be passed as environment variables prefixed with usage_
like usage_user
. Help is available with mise run my-task --help
and will show the options defined in the task. Completions are available like you'd expect, so typing mise run my-task --color <tab>
will show "red", "green", and "blue" as options. mise run my-task --user <tab>
will execute mycli users
and use the output as completions.
No extra setup is required for completions so long as mise completions are otherwise set up.
See Tasks for more information on working with tasks.
Common Commands
Since there are a lot of commands available in mise, here are what I consider the most important:
mise completion
– Set up completions for your shell.mise config|cfg
– A bunch of commands for working withmise.toml
files via the CLI.mise exec|x
– Execute a command in the mise environment without activating mise.mise generate|g
– Generates things like git hooks, task documentation, GitHub actions, and more for your project.mise install|i
– Install tools.mise link
– Symlink a tool installed by some other means into the mise.mise ls-remote
– List all available versions of a tool.mise ls
– Lists information about installed/active tools.mise outdated
– Informs you of any tools with newer versions available.mise plugin
– Plugins can extend mise with new functionality like extra tools or environment variable management. Commonly, these are simply asdf/vfox plugins.mise run|r
– Run a task defined inmise.toml
ormise-tasks
.mise self-update
– Update mise to the latest version. Don't use this if you installed mise via a package manager.mise settings
– CLI access to get/set configuration settings.mise uninstall|rm
– Uninstall a tool.mise upgrade|up
– Upgrade tool versions.mise use|u
– Install and activate tools.mise watch|w
– Watch for changes in a project and run tasks when they occur.
Final Thoughts
Dev tools, env vars, and tasks work together to make managing your development environment easier—especially when working with others. The goal is to have a consistent UX to interface with projects regardless of the programming languages or tools used on it.
For further reading:
- Dev Tools – A deeper overview of working with dev tools
- Environments – A deeper overview of working with environment variables
- Tasks – A deeper overview of working with tasks
- Configuration – More information on
mise.toml
files - Settings – All the configuration settings available in mise
- Backends – An index of all the backends available in mise
- Registry – Every "shorthand" available for tools in mise like
node
,terraform
, orwatchexec
which point tocore:node
,asdf:asdf-community/asdf-hashicorp
, andubi:watchexec/watchexec
respectively - CLI – The full list of commands available in mise