Walkthrough

Once you've completed the Getting Started guide, you're ready to start using mise. This document offers a quick overview of some things you may want to try first.

Installing Dev Tools

The main command for working with tools in mise is mise u|use. It does two things:

• Installs the tool (if not already installed)
• Adds the tool to the mise.toml config file—in mise, I say a tool is "active" if it's in mise.toml

WARNING

Both steps are required to use a tool. If you only install a tool with mise install, it won't be available in your shell. It must also be added to mise.toml—which is why I recommend mise use, since it does both.

Use it like so (mise must be activated for this example to work):

mkdir example-project && cd example-project
mise use node@26
node -v
# v26.x.x

You'll also notice that you now have a mise.toml file with the following content:

mise.toml

[tools]
node = "26"

• If this file is in the root of a project, node will be installed whenever someone runs mise install|i.
• mise install is the command to run when you first clone a project or when you want to update installed tools.

mise.toml Configuration

You can create a mise.toml file manually or with the CLI.

TIP

Use mise edit to open an interactive editor for your configuration. It provides a TUI where you can navigate sections, add tools from the registry with fuzzy search, and configure settings with schema-aware autocompletion.

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 ideal for personal preferences or configuration.

mise supports nested configuration files that cascade from broad to specific settings:

1. ~/.config/mise/config.toml - Global settings for all projects
2. ~/work/mise.toml - Work-specific settings
3. ~/work/project/mise.toml - Project-specific settings
4. ~/work/project/mise.local.toml - Project-specific settings that should not be shared

mise combines the config files from all parent directories to determine the set of tools—with lower levels of the hierarchy overriding higher ones.

TIP

Use mise config ls to see the configuration files currently used by mise.

In general, prefer loose versions like node@26 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 enforce a specific version, use mise use --pin or the lockfile setting.

If you leave out the version, mise defaults to node@latest.

Dev Tool Backends

Tools are installed with a variety of backends like aqua, github, or gitlab. 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

Upgrade tool versions with mise up|upgrade. By default, it respects the version prefix in mise.toml. If a lockfile exists, mise updates mise.lock to the latest version of the tool matching the prefix from mise.toml.

So if you have node = "26" in mise.toml, then mise upgrade node will upgrade to the latest version of node 26.

To update the version in mise.toml to something newer, use mise upgrade --bump node. It keeps the same specificity as the current version: if you have node = "24" and mise upgrade --bump node updates to node@26, it will set node = "26" in mise.toml.

See Dev Tools for more information on working with tools.

Setting Environment Variables

mise can also set environment variables for your project. You can set them with the CLI:

mise set MY_VAR=123
echo $MY_VAR
# 123

Or by directly modifying mise.toml:

[env]
MY_VAR = "123"

Some examples of where this is useful:

• Setting NODE_ENV for a Node.js project
• Setting DATABASE_URL for a database connection
• Setting RUST_TEST_THREADS=1 to run cargo tests in series

Do not set secrets in a project's mise.toml, as the file is intended to be added to version control. Use mise.local.toml instead for secrets.

You can also modify PATH with mise.toml. This example makes CLIs installed with npm available:

[env]
_.path = "./node_modules/.bin"

This adds ./node_modules/.bin to the PATH for the project. Here "." refers to the directory containing the mise.toml file, so the entry still works if you enter a subdirectory.

See Environments for more information on working with environment variables.

Tasks

Tasks are defined in a project to execute commands.

You can define tasks in a mise.toml:

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:

mise-tasks/build

#!/bin/bash
npm run build

Tasks are executed with mise r|run:

mise run build
mise run test

TIP

mise run sets up the "mise environment" (tools and environment variables) before running the task. So if you'd rather not activate mise in your shell, you can use mise run to run tasks with the tools on 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:

mise-tasks/greet

#!/usr/bin/env bash
set -e

#MISE description="Greet a user with a message"
#USAGE flag "-g --greeting <greeting>" help="The greeting word to use" {
#USAGE   choices "hi" "hello" "hey"
#USAGE }
#USAGE flag "-u --user <user>" help="The user to greet"
#USAGE flag "--dir <dir>" help="The directory to greet from" default="."
#USAGE complete "dir" run="find . -maxdepth 1 -type d"
#USAGE arg "<message>" help="Greeting message"

echo "all available options are in the env with the prefix 'usage_'"
env | grep usage_

echo "${usage_greeting?}, ${usage_user?}! Your message is: ${usage_message?}"

This task can be run like so:

mise run greet --user jdx -g "hey" "How are you?"

• All options are passed as environment variables prefixed with usage_, like usage_user.
• Help is available with mise run greet --help, which shows the options defined in the task.
• Completions are available like you'd expect, so typing mise run greet --greeting <tab> will show hi, hello, and hey as options.
• Custom completion can be provided by a CLI. mise run greet --dir <tab> will execute find . -maxdepth 1 -type d to provide completions.

To get the autocompletion working, set up mise autocompletions.

See Tasks for more information on working with tasks.

Common Commands

mise has a lot of commands; here are the ones I consider most important:

• mise completion – Set up completions for your shell.
• mise cfg|config – A bunch of commands for working with mise.toml files via the CLI.
• mise x|exec – Execute a command in the mise environment without activating mise.
• mise g|generate – Generate things like git hooks, task documentation, GitHub actions, and more for your project.
• mise i|install – Install tools.
• mise link – Symlink a tool installed by some other means into mise.
• mise ls-remote – List all available versions of a tool.
• mise ls – List information about installed/active tools.
• mise outdated – Report any tools with newer versions available.
• mise plugin – Manage plugins, which extend mise with new functionality like extra tools or environment variable management. Commonly, these are asdf plugins or modern plugins.
• mise r|run – Run a task defined in mise.toml or mise-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 rm|uninstall – Uninstall a tool.
• mise up|upgrade – Upgrade tool versions.
• mise u|use – Install and activate tools.
• mise w|watch – 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 a consistent UX for working with projects regardless of the programming languages or tools they use.

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, or watchexec which point to core:node, aqua:hashicorp/terraform, and aqua:watchexec/watchexec respectively
• CLI – The full list of commands available in mise