<!-- @generated by usage-cli from usage spec -->
# `mise`
- **author**: Jeff Dickey <@jdx>

mise prepares your development environment before each command runs. https://github.com/jdx/mise


- **Usage**: `mise [FLAGS] [TASK] <SUBCOMMAND>`

## Arguments

### `[TASK]`

Task to run.

Shorthand for `mise tasks run <TASK>`.

## Global Flags

### `-C --cd <DIR>`

Change directory before running command

### `-E --env… <ENV>`

Set the environment for loading `mise.<ENV>.toml`

### `-j --jobs <JOBS>`

How many jobs to run in parallel; values below 1 are treated as 1 [default: 8]

**Environment Variable:** `MISE_JOBS`

### `-q --quiet`

Suppress non-error messages

### `-v --verbose…`

Show extra output (use -vv for even more)

### `-y --yes`

Answer yes to all confirmation prompts

### `--raw`

Read/write directly to stdin/stdout/stderr instead of by line

### `--locked`

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

### `--silent`

Suppress all task output and mise non-error messages

## Flags

### `--no-config`

Do not load any config files

Can also use `MISE_NO_CONFIG=1`

### `--no-env`

Do not load environment variables from config files

Can also use `MISE_NO_ENV=1`

### `--no-hooks`

Do not execute hooks from config files

Can also use `MISE_NO_HOOKS=1`

### `--output <OUTPUT>`

## `mise activate`

- **Usage**: `mise activate [FLAGS] [SHELL_TYPE]`
- **Effect**: read-only

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.

### Arguments

#### `[SHELL_TYPE]`

Shell type to generate the script for

**Choices:**

- `bash`
- `elvish`
- `fish`
- `nu`
- `xonsh`
- `zsh`
- `pwsh`

### Flags

#### `-q --quiet`

Suppress non-error messages

#### `--no-hook-env`

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.

#### `--shims`

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

Examples:

    $ eval "$(mise activate bash)"
    $ eval "$(mise activate zsh)"
    $ mise activate fish | source
    $ execx($(mise activate xonsh))
    $ (&mise activate pwsh) | Out-String | Invoke-Expression

## `mise tool-alias`

- **Usage**: `mise tool-alias [-p --tool <TOOL>] [--no-header] <SUBCOMMAND>`
- **Effect**: read-only

Manage tool version aliases.

### Flags

#### `-p --tool <TOOL>`

Filter aliases by tool

#### `--no-header`

Don't show table header

## `mise tool-alias get`

- **Usage**: `mise tool-alias get <TOOL> <ALIAS>`
- **Effect**: read-only

Show an alias for a tool

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

### Arguments

#### `<TOOL>`

The tool to show the alias for

#### `<ALIAS>`

The alias to show

Examples:

    $ mise tool-alias get node lts-hydrogen
    20.0.0

## `mise tool-alias ls`

- **Usage**: `mise tool-alias ls [--no-header] [TOOL]`
- **Aliases**: `list`
- **Effect**: read-only

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"

### Arguments

#### `[TOOL]`

Show aliases for <TOOL>

### Flags

#### `--no-header`

Don't show table header

Examples:

    $ mise tool-alias ls
    node  lts-jod      22

## `mise tool-alias set`

- **Usage**: `mise tool-alias set <ARGS>…`
- **Aliases**: `add`, `create`
- **Effect**: modifies state

Add/update an alias for a tool/backend

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

### Arguments

#### `<TOOL>`

The tool/backend to set the alias for

#### `<ALIAS>`

The alias to set

#### `[VALUE]`

The value to set the alias to

Examples:

    $ mise tool-alias set maven asdf:mise-plugins/mise-maven
    $ mise tool-alias set node lts-jod 22.0.0

## `mise tool-alias unset`

- **Usage**: `mise tool-alias unset <TOOL> [ALIAS]`
- **Aliases**: `rm`, `remove`, `delete`, `del`
- **Effect**: modifies state

Clears an alias for a tool/backend

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

### Arguments

#### `<TOOL>`

The tool/backend to remove the alias from

#### `[ALIAS]`

The alias to remove

Examples:

    $ mise tool-alias unset maven
    $ mise tool-alias unset node lts-jod

## `mise asdf`

- **Usage**: `mise asdf [ARGS]…`

[internal] simulates asdf for plugins that call "asdf" internally

### Arguments

#### `[ARGS]…`

all arguments

## `mise backends`

- **Usage**: `mise backends <SUBCOMMAND>`
- **Effect**: read-only

Manage backends

Deprecation:

The `mise b` alias is deprecated and will be removed in mise 2027.4.0.
Use `mise backends` instead.

## `mise backends ls`

- **Usage**: `mise backends ls`
- **Aliases**: `list`
- **Effect**: read-only

List built-in backends

Examples:

    $ mise backends ls
    aqua
    asdf
    cargo
    core
    dotnet
    gem
    go
    npm
    pipx
    spm
    ubi
    vfox

## `mise bin-paths`

- **Usage**: `mise bin-paths [--bin-names] [-J --json] [TOOL@VERSION]…`
- **Effect**: read-only

List all the active runtime bin paths

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to look up
e.g.: ruby@3

### Flags

#### `--bin-names`

Output executable names instead of bin directories

#### `-J --json`

Output executable entries in JSON format (implies --bin-names)

## `mise bootstrap`

- **Usage**: `mise bootstrap [FLAGS] <SUBCOMMAND>`
- **Effect**: destructive — may delete or irreversibly overwrite

Set up a machine for the current config in one command

Runs the bootstrap steps for the current config in order:

0. `mise bootstrap accounts apply` — converge `[bootstrap.users]` and
   `[bootstrap.groups]` (Linux)
1. `mise bootstrap plugins apply` — install `[bootstrap.plugins]`
   1.7. `[bootstrap.hooks.pre-packages]` — optional setup hook
2. Install built-in-manager entries from `[bootstrap.packages]` 3. `mise bootstrap files apply` — converge `[bootstrap.files]` and
   `[bootstrap.directories]`
4. `mise bootstrap services apply` — converge `[bootstrap.services]`
   systemd system services (Linux)
5. `mise bootstrap firewall apply` — converge `[bootstrap.linux.firewall]`
   host firewall policy and rules (Linux)
6. `mise bootstrap compose apply` — converge `[bootstrap.compose]`
   Docker Compose projects
7. `mise bootstrap repos apply` — clone/converge `[bootstrap.repos]`
   surrounded by `pre-repos`/`post-repos` hooks
8. `mise bootstrap dotfiles apply` — apply dotfiles from `[dotfiles]`
   surrounded by `pre-dotfiles`/`post-dotfiles` hooks
9. `mise bootstrap mise-shell-activate apply` — configure shell activation
   from `[bootstrap.mise_shell_activate]`
10. `mise bootstrap macos defaults apply` — write
    `[bootstrap.macos.defaults]` entries (macOS)
    surrounded by `pre-defaults`/`post-defaults` hooks
11. `mise bootstrap macos launchd-agents apply` — install/load
    `[bootstrap.macos.launchd.agents]`
12. `mise bootstrap linux systemd-units apply` — install/start
    `[bootstrap.linux.systemd.units]`
13. `mise bootstrap user apply` — set `[bootstrap.user].login_shell`
    (Unix)
    surrounded by `pre-user`/`post-user` hooks
14. `mise install` — install missing tools from `[tools]`
    surrounded by `pre-tools`/`post-tools` hooks; package-plugin entries
    from `[bootstrap.packages]` install afterward, followed by
    `[bootstrap.hooks.post-packages]`
15. `mise run bootstrap` — if a task named `bootstrap` is defined 16. `[bootstrap.hooks.final]` — optional final hook

The declarative steps converge — anything already in its desired state is skipped, so re-running is safe. The `bootstrap` task runs on every invocation; keep it idempotent. Use it for any project-specific setup that doesn't fit the declarative sections (seeding databases, auth flows, etc.) — it runs with the installed tools on PATH.

Use `--skip <part>` to skip named parts, or `--only <part>` to run just named parts. Both flags can be repeated or comma-separated, but they cannot be used together.

### Flags

#### `-n --dry-run`

Print what would happen without installing anything

#### `-y --yes`

Skip confirmation prompts

#### `--force-dotfiles`

Overwrite existing files that conflict with whole-file dotfile entries

#### `--only… <ONLY>`

Run only one or more bootstrap parts

Can be passed multiple times or as a comma-separated list. Cannot be used with `--skip`.

**Choices:**

- `plugins`
- `packages`
- `accounts`
- `files`
- `services`
- `firewall`
- `compose`
- `repos`
- `dotfiles`
- `mise-shell-activate`
- `macos-defaults`
- `macos-launchd-agents`
- `linux-systemd-units`
- `user`
- `tools`
- `task`
- `final-hook`

#### `--prompt-secrets`

Prompt securely for missing bootstrap secret inputs

#### `--skip… <SKIP>`

Skip one or more bootstrap parts

Can be passed multiple times or as a comma-separated list.

**Choices:**

- `plugins`
- `packages`
- `accounts`
- `files`
- `services`
- `firewall`
- `compose`
- `repos`
- `dotfiles`
- `mise-shell-activate`
- `macos-defaults`
- `macos-launchd-agents`
- `linux-systemd-units`
- `user`
- `tools`
- `task`
- `final-hook`

#### `--update`

Refresh package manager metadata and update configured repos

Examples:

    $ mise bootstrap                    # packages + repos + dotfiles + tools + bootstrap task
    $ mise bootstrap --force-dotfiles   # replace conflicting dotfile targets
    $ mise bootstrap --skip tools,task  # skip tool installation and the bootstrap task
    $ mise bootstrap --only tools       # run just tool installation
    $ mise bootstrap status --missing
    $ mise bootstrap packages apply --yes
    $ mise bootstrap repos status
    $ mise bootstrap repos apply --dry-run
    $ mise bootstrap dotfiles status
    $ mise bootstrap mise-shell-activate apply --dry-run
    $ mise bootstrap macos defaults status
    $ mise bootstrap macos launchd-agents apply --dry-run
    $ mise bootstrap linux systemd-units apply --dry-run
    $ mise bootstrap user apply --dry-run

## `mise bootstrap __apply-account-plan`

- **Usage**: `mise bootstrap __apply-account-plan`
- **Effect**: destructive — may delete or irreversibly overwrite

## `mise bootstrap __apply-service-plan`

- **Usage**: `mise bootstrap __apply-service-plan`
- **Effect**: destructive — may delete or irreversibly overwrite

## `mise bootstrap __apply-firewall-plan`

- **Usage**: `mise bootstrap __apply-firewall-plan`
- **Effect**: destructive — may delete or irreversibly overwrite

## `mise bootstrap __apply-system-plan`

- **Usage**: `mise bootstrap __apply-system-plan`
- **Effect**: destructive — may delete or irreversibly overwrite

## `mise bootstrap __inspect-system-files`

- **Usage**: `mise bootstrap __inspect-system-files`
- **Effect**: read-only

## `mise bootstrap __inspect-firewall-plan`

- **Usage**: `mise bootstrap __inspect-firewall-plan`
- **Effect**: read-only

## `mise bootstrap accounts`

- **Usage**: `mise bootstrap accounts <SUBCOMMAND>`
- **Effect**: read-only

Manage Linux users and groups from `[bootstrap.users]` and `[bootstrap.groups]`

## `mise bootstrap accounts apply`

- **Usage**: `mise bootstrap accounts apply [-n --dry-run] [-y --yes]`
- **Effect**: destructive — may delete or irreversibly overwrite

Apply configured Linux users and groups

### Flags

#### `-n --dry-run`

Print what would change without changing anything

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap accounts status`

- **Usage**: `mise bootstrap accounts status [-J --json] [--missing]`
- **Effect**: read-only

Show configured Linux user and group state

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 when any account is not converged

## `mise bootstrap compose`

- **Usage**: `mise bootstrap compose <SUBCOMMAND>`
- **Effect**: read-only

Manage Docker Compose projects from `[bootstrap.compose]`

## `mise bootstrap compose apply`

- **Usage**: `mise bootstrap compose apply [-n --dry-run] [-y --yes]`
- **Effect**: destructive — may delete or irreversibly overwrite

Apply configured Docker Compose project state

### Flags

#### `-n --dry-run`

Print what would change without changing anything

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap compose status`

- **Usage**: `mise bootstrap compose status [-J --json] [--missing]`
- **Effect**: read-only

Show configured Docker Compose project state

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 when any Compose project is not converged

## `mise bootstrap dotfiles`

- **Usage**: `mise bootstrap dotfiles <SUBCOMMAND>`
- **Effect**: read-only

Manage dotfiles from `[dotfiles]`

## `mise bootstrap dotfiles add`

- **Usage**: `mise bootstrap dotfiles add [FLAGS] <TARGET>…`
- **Effect**: modifies state

Add or update dotfiles in `[dotfiles]`

If the target is already managed, this updates its source from the live target. Otherwise it creates a `[dotfiles]` entry and seeds the source under `dotfiles.root` unless `--source` is provided.

### Arguments

#### `<TARGET>…`

Targets to add or update

### Flags

#### `-f --force`

Overwrite existing sources without prompting

#### `-g --global`

Write to the global config

#### `-l --local`

Write to the local config instead of the global config

#### `-m --mode <MODE>`

Dotfile mode to write

#### `-n --dry-run`

Print the config/source updates without writing anything

#### `--no-apply`

Add the entry without applying it

#### `-p --path <PATH>`

Write to this config file or directory

#### `-s --source <PATH>`

Source path to use for a single target

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles add ~/.zshrc
    $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml
    $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig

## `mise bootstrap dotfiles apply`

- **Usage**: `mise bootstrap dotfiles apply [FLAGS] [TARGET]…`
- **Effect**: modifies state

Apply dotfiles from `[dotfiles]`

Applies configured whole-file entries and edits that aren't in their desired state. Whole-file entries may symlink, copy, or render templates. Edit entries manage a marker-delimited block or a single line in a file mise doesn't otherwise own.

### Arguments

#### `[TARGET]…`

Only apply these targets

### Flags

#### `-f --force`

Overwrite existing files that conflict with whole-file dotfile entries

#### `-n --dry-run`

Print the actions that would run without writing anything

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles apply
    $ mise bootstrap dotfiles apply --dry-run
    $ mise bootstrap dotfiles apply --force --yes

## `mise bootstrap dotfiles edit`

- **Usage**: `mise bootstrap dotfiles edit [FLAGS] <TARGET>`
- **Effect**: modifies state

Edit a managed dotfile source

### Arguments

#### `<TARGET>`

Target to edit

### Flags

#### `--apply`

Apply this target after the editor exits

#### `-m --mode <MODE>`

Dotfile mode to use if the target is not yet managed

#### `-s --source <PATH>`

Source path to use if the target is not yet managed

#### `-y --yes`

Skip the confirmation prompt when adding an unmanaged target

Examples:

    $ mise bootstrap dotfiles edit ~/.zshrc
    $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml

## `mise bootstrap dotfiles status`

- **Usage**: `mise bootstrap dotfiles status [-J --json] [--missing] [TARGET]…`
- **Effect**: read-only

Show the status of dotfiles from `[dotfiles]`

### Arguments

#### `[TARGET]…`

Only show these targets

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured dotfiles are not in their desired
state (missing, source missing, differs)

Examples:

    $ mise bootstrap dotfiles status
    $ mise bootstrap dotfiles status ~/.zshrc
    $ mise bootstrap dotfiles status --json
    $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync

## `mise bootstrap dotfiles unapply`

- **Usage**: `mise bootstrap dotfiles unapply [FLAGS] [TARGET]…`
- **Effect**: destructive — may delete or irreversibly overwrite

Remove dotfiles applied from `[dotfiles]`

Removes configured whole-file entries and edits while preserving files mise cannot identify as managed. Modified copies, templates, and plain-line edits require `--force`.

### Arguments

#### `[TARGET]…`

Only unapply these targets

### Flags

#### `-f --force`

Remove modified or otherwise ambiguous managed files and lines

#### `-n --dry-run`

Print the actions that would run without writing anything

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles unapply
    $ mise bootstrap dotfiles unapply ~/.zshrc
    $ mise bootstrap dotfiles unapply --dry-run
    $ mise bootstrap dotfiles unapply --force --yes

## `mise bootstrap files`

- **Usage**: `mise bootstrap files <SUBCOMMAND>`
- **Effect**: read-only

Manage privileged files and directories from `[bootstrap.files]` and `[bootstrap.directories]`

## `mise bootstrap files apply`

- **Usage**: `mise bootstrap files apply [FLAGS]`
- **Effect**: destructive — may delete or irreversibly overwrite

Apply configured privileged files and directories

### Flags

#### `-n --dry-run`

Print what would change without changing anything

#### `-y --yes`

Skip the confirmation prompt

#### `--prompt-secrets`

Prompt securely for missing bootstrap secret inputs

## `mise bootstrap files status`

- **Usage**: `mise bootstrap files status [FLAGS]`
- **Effect**: read-only

Show configured privileged file and directory state

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 when any resource is not converged

#### `--prompt-secrets`

Prompt securely for missing bootstrap secret inputs

## `mise bootstrap firewall`

- **Usage**: `mise bootstrap firewall <SUBCOMMAND>`
- **Effect**: read-only

Manage the Linux host firewall from `[bootstrap.linux.firewall]`

## `mise bootstrap firewall apply`

- **Usage**: `mise bootstrap firewall apply [-n --dry-run] [-y --yes]`
- **Effect**: destructive — may delete or irreversibly overwrite

Apply the configured Linux host firewall

### Flags

#### `-n --dry-run`

Print what would change without changing anything

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap firewall status`

- **Usage**: `mise bootstrap firewall status [-J --json] [--missing]`
- **Effect**: read-only

Show configured Linux host firewall state

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 when the firewall is not converged

## `mise bootstrap launchd`

- **Usage**: `mise bootstrap launchd <SUBCOMMAND>`
- **Effect**: read-only

Manage macOS LaunchAgents from `[bootstrap.macos.launchd.agents]`

## `mise bootstrap launchd apply`

- **Usage**: `mise bootstrap launchd apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap launchd status`

- **Usage**: `mise bootstrap launchd status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured LaunchAgent is not in its desired state

## `mise bootstrap linux`

- **Usage**: `mise bootstrap linux <SUBCOMMAND>`
- **Effect**: read-only

Manage Linux bootstrap config from `[bootstrap.linux]`

## `mise bootstrap linux systemd-units`

- **Usage**: `mise bootstrap linux systemd-units <SUBCOMMAND>`
- **Effect**: read-only

Manage systemd user services from `[bootstrap.linux.systemd.units]`

## `mise bootstrap linux systemd-units apply`

- **Usage**: `mise bootstrap linux systemd-units apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap linux systemd-units status`

- **Usage**: `mise bootstrap linux systemd-units status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured systemd user service is not in its desired state

## `mise bootstrap macos`

- **Usage**: `mise bootstrap macos <SUBCOMMAND>`
- **Effect**: read-only

Manage macOS bootstrap config from `[bootstrap.macos]`

## `mise bootstrap macos defaults`

- **Usage**: `mise bootstrap macos defaults <SUBCOMMAND>`
- **Effect**: read-only

Manage macOS defaults from `[bootstrap.macos.defaults]`

## `mise bootstrap macos defaults apply`

- **Usage**: `mise bootstrap macos defaults apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap macos defaults status`

- **Usage**: `mise bootstrap macos defaults status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured defaults are not in their desired state

## `mise bootstrap macos launchd-agents`

- **Usage**: `mise bootstrap macos launchd-agents <SUBCOMMAND>`
- **Effect**: read-only

Manage macOS LaunchAgents from `[bootstrap.macos.launchd.agents]`

## `mise bootstrap macos launchd-agents apply`

- **Usage**: `mise bootstrap macos launchd-agents apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap macos launchd-agents status`

- **Usage**: `mise bootstrap macos launchd-agents status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured LaunchAgent is not in its desired state

## `mise bootstrap macos-defaults`

- **Usage**: `mise bootstrap macos-defaults <SUBCOMMAND>`
- **Effect**: read-only

Manage macOS defaults from `[bootstrap.macos.defaults]`

## `mise bootstrap macos-defaults apply`

- **Usage**: `mise bootstrap macos-defaults apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap macos-defaults status`

- **Usage**: `mise bootstrap macos-defaults status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured defaults are not in their desired state

## `mise bootstrap mise-shell-activate`

- **Usage**: `mise bootstrap mise-shell-activate <SUBCOMMAND>`
- **Effect**: read-only

Manage mise shell activation from `[bootstrap.mise_shell_activate]`

## `mise bootstrap mise-shell-activate apply`

- **Usage**: `mise bootstrap mise-shell-activate apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the actions that would run without writing anything

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap mise-shell-activate status`

- **Usage**: `mise bootstrap mise-shell-activate status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured shell activation is not in its desired state

## `mise bootstrap packages`

- **Usage**: `mise bootstrap packages <SUBCOMMAND>`
- **Effect**: read-only

Manage bootstrap system packages from `[bootstrap.packages]`

## `mise bootstrap packages apply`

- **Usage**: `mise bootstrap packages apply [FLAGS] [PACKAGE]…`
- **Aliases**: `i`
- **Effect**: modifies state

Apply system packages from `[bootstrap.packages]`

Checks which configured packages are missing and installs them with the system package manager. Built-in system managers may elevate with sudo when not running as root (see `system_packages.sudo`); package plugins never do.

Packages can also be given explicitly in `manager:package` form (e.g. `apk:zlib-dev`, `apt:curl`, `brew:jq`); they are installed whether or not they appear in the config. Explicit packages and `--manager` scope the run to packages only. `install` is accepted as an alias for this command.

### Arguments

#### `[PACKAGE]…`

Packages in `manager:package` form; defaults to everything configured
in [bootstrap.packages]

### Flags

#### `-m --manager <MANAGER>`

Only install packages for this built-in or plugin manager

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

#### `--update`

Refresh package manager metadata first (apk: `--update-cache`, apt: `apt-get update`)

Examples:

    $ mise bootstrap packages apply
    $ mise bootstrap packages apply apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox flatpak-user:org.gnome.Builder mas:497799835
    $ mise bootstrap packages apply --dry-run
    $ mise bootstrap packages apply --manager apt --yes

## `mise bootstrap packages brew`

- **Usage**: `mise bootstrap packages brew <SUBCOMMAND>`
- **Effect**: read-only

Manage Homebrew taps used by bootstrap packages

These commands edit `[bootstrap.brew.taps]` so tapped formulae and casks can be fetched directly by mise without a Homebrew installation.

## `mise bootstrap packages brew tap`

- **Usage**: `mise bootstrap packages brew tap [FLAGS] <TAP> [URL]`
- **Effect**: modifies state

Add a Homebrew tap URL to [bootstrap.brew.taps]

### Arguments

#### `<TAP>`

Tap name, e.g. `owner/repo`

#### `[URL]`

GitHub URL for the tap. Defaults to https://github.com/<owner>/homebrew-<repo>.git

### Flags

#### `-l --local`

Write to the local config instead of the global config

#### `-n --dry-run`

Print the config change without writing it

#### `-p --path <PATH>`

**Aliases:** `--file`

Write to this config file or directory

Examples:

    $ mise bootstrap packages brew tap railwaycat/emacsmacport
    $ mise bootstrap packages brew tap acme/tools https://github.com/acme/homebrew-tools.git

## `mise bootstrap packages brew untap`

- **Usage**: `mise bootstrap packages brew untap [FLAGS] <TAPS>…`
- **Aliases**: `remove`, `rm`
- **Effect**: modifies state

Remove Homebrew tap URLs from [bootstrap.brew.taps]

### Arguments

#### `<TAPS>…`

Tap name(s), e.g. `owner/repo`

### Flags

#### `-l --local`

Write to the local config instead of the global config

#### `-n --dry-run`

Print the config change without writing it

#### `-p --path <PATH>`

**Aliases:** `--file`

Write to this config file or directory

Examples:

    $ mise bootstrap packages brew untap railwaycat/emacsmacport

## `mise bootstrap packages import`

- **Usage**: `mise bootstrap packages import [FLAGS]`
- **Effect**: modifies state

Import installed system packages into `[bootstrap.packages]`

Currently supports Homebrew formulae only. By default, imports linked formulae whose active keg receipt says they were installed on request. Pass `--all` to import every linked formula, including dependencies.

### Flags

#### `-e --env <ENV>`

Write to the config file for this environment (mise.<ENV>.toml)

#### `-g --global`

Write to the global config (~/.config/mise/config.toml)

#### `-m --manager <MANAGER>`

Only import packages for this manager. Currently only `brew` is supported.

**Choices:**

- `brew`

**Default:** `brew`

#### `--all`

Import every linked formula, including dependencies

#### `-n --dry-run`

Print the config change without writing config

#### `-p --path <PATH>`

**Aliases:** `--file`

Write to this config file or directory

Examples:

    $ mise bootstrap packages import --manager brew
    $ mise bootstrap packages import --manager brew --all
    $ mise bootstrap packages import --manager brew --global
    $ mise bootstrap packages import --manager brew --dry-run

## `mise bootstrap packages prune`

- **Usage**: `mise bootstrap packages prune [FLAGS]`
- **Effect**: destructive — may delete or irreversibly overwrite

Prune installed system packages no longer declared in `[bootstrap.packages]`

Supports Homebrew formulae and conservatively removable, mise-owned casks. Pruning keeps packages needed by the current config or by trusted, loadable tracked configs.

### Flags

#### `-m --manager <MANAGER>`

Only prune packages for this manager

**Choices:**

- `brew`
- `brew-cask`

**Default:** `brew`

#### `-n --dry-run`

Print what would be removed without deleting anything

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap packages prune --manager brew
    $ mise bootstrap packages prune --manager brew --dry-run
    $ mise bootstrap packages prune --manager brew --yes
    $ mise bootstrap packages prune --manager brew-cask --dry-run

## `mise bootstrap packages status`

- **Usage**: `mise bootstrap packages status [-J --json] [--missing]`
- **Aliases**: `ls`
- **Effect**: read-only

Show the status of system packages from `[bootstrap.packages]`

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured packages are not in their desired state

Examples:

    $ mise bootstrap packages status
    $ mise bootstrap packages status --json
    $ mise bootstrap packages status --missing # exit 1 if anything is out of sync

## `mise bootstrap packages upgrade`

- **Usage**: `mise bootstrap packages upgrade [FLAGS] [PACKAGE]…`
- **Aliases**: `up`
- **Effect**: modifies state

Upgrade installed bootstrap packages from `[bootstrap.packages]`

Refreshes package manager metadata and upgrades the configured packages that are already installed: apk/apt/dnf/pacman upgrade to the newest available version (apk, apt, and dnf honor a version pinned in config), brew pours the formula's current bottle and replaces the old keg, brew-cask installs the current cask artifact, flatpak and flatpak-user update applications and runtimes, and mas upgrades App Store apps. Packages that are not installed yet are skipped — use `mise bootstrap packages apply` for those.

Packages can also be given explicitly in `manager:package` form.

### Arguments

#### `[PACKAGE]…`

Packages in `manager:package` form; defaults to everything configured
in [bootstrap.packages]

### Flags

#### `-m --manager <MANAGER>`

Only upgrade packages for this built-in or plugin manager

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap packages upgrade
    $ mise bootstrap packages upgrade brew:postgresql@17
    $ mise bootstrap packages upgrade --manager brew-cask
    $ mise bootstrap packages upgrade --manager mas
    $ mise bootstrap packages upgrade --manager apt --yes
    $ mise bootstrap packages upgrade --dry-run

## `mise bootstrap packages use`

- **Usage**: `mise bootstrap packages use [FLAGS] <PACKAGE>…`
- **Aliases**: `u`
- **Effect**: modifies state

Add bootstrap packages to [bootstrap.packages] and install them

Like `mise use` for tools: writes `"manager:package" = "version"` entries to mise.toml (the local config by default, the global one with `-g`) and then installs whatever is missing.

Versions are pinned with `@`: `mise bootstrap packages use apt:curl@8.5.0-2`. Without `@` (or with `@latest`) no pin is written. brew formulae and casks version through their names instead (for example `brew:postgresql@17`, `brew-cask:temurin@17`), where `@` is part of the Homebrew name rather than a mise version selector. mas uses numeric ADAM IDs and does not support pins.

### Arguments

#### `<PACKAGE>…`

Packages in `manager:package[@version]` form

### Flags

#### `-e --env <ENV>`

Write to the config file for this environment (mise.<ENV>.toml)

#### `-g --global`

Write to the global config (~/.config/mise/config.toml) instead of the
local one

#### `-n --dry-run`

Print the commands that would run without writing config or installing

#### `-p --path <PATH>`

**Aliases:** `--file`

Write to this config file or directory

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap packages use apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox flatpak-user:org.gnome.Builder mas:497799835
    $ mise bootstrap packages use -g brew:postgresql@17
    $ mise bootstrap packages use apt:curl@8.5.0-2

## `mise bootstrap plan`

- **Usage**: `mise bootstrap plan [FLAGS]`
- **Effect**: read-only

Show the changes declarative bootstrap resources would make

### Flags

#### `-J --json`

Output a stable machine-readable plan in JSON format

#### `--detailed-exitcode`

Exit 2 when the plan contains changes, 0 when unchanged, and 1 on errors

#### `--prompt-secrets`

Prompt securely for missing bootstrap secret inputs

## `mise bootstrap plugins`

- **Usage**: `mise bootstrap plugins <SUBCOMMAND>`
- **Effect**: read-only

Manage package manager plugins declared in `[bootstrap.plugins]`

## `mise bootstrap plugins apply`

- **Usage**: `mise bootstrap plugins apply [-n --dry-run]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print what would happen without installing plugins

## `mise bootstrap plugins status`

- **Usage**: `mise bootstrap plugins status [--missing]`
- **Effect**: read-only

### Flags

#### `--missing`

Exit with code 1 if a declared plugin is missing

## `mise bootstrap remote`

- **Usage**: `mise bootstrap remote [FLAGS] [TARGET]…`
- **Effect**: destructive — may delete or irreversibly overwrite

Bootstrap one or more machines over OpenSSH

### Arguments

#### `[TARGET]…`

Inventory host names from `[bootstrap.remote.hosts]`

### Flags

#### `--all`

Select every configured inventory host

#### `--bootstrap-command <COMMAND>`

Explicit remote shell command that installs mise and places it on PATH

#### `--connect-timeout <CONNECT_TIMEOUT>`

SSH connection timeout in seconds

**Default:** `10`

#### `--copy-link… <PATH>`

Dereference one source-relative symbolic link; repeat for multiple links

#### `--copy-links`

Dereference every symbolic link in the source archive

#### `--exclude… <PATTERN>`

Additional archive pattern to exclude; repeat for multiple patterns

#### `--fail-fast`

Stop after the first failed target

#### `--force-dotfiles`

Allow remote dotfile conflicts to be replaced

#### `--host… <[USER@]HOST>`

Ad-hoc SSH destination (`[user@]host`); repeat for multiple hosts

#### `-i --identity-file <IDENTITY_FILE>`

SSH identity file override

#### `-n --dry-run`

Print the remote bootstrap changes without applying them

#### `--keep-staging`

Keep the remote staging directory for debugging

#### `--mise-bin <MISE_BIN>`

Local mise binary to upload (escape hatch for custom architectures)

#### `--only… <ONLY>`

Run only one or more remote bootstrap parts

**Choices:**

- `plugins`
- `packages`
- `accounts`
- `files`
- `services`
- `firewall`
- `compose`
- `repos`
- `dotfiles`
- `mise-shell-activate`
- `macos-defaults`
- `macos-launchd-agents`
- `linux-systemd-units`
- `user`
- `tools`
- `task`
- `final-hook`

#### `--port <PORT>`

SSH port override

#### `--prompt-secrets`

Prompt securely for missing secret inputs on the remote host

#### `--remote-env… <ENV>`

Config environments to load on the remote host; repeat or delimit with commas (for example, ci,dotfiles)

#### `--remote-mise <COMMAND>`

Existing mise executable name or path; relative paths use the staged project

#### `--skip… <SKIP>`

Skip one or more remote bootstrap parts

**Choices:**

- `plugins`
- `packages`
- `accounts`
- `files`
- `services`
- `firewall`
- `compose`
- `repos`
- `dotfiles`
- `mise-shell-activate`
- `macos-defaults`
- `macos-launchd-agents`
- `linux-systemd-units`
- `user`
- `tools`
- `task`
- `final-hook`

#### `--source <SOURCE>`

Local directory archived and sent to each target

#### `--ssh-option… <OPTION>`

OpenSSH `-o` option; repeat for multiple options

#### `--tag… <TAG>`

Select configured hosts with this tag; repeat to match any tag

#### `--update`

Refresh package manager metadata and update configured repos remotely

#### `-y --yes`

Skip remote confirmation prompts

## `mise bootstrap repos`

- **Usage**: `mise bootstrap repos <SUBCOMMAND>`
- **Effect**: read-only

Manage git repo checkouts from `[bootstrap.repos]`

## `mise bootstrap repos apply`

- **Usage**: `mise bootstrap repos apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap repos exec`

- **Usage**: `mise bootstrap repos exec [-c --continue-on-error] [-n --dry-run] [PATH]… <-- COMMAND>…`

### Arguments

#### `[PATH]…`

Run only in matching configured or expanded paths

#### `<-- COMMAND>…`

Command and arguments to run in each repo

### Flags

#### `-c --continue-on-error`

Continue running in other repos after a command fails

#### `-n --dry-run`

Print the commands that would run without running them

## `mise bootstrap repos status`

- **Usage**: `mise bootstrap repos status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured repo is not in its desired state

## `mise bootstrap repos update`

- **Usage**: `mise bootstrap repos update [-n --dry-run] [-y --yes] [PATH]…`
- **Effect**: modifies state

### Arguments

#### `[PATH]…`

Update only matching configured or expanded paths

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap secrets`

- **Usage**: `mise bootstrap secrets <SUBCOMMAND>`
- **Effect**: read-only

Inspect bootstrap secret inputs without revealing their values

## `mise bootstrap secrets status`

- **Usage**: `mise bootstrap secrets status [-J --json] [--missing]`
- **Effect**: read-only

Show whether declared bootstrap secret inputs are available

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if a declared secret input is unavailable

## `mise bootstrap services`

- **Usage**: `mise bootstrap services <SUBCOMMAND>`
- **Effect**: read-only

Manage Linux system services from `[bootstrap.services]`

## `mise bootstrap services apply`

- **Usage**: `mise bootstrap services apply [-n --dry-run] [-y --yes]`
- **Effect**: destructive — may delete or irreversibly overwrite

Apply configured Linux system service state

### Flags

#### `-n --dry-run`

Print what would change without changing anything

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap services status`

- **Usage**: `mise bootstrap services status [-J --json] [--missing]`
- **Effect**: read-only

Show configured Linux system service state

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 when any service is not converged

## `mise bootstrap status`

- **Usage**: `mise bootstrap status [FLAGS]`
- **Aliases**: `ls`
- **Effect**: read-only

Show the aggregate bootstrap status

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured bootstrap state is not in its desired state

#### `--prompt-secrets`

Prompt securely for missing bootstrap secret inputs

## `mise bootstrap systemd`

- **Usage**: `mise bootstrap systemd <SUBCOMMAND>`
- **Effect**: read-only

Manage systemd user services from `[bootstrap.linux.systemd.units]`

## `mise bootstrap systemd apply`

- **Usage**: `mise bootstrap systemd apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap systemd status`

- **Usage**: `mise bootstrap systemd status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured systemd user service is not in its desired state

## `mise bootstrap user`

- **Usage**: `mise bootstrap user <SUBCOMMAND>`
- **Effect**: read-only

Manage current-user bootstrap settings from `[bootstrap.user]`

## `mise bootstrap user apply`

- **Usage**: `mise bootstrap user apply [-n --dry-run] [-y --yes]`
- **Effect**: modifies state

### Flags

#### `-n --dry-run`

Print the commands that would run without running them

#### `-y --yes`

Skip the confirmation prompt

## `mise bootstrap user status`

- **Usage**: `mise bootstrap user status [-J --json] [--missing]`
- **Effect**: read-only

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured user setting is not in its desired state

## `mise cache`

- **Usage**: `mise cache <SUBCOMMAND>`
- **Effect**: read-only

Manage the mise cache

Run `mise cache` with no args to view the current cache directory.

## `mise cache clear`

- **Usage**: `mise cache clear [--task <TASK>] [TOOL]…`
- **Aliases**: `c`
- **Effect**: modifies state

Deletes all cache files in mise

### Arguments

#### `[TOOL]…`

Tool(s) to clear cache for
e.g.: node, python

### Flags

#### `--task <TASK>`

Clear output cache entries for a task name or pattern

## `mise cache path`

- **Usage**: `mise cache path`
- **Aliases**: `dir`
- **Effect**: read-only

Show the cache directory path

## `mise cache prune`

- **Usage**: `mise cache prune [-v --verbose…] [--dry-run] [TOOL]…`
- **Aliases**: `p`
- **Effect**: modifies state

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.

### Arguments

#### `[TOOL]…`

Tool(s) to prune cache for
e.g.: node, python

### Flags

#### `-v --verbose…`

Show pruned files

#### `--dry-run`

Just show what would be pruned

## `mise cache task`

- **Usage**: `mise cache task [-J --json] <TASK>`
- **Effect**: read-only

Inspect output cache entries for a task

### Arguments

#### `<TASK>`

Task name or pattern to inspect

### Flags

#### `-J --json`

Output in JSON format

## `mise completion`

- **Usage**: `mise completion [--include-bash-completion-lib] [SHELL]`
- **Effect**: read-only

Generate shell completions

### Arguments

#### `[SHELL]`

Shell type to generate completions for

### Flags

#### `--include-bash-completion-lib`

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.

Examples:

    $ mise completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/mise
    $ mise completion zsh  > /usr/local/share/zsh/site-functions/_mise
    $ mise completion fish > ~/.config/fish/completions/mise.fish
    $ mise completion powershell >> $PROFILE

## `mise config`

- **Usage**: `mise config [FLAGS] <SUBCOMMAND>`
- **Aliases**: `cfg`
- **Effect**: read-only

Manage config files

### Flags

#### `-J --json`

Output in JSON format

#### `--no-header`

Do not print table header

#### `--tracked-configs`

List all tracked config files

## `mise config get`

- **Usage**: `mise config get [-f --file <FILE>] [KEY]`
- **Effect**: read-only

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

### Arguments

#### `[KEY]`

The path of the config to display

### Flags

#### `-f --file <FILE>`

**Aliases:** `--path`

The path to the mise.toml file to read

Can be a file path or directory. If a directory is provided, the config file in that directory is used.

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

Examples:

    $ mise toml get tools.python
    3.12

## `mise config ls`

- **Usage**: `mise config ls [FLAGS]`
- **Aliases**: `list`
- **Effect**: read-only

List config files currently in use

### Flags

#### `-J --json`

Output in JSON format

#### `--no-header`

Do not print table header

#### `--tracked-configs`

List all tracked config files

Examples:

    $ mise config ls
    Path                        Tools
    ~/.config/mise/config.toml  pitchfork
    ~/src/mise/mise.toml        actionlint, bun, cargo-binstall, cargo:cargo-insta

## `mise config set`

- **Usage**: `mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> [VALUE]`
- **Effect**: modifies state

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

### Arguments

#### `<KEY>`

The path of the config to display

#### `[VALUE]`

The value to set the key to (optional if provided as KEY=VALUE)

### Flags

#### `-f --file <FILE>`

**Aliases:** `--path`

The path to the mise.toml file to edit

Can be a file path or directory. If a directory is provided, the config file in that directory is used.

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

#### `-t --type <TYPE>`

**Choices:**

- `infer`
- `string`
- `integer`
- `float`
- `bool`
- `list`
- `set`

**Default:** `infer`

Examples:

    $ mise config set tools.python 3.12
    $ mise config set settings.always_keep_download true
    $ mise config set env.TEST_ENV_VAR ABC
    $ mise config set settings.disable_tools node,rust

    # Type for `settings` is inferred
    $ mise config set settings.jobs 4

## `mise current`

- **Usage**: `mise current [PLUGIN]`
- **Effect**: read-only

Shows current active and installed runtime versions

This is similar to `mise ls --current`, but this only shows the runtime and/or version. It's designed to fit into scripts more easily.

### Arguments

#### `[PLUGIN]`

Plugin to show versions of
e.g.: ruby, node, cargo:eza, npm:prettier, etc.

Examples:

    # outputs `.tool-versions` compatible format
    $ mise current
    python 3.11.0 3.10.0
    shfmt 3.6.0
    shellcheck 0.9.0
    node 20.0.0

    $ mise current node
    20.0.0

    # can output multiple versions
    $ mise current python
    3.11.0 3.10.0

## `mise deactivate`

- **Usage**: `mise deactivate`
- **Effect**: read-only

Disable mise for current shell session

This can be used to temporarily disable mise in a shell session.

Examples:

    $ mise deactivate

## `mise direnv`

- **Usage**: `mise direnv <SUBCOMMAND>`
- **Effect**: read-only

Output direnv function to use mise inside direnv

See https://mise.jdx.dev/direnv.html for more information

Because this generates the idiomatic files based on currently installed plugins, you should run this command after installing new plugins. Otherwise direnv may not know to update environment variables when idiomatic file versions change.

## `mise direnv activate`

- **Usage**: `mise direnv activate`
- **Effect**: read-only

Output direnv function to use mise inside direnv

See https://mise.jdx.dev/direnv.html for more information

Because this generates the idiomatic files based on currently installed plugins, you should run this command after installing new plugins. Otherwise direnv may not know to update environment variables when idiomatic file versions change.

Examples:

    $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh
    $ echo 'use mise' > .envrc
    $ direnv allow

## `mise direnv envrc`

- **Usage**: `mise direnv envrc`
- **Effect**: modifies state

[internal] This is an internal command that writes an envrc file
for direnv to consume.

## `mise direnv exec`

- **Usage**: `mise direnv exec`

[internal] This is an internal command that writes an envrc file
for direnv to consume.

## `mise dotfiles`

- **Usage**: `mise dotfiles <SUBCOMMAND>`
- **Effect**: read-only

Manage dotfiles from `[dotfiles]` (deprecated)

Use `mise bootstrap dotfiles` instead.

## `mise dotfiles add`

- **Usage**: `mise dotfiles add [FLAGS] <TARGET>…`
- **Effect**: modifies state

Add or update dotfiles in `[dotfiles]`

If the target is already managed, this updates its source from the live target. Otherwise it creates a `[dotfiles]` entry and seeds the source under `dotfiles.root` unless `--source` is provided.

### Arguments

#### `<TARGET>…`

Targets to add or update

### Flags

#### `-f --force`

Overwrite existing sources without prompting

#### `-g --global`

Write to the global config

#### `-l --local`

Write to the local config instead of the global config

#### `-m --mode <MODE>`

Dotfile mode to write

#### `-n --dry-run`

Print the config/source updates without writing anything

#### `--no-apply`

Add the entry without applying it

#### `-p --path <PATH>`

Write to this config file or directory

#### `-s --source <PATH>`

Source path to use for a single target

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles add ~/.zshrc
    $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml
    $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig

## `mise dotfiles apply`

- **Usage**: `mise dotfiles apply [FLAGS] [TARGET]…`
- **Effect**: modifies state

Apply dotfiles from `[dotfiles]`

Applies configured whole-file entries and edits that aren't in their desired state. Whole-file entries may symlink, copy, or render templates. Edit entries manage a marker-delimited block or a single line in a file mise doesn't otherwise own.

### Arguments

#### `[TARGET]…`

Only apply these targets

### Flags

#### `-f --force`

Overwrite existing files that conflict with whole-file dotfile entries

#### `-n --dry-run`

Print the actions that would run without writing anything

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles apply
    $ mise bootstrap dotfiles apply --dry-run
    $ mise bootstrap dotfiles apply --force --yes

## `mise dotfiles edit`

- **Usage**: `mise dotfiles edit [FLAGS] <TARGET>`
- **Effect**: modifies state

Edit a managed dotfile source

### Arguments

#### `<TARGET>`

Target to edit

### Flags

#### `--apply`

Apply this target after the editor exits

#### `-m --mode <MODE>`

Dotfile mode to use if the target is not yet managed

#### `-s --source <PATH>`

Source path to use if the target is not yet managed

#### `-y --yes`

Skip the confirmation prompt when adding an unmanaged target

Examples:

    $ mise bootstrap dotfiles edit ~/.zshrc
    $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml

## `mise dotfiles status`

- **Usage**: `mise dotfiles status [-J --json] [--missing] [TARGET]…`
- **Aliases**: `ls`
- **Effect**: read-only

Show the status of dotfiles from `[dotfiles]`

### Arguments

#### `[TARGET]…`

Only show these targets

### Flags

#### `-J --json`

Output in JSON format

#### `--missing`

Exit with code 1 if any configured dotfiles are not in their desired
state (missing, source missing, differs)

Examples:

    $ mise bootstrap dotfiles status
    $ mise bootstrap dotfiles status ~/.zshrc
    $ mise bootstrap dotfiles status --json
    $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync

## `mise dotfiles unapply`

- **Usage**: `mise dotfiles unapply [FLAGS] [TARGET]…`
- **Effect**: destructive — may delete or irreversibly overwrite

Remove dotfiles applied from `[dotfiles]`

Removes configured whole-file entries and edits while preserving files mise cannot identify as managed. Modified copies, templates, and plain-line edits require `--force`.

### Arguments

#### `[TARGET]…`

Only unapply these targets

### Flags

#### `-f --force`

Remove modified or otherwise ambiguous managed files and lines

#### `-n --dry-run`

Print the actions that would run without writing anything

#### `-y --yes`

Skip the confirmation prompt

Examples:

    $ mise bootstrap dotfiles unapply
    $ mise bootstrap dotfiles unapply ~/.zshrc
    $ mise bootstrap dotfiles unapply --dry-run
    $ mise bootstrap dotfiles unapply --force --yes

## `mise doctor`

- **Usage**: `mise doctor [-J --json] <SUBCOMMAND>`
- **Aliases**: `dr`
- **Effect**: read-only

Check mise installation for possible problems

### Flags

#### `-J --json`

Examples:

    $ mise doctor
    [WARN] plugin node is not installed

## `mise doctor path`

- **Usage**: `mise doctor path [-f --full]`
- **Effect**: read-only

Print the current PATH entries mise is providing

### Flags

#### `-f --full`

Print all entries including those not provided by mise

Examples:

    Get the current PATH entries mise is providing
    $ mise doctor path
    /home/user/.local/share/mise/installs/node/24.0.0/bin
    /home/user/.local/share/mise/installs/rust/1.90.0/bin
    /home/user/.local/share/mise/installs/python/3.10.0/bin

## `mise en`

- **Usage**: `mise en [-s --shell <SHELL>] [DIR]`

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.

### Arguments

#### `[DIR]`

Directory to start the shell in

**Default:** `.`

### Flags

#### `-s --shell <SHELL>`

Shell to start

Defaults to $SHELL

Examples:

    $ mise en .
    $ node -v
    v20.0.0

    Skip loading bashrc:
    $ mise en -s "bash --norc"

    Skip loading zshrc:
    $ mise en -s "zsh -f"

## `mise env`

- **Usage**: `mise env [FLAGS] [TOOL@VERSION]…`
- **Aliases**: `e`
- **Effect**: read-only

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.

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to use

### Flags

#### `-D --dotenv`

Output in dotenv format

#### `-J --json`

Output in JSON format

#### `-s --shell <SHELL>`

Shell type to generate environment variables for

#### `--json-extended`

Output in JSON format with additional information (source, tool)

#### `--redacted`

Only show redacted environment variables

#### `--values`

Only show values of environment variables

Examples:

    $ eval "$(mise env -s bash)"
    $ eval "$(mise env -s zsh)"
    $ mise env -s fish | source
    $ execx($(mise env -s xonsh))

## `mise exec`

- **Usage**: `mise exec [FLAGS] [TOOL@VERSION]… [-- COMMAND]…`
- **Aliases**: `x`

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.

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to start
e.g.: node@20 python@3.10

#### `[-- COMMAND]…`

Command string to execute (same as --command)

### Flags

#### `-c --command <COMMAND>`

Command string to execute

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_JOBS`

#### `--allow-env… <VAR>`

Allow specific env var through (implies --deny-env for everything else)
Supports wildcards, e.g. --allow-env='MYAPP_*'

#### `--allow-net… <HOST>`

Allow network to specific host (implies --deny-net for everything else)
macOS only in v1; on Linux falls back to allowing all network

#### `--allow-read… <PATH>`

Allow reads from specific path (implies --deny-read for everything else)

#### `--allow-write… <PATH>`

Allow writes to specific path (implies --deny-write for everything else)

#### `--deny-all`

Block reads, writes, network, and env vars

#### `--deny-env`

Block env var inheritance (only PATH, HOME, USER, SHELL, TERM, LANG pass through)

#### `--deny-net`

Block all network access

#### `--deny-read`

Block filesystem reads (system libs and tool dirs still accessible)

#### `--deny-write`

Block all filesystem writes

#### `--fresh-env`

Bypass the environment cache and recompute the environment

#### `--no-deps`

Skip automatic dependency preparation

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies --jobs=1

Examples:

    $ mise exec node@20 -- node ./app.js  # launch app.js using node-20.x
    $ mise x node@20 -- node ./app.js     # shorter alias

    # Specify command as a string:
    $ mise exec node@20 python@3.11 --command "node -v && python -V"

    # Run a command in a different directory:
    $ mise x -C /path/to/project node@20 -- node ./app.js

## `mise fmt`

- **Usage**: `mise fmt [FLAGS]`
- **Effect**: modifies state

Formats mise.toml

Sorts keys and cleans up whitespace in mise.toml

### Flags

#### `-a --all`

Format all files from the current directory

#### `-c --check`

Check if the configs are formatted, no formatting is done

#### `-s --stdin`

Read config from stdin and write its formatted version into
stdout

Examples:

    $ mise fmt

## `mise generate`

- **Usage**: `mise generate <SUBCOMMAND>`
- **Aliases**: `gen`
- **Effect**: read-only

Generate files for various tools/services

## `mise generate bootstrap`

- **Usage**: `mise generate bootstrap [FLAGS]`
- **Effect**: modifies state

Generate a script to download+execute mise

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

### Flags

#### `-l --localize`

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.

#### `-V --version <VERSION>`

Specify mise version to fetch

#### `-w --write [WRITE]`

instead of outputting the script to stdout, write to a file and make it executable

#### `--localized-dir <LOCALIZED_DIR>`

Directory to put localized data into

**Default:** `.mise`

#### `--windows`

Also write a Windows launcher, `<WRITE>.cmd`

Windows cannot execute the `#!/usr/bin/env bash` script, so a contributor who clones the project on Windows has nothing to run without this.

Generated on every host, not only on Windows: the file is committed, and whoever runs it on Windows is not the person who generated it. Requires `--write`, since stdout cannot carry two files.

Examples:

    $ mise generate bootstrap --write ./bin/mise
    $ ./bin/mise install                                    # downloads mise to .mise if not already installed

    # add a launcher for contributors who clone the project on Windows
    $ mise generate bootstrap --write ./bin/mise --windows  # also writes bin/mise.cmd
    $ .\bin\mise.cmd install

## `mise generate config`

- **Usage**: `mise generate config [FLAGS] [PATH]`
- **Effect**: modifies state

Generate a mise.toml file

### Arguments

#### `[PATH]`

Path to the config file to create

### Flags

#### `-g --global`

Generate the global config file (~/.config/mise/config.toml)

#### `-n --dry-run`

Show what would be generated without writing to file

#### `-t --tool-versions <TOOL_VERSIONS>`

Path to a .tool-versions file to import tools from

Examples:

    $ mise generate config             # generate mise.toml interactively
    $ mise generate config .mise.toml  # generate a specific file
    $ mise generate config -g          # generate the global config file
    $ mise generate config -y          # skip interactive editor
    $ mise generate config -n          # preview without writing

## `mise generate devcontainer`

- **Usage**: `mise generate devcontainer [FLAGS]`
- **Effect**: modifies state

Generate a devcontainer to execute mise

### Flags

#### `-i --image <IMAGE>`

The image to use for the devcontainer

#### `-m --mount-mise-data`

Bind the mise-data-volume to the devcontainer

#### `-n --name <NAME>`

The name of the devcontainer

#### `-w --write`

write to .devcontainer/devcontainer.json

Examples:

    $ mise generate devcontainer

## `mise generate git-pre-commit`

- **Usage**: `mise generate git-pre-commit [FLAGS] [-- MISE_ARG]…`
- **Aliases**: `pre-commit`
- **Effect**: modifies state

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/

### Arguments

#### `[-- MISE_ARG]…`

mise flags to embed in the generated hook, given after `--`

These are inserted between `mise` and `run`, so the hook carries the same context you would pass on the command line. Useful when the config is not at the repository root, since git runs hooks from the top level: `-- -C subdir` makes the hook find it.

### Flags

#### `-t --task <TASK>`

The task to run when the pre-commit hook is triggered

**Default:** `pre-commit`

#### `-w --write`

write to .git/hooks/pre-commit and make it executable

#### `--hook <HOOK>`

Which hook to generate (saves to .git/hooks/$hook)

**Default:** `pre-commit`

Examples:

    $ mise generate git-pre-commit --write --task=pre-commit
    $ git commit -m "feat: add new feature" # runs `mise run pre-commit`

    # config lives in a subdirectory, so the hook has to change into it first
    $ mise generate git-pre-commit --write -- -C subdir

## `mise generate github-action`

- **Usage**: `mise generate github-action [FLAGS]`
- **Effect**: modifies state

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.

### Flags

#### `-t --task <TASK>`

The task to run when the workflow is triggered

**Default:** `ci`

#### `-w --write`

write to .github/workflows/$name.yml

#### `--name <NAME>`

the name of the workflow to generate

**Default:** `ci`

Examples:

    $ mise generate github-action --write --task=ci
    $ git commit -m "feat: add new feature"
    $ git push # runs `mise run ci` on GitHub

## `mise generate task-docs`

- **Usage**: `mise generate task-docs [FLAGS]`
- **Effect**: modifies state

Generate documentation for tasks in a project

### Flags

#### `-i --inject`

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. The file must already contain both comments; mise errors instead of modifying the file if they are missing.

#### `-I --index`

write only an index of tasks, intended for use with `--multi`

#### `-m --multi`

render each task as a separate document, requires `--output` to be a directory

#### `-o --output <OUTPUT>`

writes the generated docs to a file/directory

#### `-r --root <ROOT>`

root directory to search for tasks

#### `-s --style <STYLE>`

**Choices:**

- `simple`
- `detailed`

**Default:** `simple`

Examples:

    $ mise generate task-docs

## `mise generate task-stubs`

- **Usage**: `mise generate task-stubs [-d --dir <DIR>] [-m --mise-bin <MISE_BIN>]`
- **Effect**: modifies state

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. When a parent and nested task both exist, the parent stub is written to `<parent>/_default`.

### Flags

#### `-d --dir <DIR>`

Directory to create task stubs inside of

**Default:** `bin`

#### `-m --mise-bin <MISE_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`

Examples:

    $ mise tasks add test -- echo 'running tests'
    $ mise generate task-stubs
    $ ./bin/test
    running tests

## `mise generate tool-stub`

- **Usage**: `mise generate tool-stub [FLAGS] <OUTPUT>`
- **Effect**: modifies state

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.

### Arguments

#### `<OUTPUT>`

Output file path for the tool stub

### Flags

#### `-b --bin <BIN>`

Binary path within the extracted archive

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

#### `--bootstrap`

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

#### `--bootstrap-version <BOOTSTRAP_VERSION>`

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").

#### `--checksum-algorithm <CHECKSUM_ALGORITHM>`

Checksum algorithm to use when downloading artifacts

Accepts `blake3` or `sha256` and defaults to `blake3`. Cannot be used with `--lock` or `--skip-download` because those modes do not calculate checksums.

**Choices:**

- `blake3`
- `sha256`

**Default:** `blake3`

#### `--fetch`

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 <HTTP>`

HTTP backend type to use

**Default:** `http`

#### `--lock`

Resolve and embed lockfile data (exact version + platform URLs/checksums)
into an existing stub file for reproducible installs without runtime API calls

#### `--platform-bin… <PLATFORM_BIN>`

Platform-specific binary paths in the format platform:path

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

#### `--platform-url… <PLATFORM_URL>`

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-download`

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

#### `-u --url <URL>`

URL for downloading the tool

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

#### `--version <VERSION>`

Version of the tool

**Default:** `latest`

Examples:

    Generate a tool stub for a single URL:
    $ mise generate tool-stub ./bin/gh --url "https://github.com/cli/cli/releases/download/v2.96.0/gh_2.96.0_linux_amd64.tar.gz"

    Generate a tool stub with platform-specific URLs:
    $ mise generate tool-stub ./bin/rg \
        --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \
        --platform-url darwin-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz

    Append additional platforms to an existing stub:
    $ mise generate tool-stub ./bin/rg \
        --platform-url linux-x64:https://example.com/rg-linux.tar.gz
    $ mise generate tool-stub ./bin/rg \
        --platform-url darwin-arm64:https://example.com/rg-darwin.tar.gz
    # The stub now contains both platforms

    Use auto-detection for platform from URL:
    $ mise generate tool-stub ./bin/node \
        --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz
    # Platform 'macos-arm64' will be auto-detected from the URL

    Generate with platform-specific binary paths:
    $ mise generate tool-stub ./bin/tool \
        --platform-url linux-x64:https://example.com/tool-linux.tar.gz \
        --platform-url windows-x64:https://example.com/tool-windows.zip \
        --platform-bin windows-x64:tool.exe

    Generate without downloading (faster):
    $ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --skip-download

    Fetch checksums for an existing stub:
    $ mise generate tool-stub ./bin/jq --fetch
    # This will read the existing stub and download files to fill in any missing checksums/sizes

    Generate a bootstrap stub that installs mise if needed:
    $ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --bootstrap
    # The stub will check for mise and install it automatically before running the tool

    Generate a bootstrap stub with a pinned mise version:
    $ mise generate tool-stub ./bin/tool --url "https://example.com/tool.tar.gz" --bootstrap --bootstrap-version 2025.1.0

    Lock an existing tool stub with pinned version and platform URLs/checksums:
    $ mise generate tool-stub ./bin/node --lock

    Bump the version in a locked stub:
    $ mise generate tool-stub ./bin/node --lock --version 22
    # Resolves the latest node 22.x, pins it, and updates platform URLs/checksums

## `mise github`

- **Usage**: `mise github <SUBCOMMAND>`
- **Effect**: read-only

GitHub related commands

## `mise github token`

- **Usage**: `mise github token [FLAGS] [HOST]`
- **Effect**: read-only

Display the GitHub token mise will use for a given host

Shows which token source mise would use, useful for debugging authentication issues. The token is masked by default.

### Arguments

#### `[HOST]`

GitHub hostname

**Default:** `github.com`

### Flags

#### `--oauth`

Force native GitHub OAuth device flow instead of normal token resolution

#### `--raw`

Print only the token value

#### `--refresh`

Mint a fresh OAuth token even if the cached one has not
expired, via the refresh-token grant or a new device-code flow

#### `--unmask`

Show the full unmasked token

Examples:

    $ mise github token
    github.com: ghp_…xxxx (source: GITHUB_TOKEN)

    $ mise github token --unmask
    github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)

    $ mise github token github.mycompany.com
    github.mycompany.com: (none)

## `mise global`

- **Usage**: `mise global [FLAGS] [TOOL@VERSION]…`
- **Effect**: modifies state

Sets/gets the global tool version(s)

Displays the contents of global config after writing. The file is `$HOME/.config/mise/config.toml` by default. It can be changed with `$MISE_GLOBAL_CONFIG_FILE`. If `$MISE_GLOBAL_CONFIG_FILE` is set to anything that ends in `.toml`, it will be parsed as `mise.toml`. Otherwise, it will be parsed as a `.tool-versions` file.

Use MISE_ASDF_COMPAT=1 to default the global config to ~/.tool-versions

Use `mise local` to set a tool version locally in the current directory.

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to add to .tool-versions
e.g.: node@20
If this is a single tool with no version, the current value of the global
.tool-versions will be displayed

### Flags

#### `--fuzzy`

Save fuzzy version to `~/.tool-versions`
e.g.: `mise global --fuzzy node@20` will save `node 20` to ~/.tool-versions
this is the default behavior unless MISE_ASDF_COMPAT=1

#### `--path`

Get the path of the global config file

#### `--pin`

Save exact version to `~/.tool-versions`
e.g.: `mise global --pin node@20` will save `node 20.0.0` to ~/.tool-versions

#### `--remove… <TOOL>`

Remove the tool(s) from ~/.tool-versions

Examples:
    # set the current version of node to 20.x
    # will use a fuzzy version (e.g.: 20) in .tool-versions file
    $ mise global --fuzzy node@20

    # set the current version of node to 20.x
    # will use a precise version (e.g.: 20.0.0) in .tool-versions file
    $ mise global --pin node@20

    # show the current version of node in ~/.tool-versions
    $ mise global node
    20.0.0

## `mise hook-env`

- **Usage**: `mise hook-env [FLAGS]`
- **Effect**: read-only

[internal] called by activate hook to update env vars directory change

### Flags

#### `-f --force`

Skip early exit check

#### `-q --quiet`

Hide warnings such as when a tool is not installed

#### `-s --shell <SHELL>`

Shell type to generate script for

## `mise hook-not-found`

- **Usage**: `mise hook-not-found [-s --shell <SHELL>] <BIN>`
- **Effect**: modifies state

[internal] called by shell when a command is not found

### Arguments

#### `<BIN>`

Attempted bin to run

### Flags

#### `-s --shell <SHELL>`

Shell type to generate script for

## `mise implode`

- **Usage**: `mise implode [-n --dry-run] [--config]`
- **Effect**: destructive — may delete or irreversibly overwrite

Removes mise CLI and all related data

Skips config directory by default.

### Flags

#### `-n --dry-run`

List directories that would be removed without actually removing them

#### `--config`

Also remove config directory

## `mise edit`

- **Usage**: `mise edit [FLAGS] [PATH]`
- **Effect**: modifies state

Edit mise.toml interactively

### Arguments

#### `[PATH]`

Path to the config file to create

### Flags

#### `-g --global`

Edit the global config file (~/.config/mise/config.toml)

#### `-n --dry-run`

Show what would be generated without writing to file

#### `-t --tool-versions <TOOL_VERSIONS>`

Path to a .tool-versions file to import tools from

Examples:

    $ mise edit             # edit mise.toml interactively
    $ mise edit .mise.toml  # edit a specific file
    $ mise edit -g          # edit the global config file
    $ mise edit -y          # skip interactive editor
    $ mise edit -n          # preview without writing

## `mise install`

- **Usage**: `mise install [FLAGS] [TOOL@VERSION]…`
- **Aliases**: `i`
- **Effect**: modifies state

Install a tool version

Installs a tool version to `~/.local/share/mise/installs/<TOOL>/<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`

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to install
e.g.: node@20

### Flags

#### `-f --force`

Force reinstall even if already installed
With no tools specified, reinstall all configured tools

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Show what would be installed without actually installing

#### `-v --verbose…`

Show installation output

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

#### `--dry-run-code`

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.

#### `--include-task-tools`

Also install tools required by tasks in the current scope

This prepares task tools without running task commands or dependencies. Combine with --monorepo to include tasks from every configured root.

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only install versions released before this date or older than this duration

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

#### `--monorepo`

Install tools from every [monorepo].config_roots config root

Uses the active MISE_ENV and requires monorepo_root = true plus explicit [monorepo].config_roots in the monorepo root config.

**Environment Variable:** `MISE_MONOREPO`

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies --jobs=1

#### `--shared <SHARED>`

Install tool(s) to a shared directory

Installs to the specified directory instead of the default install location. May require elevated permissions depending on the path.

#### `--system`

Install tool(s) to the system-wide shared directory

Installs to /usr/local/share/mise/installs (or MISE_SYSTEM_DATA_DIR/installs). May require elevated permissions (e.g. sudo).

Examples:

    $ mise install node@20.0.0  # install specific node version
    $ mise install node@20      # install fuzzy node version
    $ mise install node         # install version specified in mise.toml
    $ mise install              # installs everything specified in mise.toml
    $ mise install --include-task-tools # also install tools required by tasks

## `mise install-into`

- **Usage**: `mise install-into <TOOL@VERSION> <PATH>`
- **Effect**: modifies state

Install a tool version to a specific path

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

### Arguments

#### `<TOOL@VERSION>`

Tool to install
e.g.: node@20

#### `<PATH>`

Path to install the tool into

Examples:

    # install node@20.0.0 into ./mynode
    $ mise install-into node@20.0.0 ./mynode && ./mynode/bin/node -v
    20.0.0

## `mise latest`

- **Usage**: `mise latest [-i --installed] [--minimum-release-age <MINIMUM_RELEASE_AGE>] <TOOL@VERSION>`
- **Effect**: read-only

Gets the latest available version for a plugin

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

### Arguments

#### `<TOOL@VERSION>`

Tool to get the latest version of

### Flags

#### `-i --installed`

Show latest installed instead of available version

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only consider versions released before this date or older than this duration

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y". Overrides per-tool `minimum_release_age` options and the global `minimum_release_age` setting.

Examples:

    $ mise latest node@20  # get the latest version of node 20
    20.0.0

    $ mise latest node     # get the latest stable version of node
    20.0.0

    $ mise latest node --minimum-release-age 2024-01-01  # latest stable node released before 2024-01-01

## `mise link`

- **Usage**: `mise link [-f --force] <TOOL@VERSION> <PATH>`
- **Aliases**: `ln`
- **Effect**: modifies state

Symlinks a tool version into mise

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

### 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

### Flags

#### `-f --force`

Overwrite an existing tool version if it exists

Examples:

    # build node-20.0.0 with node-build and link it into mise
    $ node-build 20.0.0 ~/.nodes/20.0.0
    $ mise link node@20.0.0 ~/.nodes/20.0.0

    # have mise use the node version provided by Homebrew
    $ brew install node
    $ mise link node@brew $(brew --prefix node)
    $ mise use node@brew

## `mise local`

- **Usage**: `mise local [FLAGS] [TOOL@VERSION]…`
- **Effect**: modifies state

Sets/gets tool version in local .tool-versions or mise.toml

Use this to set a tool's version when within a directory Use `mise global` to set a tool version globally This uses `.tool-version` by default unless there is a `mise.toml` file or if `MISE_USE_TOML` is set. A future v2 release of mise will default to using `mise.toml`.

### Arguments

#### `[TOOL@VERSION]…`

Tool(s) to add to .tool-versions/mise.toml
e.g.: node@20
if this is a single tool with no version,
the current value of .tool-versions/mise.toml will be displayed

### Flags

#### `-p --parent`

Recurse up to find a .tool-versions file rather than using the current directory only
by default this command will only set the tool in the current directory ("$PWD/.tool-versions")

#### `--fuzzy`

Save fuzzy version to `.tool-versions`
e.g.: `mise local --fuzzy node@20` will save `node 20` to .tool-versions
This is the default behavior unless MISE_ASDF_COMPAT=1

#### `--path`

Get the path of the config file

#### `--pin`

Save exact version to `.tool-versions`
e.g.: `mise local --pin node@20` will save `node 20.0.0` to .tool-versions

#### `--remove… <TOOL>`

Remove the tool(s) from .tool-versions

Examples:
    # set the current version of node to 20.x for the current directory
    # will use a precise version (e.g.: 20.0.0) in .tool-versions file
    $ mise local node@20

    # set node to 20.x for the current project (recurses up to find .tool-versions)
    $ mise local -p node@20

    # set the current version of node to 20.x for the current directory
    # will use a fuzzy version (e.g.: 20) in .tool-versions file
    $ mise local --fuzzy node@20

    # removes node from .tool-versions
    $ mise local --remove=node

    # show the current version of node in .tool-versions
    $ mise local node
    20.0.0

## `mise lock`

- **Usage**: `mise lock [FLAGS] [TOOL]…`
- **Effect**: modifies state

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, including tools declared by tasks. 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.

### Arguments

#### `[TOOL]…`

Tool(s) to update in lockfile
e.g.: node python
If not specified, all configured and task-specific tools will be updated

### Flags

#### `-g --global`

Target only global config lockfiles (~/.config/mise/mise.lock and system config)
By default, only the active project config root is locked

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Show what would be updated without making changes

#### `-p --platform… <PLATFORM>`

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

#### `--bump`

Re-resolve fuzzy version selectors against the latest available versions

By default, `mise lock` refreshes metadata for the currently locked versions. With this flag, selectors like "latest", "lts", or prefixes like "20" are re-resolved against the latest matching remote versions, so the lockfile advances without installing anything. Config files are never modified: exactly pinned versions resolve to themselves and stay unchanged (use `mise upgrade --bump` to rewrite pins in mise.toml).

#### `--json`

Output version changes as JSON

Prints an array of objects describing lockfile version changes: name, backend, lockfile, old_versions, new_versions. Version lists keep config/lockfile order; they are not sorted. Only version-level changes are reported: checksum/URL refreshes for unchanged versions produce no entries, so plain `mise lock --json` typically prints `[]` while still updating the lockfile. Suppresses the human-readable output. Combine with `--dry-run` to detect available updates without writing the lockfile.

#### `--local`

Update mise.local.lock instead of mise.lock
Use for tools defined in .local.toml configs

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only lock versions released before this age or date

Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y". This only affects fuzzy version matches like "20" or "latest". Explicitly pinned versions like "22.5.0" are not filtered. Existing matching lockfile entries are preserved and are not downgraded solely by this flag.

Examples:

    $ mise lock                       # update lockfile for all common platforms
    $ mise lock node python           # update only node and python
    $ mise lock --platform linux-x64  # update only linux-x64 platform
    $ mise lock --dry-run             # show what would be updated
    $ mise lock --bump                # re-resolve selectors like "latest" or "20" to the latest matching versions
    $ mise lock --bump --dry-run --json   # list available updates as JSON without writing
    $ mise lock --minimum-release-age 2024-01-01   # lock latest/fuzzy versions released before 2024-01-01
    $ mise lock --local               # update mise.local.lock for local configs
    $ mise lock --global              # update only global config lockfiles

## `mise ls`

- **Usage**: `mise ls [FLAGS] [INSTALLED_TOOL]…`
- **Aliases**: `list`
- **Effect**: read-only

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.

### Arguments

#### `[INSTALLED_TOOL]…`

Only show tool versions from [TOOL]

### Flags

#### `-c --current`

Only show tool versions currently specified in a mise.toml

#### `-g --global`

Only show tool versions currently specified in the global mise.toml

#### `-i --installed`

Only show tool versions that are installed
(Hides tools defined in mise.toml but not installed)

#### `-J --json`

Output in JSON format

#### `-l --local`

Only show tool versions currently specified in the local mise.toml

#### `-m --missing`

Display missing tool versions

#### `--all-sources`

Display all tracked config sources for tools

#### `--monorepo`

List tools from every [monorepo].config_roots config root

Uses the active MISE_ENV and requires monorepo_root = true plus explicit [monorepo].config_roots in the monorepo root config.

**Environment Variable:** `MISE_MONOREPO`

#### `--no-header`

Don't display headers

#### `--outdated`

Display whether a version is outdated

#### `--prefix <PREFIX>`

Display versions matching this prefix

#### `--prunable`

List only tools that can be pruned with `mise prune`

Examples:

    $ mise ls
    node    20.0.0 ~/src/myapp/.tool-versions latest
    python  3.11.0 ~/.tool-versions           3.10
    python  3.10.0

    $ mise ls --current
    node    20.0.0 ~/src/myapp/.tool-versions 20
    python  3.11.0 ~/.tool-versions           3.11.0

    $ mise ls --json
    {
      "node": [
        {
          "version": "20.0.0",
          "install_path": "/Users/jdx/.mise/installs/node/20.0.0",
          "source": {
            "type": "mise.toml",
            "path": "/Users/jdx/mise.toml"
          }
        }
      ],
      "python": [...]
    }

    $ mise ls --all-sources
    node    20.0.0  ~/src/myapp/mise.toml  20
                    ~/.config/mise/config.toml  latest

## `mise ls-remote`

- **Usage**: `mise ls-remote [FLAGS] [TOOL@VERSION] [PREFIX]`
- **Effect**: read-only

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.

### 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 "@"

### Flags

#### `--all`

Show all installed plugins and versions

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only show versions released before this age or date

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

#### `-J --json`

Output in JSON format (includes version metadata like created_at timestamps when available)

#### `--no-versions-host`

Disable checking the mise-versions host

#### `--prerelease`

Include pre-release versions in the output for backends that report
upstream prerelease metadata or opt in to regex-based prerelease
detection. Equivalent to setting `MISE_PRERELEASES=1` or the
`prereleases` setting for the duration of this command.

#### `--strict-metadata`

Fail if release metadata fetches fail

Requires --json and --no-versions-host.

This prevents metadata consumers from accepting empty fallback results when a backend's metadata-producing upstream request fails.

Examples:

    $ mise ls-remote node
    18.0.0
    20.0.0

    $ mise ls-remote node@20
    20.0.0
    20.1.0

    $ mise ls-remote node 20
    20.0.0
    20.1.0

    $ mise ls-remote node --minimum-release-age 2024-01-01
    20.0.0

    $ mise ls-remote github:cli/cli --json
    [{"version":"2.62.0","created_at":"2024-11-14T15:40:35Z","prerelease":false},{"version":"2.61.0","created_at":"2024-10-23T19:22:15Z","prerelease":false}]

## `mise mcp`

- **Usage**: `mise mcp`

Run Model Context Protocol (MCP) server

This command starts an MCP server that exposes mise functionality to AI assistants over stdin/stdout using JSON-RPC protocol.

The MCP server provides access to: - Installed and available tools - Task definitions and execution - Environment variables - Configuration information - Task execution via the run_task tool

Resources available: - mise://tools - List all tools (use ?include_inactive=true to include inactive tools) - mise://tasks - List all tasks with their configurations - mise://env - List all environment variables - mise://config - Show configuration files and project root

Tools available: - list_commands - Every mise command, with its declared effect on the world - install_tool - Install a tool with an optional version (not yet implemented) - run_task - Execute a mise task with optional arguments

Note: This is primarily intended for integration with AI assistants like Claude, Cursor, or other tools that support the Model Context Protocol.

Examples:

    # Start the MCP server (typically used by AI assistant tools)
    $ mise mcp

    # Example integration with Claude Desktop (add to claude_desktop_config.json):
    {
      "mcpServers": {
        "mise": {
          "command": "mise",
          "args": ["mcp"],
          "env": {}
        }
      }
    }

    # Interactive testing with JSON-RPC commands:
    $ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | mise mcp

    # Resources you can query:
    - mise://tools - List active tools
    - mise://tools?include_inactive=true - List all installed tools
    - mise://tasks - List all tasks
    - mise://env - List environment variables
    - mise://config - Show configuration info

    # Tools available:
    - list_commands - Every mise command and what running it does
      Example: {"include_hidden": false}
    - install_tool - Install a tool (not yet implemented)
    - run_task - Execute a mise task with optional arguments
      Example: {"task": "build", "args": ["--verbose"]}

## `mise oci`

- **Usage**: `mise oci <SUBCOMMAND>`
- **Effect**: read-only

[experimental] Build OCI container images from a mise.toml

Each tool becomes its own OCI layer, so bumping any single tool version only invalidates one content-addressable blob — unlike a Dockerfile where changing an early `RUN` invalidates every layer above it.

This command is experimental and requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`). Behavior, flags, and output layout may change in future releases.

## `mise oci build`

- **Usage**: `mise oci build [FLAGS]`
- **Effect**: modifies state

[experimental] Build an OCI image from the current mise.toml

Each tool version becomes its own content-addressable OCI layer. Bumping a tool version only invalidates that tool's layer — other tools, the base image, and config are reused unchanged. The output directory conforms to the OCI image-layout spec and can be consumed by `skopeo`, `crane`, or `podman load`.

Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`).

### Flags

#### `--copy… <HOST_PATH:IMAGE_PATH>`

Copy a host file, directory, or symlink into the image (repeatable, HOST:IMAGE)

#### `-o --output <OUTPUT>`

Output directory for the OCI image layout

**Default:** `./mise-oci`

#### `--from <FROM>`

Base image reference (overrides [oci].from and the oci.default_from setting)

#### `--include-global`

Also include tools from the global / system config (default: project-only)

By default `mise oci build` only packages tools declared in the project's mise config (and any parent configs at-or-below the project root, e.g. a monorepo root config). Personal dev tools in `~/.config/mise/config.toml` are excluded so they don't bake into a project image. Pass `--include-global` to revert to the old "merge all loaded configs" behavior.

#### `-t --tag <TAG>`

Tag to record in the image index (the org.opencontainers.image.ref.name annotation)

#### `--mount-point <MOUNT_POINT>`

Where to place tool installs inside the image (default: /mise)

#### `--no-mise`

Do not embed the currently-running mise binary at /usr/local/bin/mise

#### `--owner <UID[:GID]>`

UID[:GID] to assign to every tar entry in generated layers

Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

Examples:

    Build with defaults (debian:bookworm-slim base):
    $ mise oci build

    Build with a specific base image and tag:
    $ mise oci build --from ubuntu:24.04 --tag myorg/dev:latest -o ./img

    Inspect the result with skopeo:
    $ skopeo inspect oci:./mise-oci

    Push to a registry:
    $ mise oci push --image-dir ./mise-oci ghcr.io/me/dev:latest

Notes:

    - The image only contains tools from the project's mise config (and
      any configs at-or-below the project root). Tools from
      `~/.config/mise/config.toml` are not included; pass --include-global
      to package them too.
    - asdf and vfox plugins are not supported in v1; use a different backend
      (core, aqua, ubi, github, cargo, npm, go, pipx, spm, http) for each tool.
    - The host mise binary is embedded at /usr/local/bin/mise by default;
      build on the same OS/arch as your target image (or pass --no-mise).

## `mise oci push`

- **Usage**: `mise oci push [FLAGS] <REF>`
- **Effect**: modifies state

[experimental] Build an OCI image and push it to a registry

Pushes with mise's built-in registry client — no skopeo/crane/docker required. If `--image-dir` is not passed, builds fresh from the current mise.toml first. Only blobs the registry doesn't already have are uploaded, so repeat pushes of mostly-unchanged toolsets are cheap.

Tool layers whose tool, version, mount point, and file owner match the previously pushed image (or `--cache-from`) are reused without being rebuilt — those tools don't even need to be installed locally. Pass `--no-cache` to force a full local rebuild.

Credentials are read from the same places docker and podman use: `$REGISTRY_AUTH_FILE`, `$XDG_RUNTIME_DIR/containers/auth.json`, `~/.config/containers/auth.json`, and `~/.docker/config.json` (including credential helpers) — so `docker login` / `podman login` is all the setup needed.

Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`).

### Arguments

#### `<REF>`

Destination registry reference (e.g. `ghcr.io/me/devenv:latest`)

### Flags

#### `--cache-from <REF>`

Reuse unchanged tool layers from this image instead of the destination ref

Must live in the same repository as the destination. Useful when each push gets a unique tag (e.g. per-commit tags in CI): `--cache-from ghcr.io/me/dev:latest ghcr.io/me/dev:$SHA`.

#### `--from <FROM>`

Base image for the build (ignored with --image-dir)

#### `--image-dir <IMAGE_DIR>`

Push an already-built OCI image layout (skip the build step)

#### `--include-global`

Also include tools from the global / system config (default: project-only)

See `mise oci build --help` for details.

#### `--mount-point <MOUNT_POINT>`

Override in-image mount point (ignored with --image-dir)

#### `--no-cache`

Don't reuse tool layers from the previously pushed image

#### `--no-mise`

Don't embed the mise binary (ignored with --image-dir)

#### `--owner <UID[:GID]>`

UID[:GID] to assign to every tar entry when building (conflicts with --image-dir)

Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

#### `--update-index`

Maintain the tag as a multi-arch image index

Pushes this build's manifest by digest and points the tag at an OCI image index containing one entry per platform, preserving entries other architectures pushed. Run `mise oci push --update-index` from one runner per platform to assemble a multi-arch tag.

Examples:

    Build and push to GHCR:
    $ mise oci push ghcr.io/me/devenv:latest

    Push an image built earlier:
    $ mise oci build -o ./img
    $ mise oci push --image-dir ./img ghcr.io/me/devenv:v1

Auth:

    Credentials are resolved the same way docker/podman resolve them:
    $REGISTRY_AUTH_FILE, $XDG_RUNTIME_DIR/containers/auth.json,
    ~/.config/containers/auth.json, then ~/.docker/config.json
    (inline auths and credential helpers). Log in with either:
    $ docker login ghcr.io
    $ podman login ghcr.io

## `mise oci run`

- **Usage**: `mise oci run [FLAGS] [-- CMD]…`

[experimental] Build an OCI image from the current mise.toml and run a command in it

Equivalent to `mise oci build` followed by `docker run` / `podman run`. The built image is loaded into the local container engine (podman pulls the OCI layout natively; docker receives it via `docker load`) and the given command is executed inside it with stdin/stdout/stderr inherited.

Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`) and one of: `podman`, `docker`.

### Arguments

#### `[-- CMD]…`

Command and arguments to run inside the container (after `--`)

### Flags

#### `--engine <ENGINE>`

Container engine to use (`auto`, `podman`, or `docker`)

**Choices:**

- `auto`
- `podman`
- `docker`

**Default:** `auto`

#### `--from <FROM>`

Base image reference for the build (ignored with --image-dir)

#### `--image-dir <IMAGE_DIR>`

Use an already-built OCI image layout instead of building fresh

#### `--include-global`

Also include tools from the global / system config (default: project-only)

See `mise oci build --help` for details.

#### `--keep`

Keep the loaded image in the engine's storage after the run

By default, both the container (`--rm`) and the loaded image are removed when the command exits, so repeated `mise oci run` calls don't accumulate images in podman / docker storage. Pass `--keep` to retain the image under the tag mise used (`mise-oci:run-*` for docker; the pulled image ID for podman).

#### `--mount-point <MOUNT_POINT>`

Override in-image mount point (ignored with --image-dir)

#### `--no-mise`

Don't embed the mise binary (ignored with --image-dir)

#### `--owner <UID[:GID]>`

UID[:GID] to assign to every tar entry when building (conflicts with --image-dir)

Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

#### `--volume… <HOST:CONTAINER>`

Bind-mount a host path (repeatable, `HOST:CONTAINER[:MODE]`)

Note: unlike `docker run -v`, there's no `-v` short flag here because mise reserves `-v` for --verbose. Use `--volume` or `--mount`.

#### `-e --env… <KEY=VAL>`

Set environment variable in the container (repeatable, `KEY=VAL`)

#### `-i --interactive`

Run interactively (pass `-i` to the engine)

#### `-t --tty`

Allocate a TTY (pass `-t` to the engine)

#### `-w --workdir <WORKDIR>`

Working directory inside the container

Examples:

    Build the current mise.toml and drop into bash:
    $ mise oci run -it -- bash

    Run a one-shot command with env + volume (note: `-v` is reserved
    for --verbose, so use `--volume`):
    $ mise oci run -e DEBUG=1 --volume $PWD:/work -w /work -- npm test

    Re-use a previously built layout (skip the build step):
    $ mise oci build -o ./img && mise oci run --image-dir ./img -- node -e 'console.log(process.version)'

Engines:

    Prefers podman (loads OCI layouts natively). Falls back to docker
    (loaded via docker load). Pass --engine podman or --engine docker to override.

## `mise outdated`

- **Usage**: `mise outdated [FLAGS] [TOOL@VERSION]…`
- **Effect**: read-only

Shows outdated tool versions

See `mise upgrade` to upgrade these versions.

### 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

### Flags

#### `-b --bump`

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.

#### `-J --json`

Output in JSON format

#### `--inactive`

Show outdated tools including installed-but-inactive tools not present in the current config

By default, `mise outdated` only shows tools that come from the current config.

#### `--local`

Only show outdated tools defined in local config files

This will only show tools that are defined in project-local mise.toml and will skip tools defined in the global config (~/.config/mise/config.toml).

#### `--monorepo`

Placeholder for future monorepo outdated checks; `mise outdated --monorepo` is not implemented yet.

#### `--no-header`

Don't show table header

Deprecation:

The `-l` shorthand for `--bump` is deprecated and will be removed in mise 2027.8.5.
After removal, `-l` will become shorthand for `--local`. Use `-b` or `--bump` instead.

Examples:

    $ mise outdated
    Plugin  Requested  Current  Latest
    python  3.11       3.11.0   3.11.1
    node    20         20.0.0   20.1.0

    $ mise outdated node
    Plugin  Requested  Current  Latest
    node    20         20.0.0   20.1.0

    $ mise outdated --json
    {"python": {"requested": "3.11", "current": "3.11.0", "latest": "3.11.1"}, ...}

    $ mise outdated --local
    Plugin  Requested  Current  Latest
    node    20         20.0.0   20.1.0

## `mise patrons`

- **Usage**: `mise patrons [-J --json] [--refresh]`
- **Effect**: read-only

Show the individuals supporting mise as Patron-tier members

Lists the individuals on the Patron tier from <https://jdx.dev/patrons.json>. The list refreshes daily; supporting terminals will render each patron's name as a clickable link via OSC 8 hyperlinks.

To appear here, become a patron at <https://jdx.dev/sponsors.html>.

### Flags

#### `-J --json`

Output in JSON format

#### `--refresh`

Bypass the local cache and re-fetch

Examples:

    $ mise patrons
    $ mise patrons -J
    $ mise patrons --refresh

## `mise plugins`

- **Usage**: `mise plugins [FLAGS] <SUBCOMMAND>`
- **Aliases**: `p`
- **Effect**: read-only

Manage plugins

### Flags

#### `-c --core`

The built-in plugins only
Normally these are not shown

#### `-u --urls`

Show the git url for each plugin
e.g.: https://github.com/mise-plugins/vfox-cmake.git

#### `--user`

List installed plugins

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

## `mise plugins install`

- **Usage**: `mise plugins install [FLAGS] [NEW_PLUGIN] [GIT_URL]`
- **Aliases**: `i`, `a`, `add`
- **Effect**: modifies state

Install a plugin

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

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

### Arguments

#### `[NEW_PLUGIN]`

The name of the plugin to install
e.g.: cmake, poetry
Can specify multiple plugins: `mise plugins install cmake poetry`

#### `[GIT_URL]`

The git url of the plugin

### Flags

#### `-a --all`

Install all missing plugins
This will only install plugins that have matching shorthands.
i.e.: they don't need the full git repo url

#### `-f --force`

Reinstall even if plugin exists

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1

#### `-v --verbose…`

Show installation output

Examples:

    # install the poetry via shorthand
    $ mise plugins install poetry

    # install the poetry plugin using a specific git url
    $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git

    # install the poetry plugin using the git url only
    # (poetry is inferred from the url)
    $ mise plugins install https://github.com/mise-plugins/mise-poetry.git

    # install the poetry plugin using a specific ref
    $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git#11d0c1e

## `mise plugins link`

- **Usage**: `mise plugins link [-f --force] <NAME> [DIR]`
- **Aliases**: `ln`
- **Effect**: modifies state

Symlinks a plugin into mise

This is used for developing a plugin.

### Arguments

#### `<NAME>`

The name of the plugin
e.g.: cmake, poetry

#### `[DIR]`

The local path to the plugin
e.g.: ./vfox-cmake

### Flags

#### `-f --force`

Overwrite existing plugin

Examples:

    # essentially just `ln -s ./vfox-cmake ~/.local/share/mise/plugins/cmake`
    $ mise plugins link cmake ./vfox-cmake

    # infer plugin name as "cmake"
    $ mise plugins link ./vfox-cmake

## `mise plugins ls`

- **Usage**: `mise plugins ls [-o --outdated] [-u --urls]`
- **Aliases**: `list`
- **Effect**: read-only

List installed plugins

Can also show remotely available plugins to install.

### Flags

#### `-o --outdated`

Show plugins with available updates
Checks the remote for newer versions and only displays plugins that are outdated

#### `-u --urls`

Show the git url for each plugin
e.g.: https://github.com/mise-plugins/vfox-cmake.git

Examples:

    $ mise plugins ls
    cmake
    poetry

    $ mise plugins ls --urls
    cmake     https://github.com/mise-plugins/vfox-cmake.git
    poetry    https://github.com/mise-plugins/vfox-poetry.git

## `mise plugins ls-remote`

- **Usage**: `mise plugins ls-remote [-u --urls] [--only-names]`
- **Aliases**: `list-remote`, `list-all`
- **Effect**: read-only


List all available remote plugins

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

Examples:

    $ mise plugins ls-remote

### Flags

#### `-u --urls`

Show the git url for each plugin
e.g.: https://github.com/mise-plugins/mise-poetry.git

#### `--only-names`

Only show the name of each plugin
by default it will show a "*" next to installed plugins

## `mise plugins uninstall`

- **Usage**: `mise plugins uninstall [-a --all] [-p --purge] [PLUGIN]…`
- **Aliases**: `remove`, `rm`
- **Effect**: destructive — may delete or irreversibly overwrite

Removes a plugin

### Arguments

#### `[PLUGIN]…`

Plugin(s) to remove

### Flags

#### `-a --all`

Remove all plugins

#### `-p --purge`

Also remove the plugin's installs, downloads, and cache

Examples:

    $ mise plugins uninstall cmake

## `mise plugins update`

- **Usage**: `mise plugins update [-j --jobs <JOBS>] [PLUGIN]…`
- **Aliases**: `up`, `upgrade`
- **Effect**: modifies state

Updates a plugin to the latest version

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

### Arguments

#### `[PLUGIN]…`

Plugin(s) to update

### Flags

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
Default: 4

Examples:

    $ mise plugins update              # update all plugins
    $ mise plugins update cmake       # update only cmake
    $ mise plugins update cmake#beta  # specify a ref

## `mise deps`

- **Usage**: `mise deps [FLAGS] [PROVIDER] <SUBCOMMAND>`
- **Aliases**: `dep`
- **Effect**: modifies state

[experimental] Manage project dependencies

Runs all applicable dependency install 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-deps flag.

### Arguments

#### `[PROVIDER]`

Provider to operate on (runs only this provider, or use with --explain)

### Flags

#### `--explain`

Show why a provider is fresh or stale (requires a provider argument)

#### `-f --force`

Force run all deps steps even if outputs are fresh

#### `-n --dry-run`

Only check if deps install is needed, don't run commands

#### `--list`

Show what deps providers are available

#### `--monorepo`

Install dependencies from every [monorepo].config_roots config root

Requires monorepo_root = true plus explicit [monorepo].config_roots in the monorepo root config. Providers are named like //apps/api:uv.

**Environment Variable:** `MISE_MONOREPO`

#### `--only… <ONLY>`

Run specific deps rule(s) only

#### `--skip… <SKIP>`

Skip specific deps rule(s)

Examples:

    $ mise deps                    # Install all project dependencies
    $ mise deps install            # Same as bare `mise deps`
    $ mise deps install --force    # Force reinstall even if fresh
    $ mise deps install --dry-run  # Show what would run
    $ mise deps --monorepo         # Install deps from explicit monorepo config roots
    $ mise deps add npm:react      # Add a dependency
    $ mise deps add -D npm:vitest  # Add a dev dependency
    $ mise deps remove npm:lodash  # Remove a dependency

Configuration:

```toml
# Built-in npm provider (auto-detects lockfile)
[deps.npm]
auto = true              # Auto-run before mise x/run

# Custom provider
[deps.codegen]
auto = true
sources = ["schema/*.graphql"]
outputs = ["src/generated/"]
run = "npm run codegen"

[deps]
disable = ["npm"]        # Disable specific providers at runtime
```

## `mise deps add`

- **Usage**: `mise deps add [-D --dev] <PACKAGES>…`
- **Effect**: modifies state

Add a dependency

Adds one or more packages to the project using the appropriate package manager. Package specs use the format `ecosystem:package`, e.g., `npm:react` or `npm:@types/react@19`.

### Arguments

#### `<PACKAGES>…`

Package(s) to add (e.g., npm:react, npm:@types/react@19)

### Flags

#### `-D --dev`

Add as a development dependency

## `mise deps install`

- **Usage**: `mise deps install [FLAGS] [PROVIDER]`
- **Effect**: modifies state

Install all project dependencies

Checks if dependency lockfiles are newer than installed outputs and runs install commands if needed.

### Arguments

#### `[PROVIDER]`

Provider to operate on (runs only this provider, or use with --explain)

### Flags

#### `--explain`

Show why a provider is fresh or stale (requires a provider argument)

#### `-f --force`

Force run all deps steps even if outputs are fresh

#### `-n --dry-run`

Only check if deps install is needed, don't run commands

#### `--list`

Show what deps providers are available

#### `--monorepo`

Install dependencies from every [monorepo].config_roots config root

Requires monorepo_root = true plus explicit [monorepo].config_roots in the monorepo root config. Providers are named like //apps/api:uv.

**Environment Variable:** `MISE_MONOREPO`

#### `--only… <ONLY>`

Run specific deps rule(s) only

#### `--skip… <SKIP>`

Skip specific deps rule(s)

## `mise deps remove`

- **Usage**: `mise deps remove <PACKAGES>…`
- **Effect**: destructive — may delete or irreversibly overwrite

Remove a dependency

Removes one or more packages from the project using the appropriate package manager. Package specs use the format `ecosystem:package`, e.g., `npm:lodash`.

### Arguments

#### `<PACKAGES>…`

Package(s) to remove (e.g., npm:lodash)

## `mise prune`

- **Usage**: `mise prune [FLAGS] [INSTALLED_TOOL]…`
- **Effect**: destructive — may delete or irreversibly overwrite

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_<TOOL>_VERSION` will be deleted, as will versions only referenced on the command line `mise exec <TOOL>@<VERSION>`.

Tool stubs that have been executed are tracked in ~/.local/state/mise/tracked-stubs. Versions still referenced by a tracked stub are not deleted.

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

### Arguments

#### `[INSTALLED_TOOL]…`

Prune only these tools

### Flags

#### `-n --dry-run`

Do not actually delete anything

#### `--configs`

Prune only tracked and trusted configuration links that point to nonexistent configurations

#### `--dry-run-code`

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.

#### `--monorepo`

Placeholder for future monorepo pruning; `mise prune --monorepo` is not implemented yet.

#### `--tools`

Prune only unused versions of tools

Examples:

    $ mise prune --dry-run
    rm -rf ~/.local/share/mise/versions/node/20.0.0
    rm -rf ~/.local/share/mise/versions/node/20.0.1

## `mise registry`

- **Usage**: `mise registry [FLAGS] [NAME]`
- **Effect**: read-only

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`.

### Arguments

#### `[NAME]`

Show only the specified tool's full name

### Flags

#### `-b --backend <BACKEND>`

Show only tools for this backend

#### `--hide-aliased`

Hide aliased tools

#### `-J --json`

Output in JSON format

#### `--security`

Include security features for each tool's backends in JSON output.

Requires --json. Security info is de-duplicated across all of a tool's backends. This can add noticeable time for large listings since each backend's security info is resolved individually.

Examples:

    $ mise registry
    node    core:node
    poetry  asdf:mise-plugins/mise-poetry
    ubi     cargo:ubi-cli

    $ mise registry poetry
    asdf:mise-plugins/mise-poetry

## `mise render-help`

- **Usage**: `mise render-help`
- **Effect**: modifies state

internal command to generate markdown from help

## `mise reshim`

- **Usage**: `mise reshim [-f --force]`
- **Effect**: modifies state

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 set up 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.

### Flags

#### `-f --force`

Removes all shims before reshimming

Examples:

    $ mise reshim
    $ ~/.local/share/mise/shims/node -v
    v20.0.0

## `mise run`

- **Usage**: `mise run [FLAGS]`
- **Aliases**: `r`

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

### Flags

#### `--affected`

Run matching tasks only for projects affected by Git changes

#### `--affected-base <REV>`

Git base revision for --affected
Defaults to MISE_AFFECTED_BASE, CI metadata, or HEAD~1

#### `--affected-explain`

Explain why projects and tasks were selected by --affected

#### `--affected-head <REV>`

Git head revision for --affected
Defaults to MISE_AFFECTED_HEAD, CI metadata, or HEAD

#### `--affected-json`

Output affected projects and tasks as JSON without running tasks

#### `--all`

Open the interactive selector with all tasks from the entire monorepo

#### `-c --continue-on-error`

Continue running tasks even if one fails

#### `-C --cd <CD>`

Change to this directory before executing the command

#### `-f --force`

Force the tasks to run even if outputs are up to date

#### `-j --jobs <JOBS>`

Number of tasks to run in parallel
Values below 1 are treated as 1
[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Don't actually run the task(s), just print them in order of execution

#### `-o --output <OUTPUT>`

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

**Environment Variable:** `MISE_TASK_OUTPUT`

#### `-q --quiet`

Don't show extra output

**Environment Variable:** `MISE_QUIET`

#### `-r --raw`

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

#### `-s --shell <SHELL>`

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.

#### `-S --silent`

Don't show any output except for errors

**Environment Variable:** `MISE_SILENT`

#### `-t --tool… <TOOL@VERSION>`

Tool(s) to run in addition to what is in mise.toml files
e.g.: node@20 python@3.10

#### `--allow-env… <VAR>`

Allow specific env var through (implies --deny-env for everything else)
Supports wildcards, e.g. --allow-env='MYAPP_*'

#### `--allow-net… <HOST>`

Allow network to specific host (implies --deny-net for everything else)

#### `--allow-read… <PATH>`

Allow reads from specific path (implies --deny-read for everything else)

#### `--allow-write… <PATH>`

Allow writes to specific path (implies --deny-write for everything else)

#### `--deny-all`

Block reads, writes, network, and env vars

#### `--deny-env`

Block env var inheritance (only PATH, HOME, USER, SHELL, TERM, LANG pass through)

#### `--deny-net`

Block all network access

#### `--deny-read`

Block filesystem reads (system libs and tool dirs still accessible)

#### `--deny-write`

Block all filesystem writes

#### `--fresh-env`

Bypass the environment cache and recompute the environment

#### `--no-cache`

Do not use cache on remote tasks

**Environment Variable:** `MISE_TASK_REMOTE_NO_CACHE`

#### `--no-deps`

Skip automatic dependency preparation

#### `--no-timings`

Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

#### `--skip-deps`

Run only the specified tasks skipping all dependencies

**Environment Variable:** `MISE_TASK_SKIP_DEPENDS`

#### `--skip-tools`

Skip installing tools before running tasks

Can also be set persistently with the `task.run_auto_install` setting or `MISE_TASK_RUN_AUTO_INSTALL=false` env var

#### `--task-cache <TASK_CACHE>`

Set task output cache access for this run

- `read-write` - Read cached results and write new results - `read-only` - Read cached results without writing new results - `write-only` - Write new results without reading cached results - `off` - Disable task output caching - `local-only` - Read and write only the local cache; currently equivalent to `read-write`

**Choices:**

- `read-write`
- `read-only`
- `write-only`
- `off`
- `local-only`

**Default:** `read-write`

**Environment Variable:** `MISE_TASK_CACHE`

#### `--task-cache-explain`

Explain the inputs that produced each task's output cache key

#### `--task-cache-explain-json`

Output cache-key input details as JSON Lines without running tasks

#### `--task-cache-stats`

Report task output cache hits, restored bytes, and time saved

#### `--timeout <TIMEOUT>`

Timeout for the task to complete
e.g.: 30s, 5m

Examples:

    # Runs the "lint" tasks. This needs to either be defined in mise.toml
    # or as a standalone script. See the project README for more information.
    $ mise run lint

    # Forces the "build" tasks to run even if its sources are up-to-date.
    $ mise run --force build

    # Run "test" with stdin/stdout/stderr all connected to the current terminal.
    # This forces `--jobs=1` to prevent interleaving of output.
    $ mise run --raw test

    # Runs the "lint", "test", and "check" tasks in parallel.
    $ mise run lint ::: test ::: check

    # Execute multiple tasks each with their own arguments.
    $ mise run cmd1 arg1 arg2 ::: cmd2 arg1 arg2

## `mise search`

- **Usage**: `mise search [FLAGS] [NAME]`
- **Effect**: read-only

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.

### Arguments

#### `[NAME]`

The tool to search for

### Flags

#### `-i --interactive`

Show interactive search

#### `-m --match-type <MATCH_TYPE>`

Match type: equal, contains, or fuzzy

**Choices:**

- `equal`
- `contains`
- `fuzzy`

**Default:** `fuzzy`

#### `--no-header`

Don't display headers

Examples:

    $ mise search jq
    Tool  Description
    jq    Command-line JSON processor. https://github.com/jqlang/jq
    jqp   A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp
    jiq   jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq
    gojq  Pure Go implementation of jq. https://github.com/itchyny/gojq

    $ mise search --interactive
    Tool
    Search a tool
    ❯ jq    Command-line JSON processor. https://github.com/jqlang/jq
      jqp   A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp
      jiq   jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq
      gojq  Pure Go implementation of jq. https://github.com/itchyny/gojq
    /jq 
    esc clear filter • enter confirm

## `mise self-update`

- **Usage**: `mise self-update [FLAGS] [VERSION]`
- **Effect**: modifies state

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 mise's GitHub token resolution chain for authenticated requests.

Packagers can disable this command so that mise is updated through the package manager instead. See https://mise.jdx.dev/contributing.html#packaging-and-self-update-instructions

### Arguments

#### `[VERSION]`

Update to a specific version

### Flags

#### `-f --force`

Update even if already up to date

#### `-y --yes`

Skip confirmation prompt

#### `--no-plugins`

Disable auto-updating plugins

## `mise set`

- **Usage**: `mise set [FLAGS] [ENV_VAR]…`
- **Effect**: modifies state

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`.

### Arguments

#### `[ENV_VAR]…`

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

### Flags

#### `-E --env <ENV>`

Create/modify an environment-specific config file like .mise.<env>.toml

#### `-g --global`

Set the environment variable in the global config file

#### `--age-encrypt`

[experimental] Encrypt the value with age before storing

#### `--age-key-file <PATH>`

[experimental] Age identity file for encryption

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

#### `--age-recipient… <RECIPIENT>`

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

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

#### `--age-ssh-recipient… <PATH_OR_PUBKEY>`

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

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

#### `--file <FILE>`

**Aliases:** `--path`

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`](https://mise.jdx.dev/configuration.html#mise_default_config_filename) environment variable, or `mise.toml`. Use [`MISE_GLOBAL_CONFIG_FILE`](https://mise.jdx.dev/configuration.html#mise_global_config_file) to choose a different global config path.

#### `--no-redact`

Show raw values instead of redacting secrets

#### `--prompt`

Prompt for environment variable values

#### `--stdin`

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.

Examples:

    $ mise set NODE_ENV=production

    $ mise set NODE_ENV
    production

    $ mise set -E staging NODE_ENV=staging
    # creates or modifies mise.staging.toml

    $ mise set
    key       value       source
    NODE_ENV  production  ~/.config/mise/config.toml

    $ mise set --prompt PASSWORD
    Enter value for PASSWORD: [hidden input]

    Multiline Values (--stdin):

    $ cat private.key | mise set --stdin MY_KEY

    $ printf "line1\nline2" | mise set --stdin MY_KEY

    [experimental] Age Encryption:

    $ mise set --age-encrypt API_KEY=secret

    $ mise set --age-encrypt --prompt API_KEY
    Enter value for API_KEY: [hidden input]

## `mise settings`

- **Usage**: `mise settings [FLAGS] [SETTING] [VALUE] <SUBCOMMAND>`
- **Effect**: modifies state

Manage settings

### Arguments

#### `[SETTING]`

Name of setting

#### `[VALUE]`

Setting value to set

### Global Flags

#### `-l --local`

Use the local config file instead of the global one

### Flags

#### `-a --all`

List all settings

#### `-J --json`

Output in JSON format

#### `-T --toml`

Output in TOML format

#### `--json-extended`

Output in JSON format with sources

Examples:
    # list all settings
    $ mise settings

    # get the value of the setting "always_keep_download"
    $ mise settings always_keep_download

    # set the value of the setting "always_keep_download" to "true"
    $ mise settings always_keep_download=true

    # set the value of the setting "node.mirror_url" to "https://npmmirror.com/mirrors/node/"
    $ mise settings node.mirror_url https://npmmirror.com/mirrors/node/

## `mise settings add`

- **Usage**: `mise settings add [-l --local] <SETTING> [VALUE]`
- **Effect**: modifies state

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

### Arguments

#### `<SETTING>`

The setting to set

#### `[VALUE]`

The value to set (optional if provided as KEY=VALUE)

### Flags

#### `-l --local`

Use the local config file instead of the global one

Examples:

    $ mise settings add disable_hints python_multi

## `mise settings get`

- **Usage**: `mise settings get [-l --local] <SETTING>`
- **Effect**: read-only

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`

### Arguments

#### `<SETTING>`

The setting to show

### Flags

#### `-l --local`

Use the local config file instead of the global one

Examples:

    $ mise settings get idiomatic_version_file
    true

## `mise settings ls`

- **Usage**: `mise settings ls [FLAGS] [SETTING]`
- **Aliases**: `list`
- **Effect**: read-only

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`

### Arguments

#### `[SETTING]`

Name of setting

### Flags

#### `-a --all`

List all settings

#### `-J --json`

Output in JSON format

#### `-l --local`

Use the local config file instead of the global one

#### `-T --toml`

Output in TOML format

#### `--json-extended`

Output in JSON format with sources

Examples:

    $ mise settings ls
    idiomatic_version_file = false
    ...

    $ mise settings ls python
    default_packages_file = "~/.default-python-packages"
    ...

## `mise settings set`

- **Usage**: `mise settings set [-l --local] <SETTING> [VALUE]`
- **Aliases**: `create`
- **Effect**: modifies state

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

### Arguments

#### `<SETTING>`

The setting to set

#### `[VALUE]`

The value to set (optional if provided as KEY=VALUE)

### Flags

#### `-l --local`

Use the local config file instead of the global one

Examples:

    $ mise settings idiomatic_version_file=true

## `mise settings unset`

- **Usage**: `mise settings unset [-l --local] <KEY>`
- **Aliases**: `rm`, `remove`, `delete`, `del`
- **Effect**: modifies state

Clears a setting

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

### Arguments

#### `<KEY>`

The setting to remove

### Flags

#### `-l --local`

Use the local config file instead of the global one

Examples:

    $ mise settings unset idiomatic_version_file

## `mise shell`

- **Usage**: `mise shell [FLAGS] <TOOL@VERSION>…`
- **Aliases**: `sh`
- **Effect**: read-only

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`.

### Arguments

#### `<TOOL@VERSION>…`

Tool(s) to use

### Flags

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_JOBS`

#### `-u --unset`

Removes a previously set version

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies --jobs=1

Examples:

    $ mise shell node@20
    $ node -v
    v20.0.0

## `mise shell-alias`

- **Usage**: `mise shell-alias [--no-header] <SUBCOMMAND>`
- **Effect**: read-only

Manage shell aliases.

### Flags

#### `--no-header`

Don't show table header

## `mise shell-alias get`

- **Usage**: `mise shell-alias get <shell_alias>`
- **Effect**: read-only

Show the command for a shell alias

### Arguments

#### `<shell_alias>`

The alias to show

Examples:

    $ mise shell-alias get ll
    ls -la

## `mise shell-alias ls`

- **Usage**: `mise shell-alias ls [--no-header]`
- **Aliases**: `list`
- **Effect**: read-only

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.

### Flags

#### `--no-header`

Don't show table header

Examples:

    $ mise shell-alias ls
    alias    command
    ll       ls -la
    gs       git status

## `mise shell-alias set`

- **Usage**: `mise shell-alias set <shell_alias> [COMMAND]`
- **Aliases**: `add`, `create`
- **Effect**: modifies state

Add/update a shell alias

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

### Arguments

#### `<shell_alias>`

The alias name

#### `[COMMAND]`

The command to run (optional if provided as ALIAS=COMMAND)

Examples:

    $ mise shell-alias set ll "ls -la"
    $ mise shell-alias set gs "git status"

## `mise shell-alias unset`

- **Usage**: `mise shell-alias unset <shell_alias>`
- **Aliases**: `rm`, `remove`, `delete`, `del`
- **Effect**: modifies state

Removes a shell alias

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

### Arguments

#### `<shell_alias>`

The alias to remove

Examples:

    $ mise shell-alias unset ll

## `mise sponsors`

- **Usage**: `mise sponsors`
- **Effect**: read-only

Show the companies sponsoring mise and the jdx.dev open source tools

## `mise sync`

- **Usage**: `mise sync <SUBCOMMAND>`
- **Effect**: read-only

Synchronize tools from other version managers with mise

## `mise sync node`

- **Usage**: `mise sync node [FLAGS]`
- **Effect**: modifies state

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 managed installs, runtime aliases, or links from other providers.

### Flags

#### `--brew`

Get tool versions from Homebrew

#### `--nodenv`

Get tool versions from nodenv

#### `--nvm`

Get tool versions from nvm

Examples:

    $ brew install node@18 node@20
    $ mise sync node --brew
    $ mise use -g node@18 - uses Homebrew-provided node

## `mise sync python`

- **Usage**: `mise sync python [--pyenv] [--uv]`
- **Effect**: modifies state

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 managed installs, runtime aliases, or links from other providers.

### Flags

#### `--pyenv`

Get tool versions from pyenv

#### `--uv`

Sync tool versions with uv (2-way sync)

Examples:

    $ pyenv install 3.11.0
    $ mise sync python --pyenv
    $ mise use -g python@3.11.0 - uses pyenv-provided python
    
    $ uv python install 3.11.0
    $ mise install python@3.10.0
    $ mise sync python --uv
    $ mise x python@3.11.0 -- python -V - uses uv-provided python
    $ uv run -p 3.10.0 -- python -V - uses mise-provided python

## `mise sync ruby`

- **Usage**: `mise sync ruby <--brew>`
- **Effect**: modifies state

Symlinks all ruby tool versions from an external tool into mise

### Flags

#### `--brew`

Get tool versions from Homebrew

Examples:

    $ brew install ruby
    $ mise sync ruby --brew
    $ mise use -g ruby - Use the latest version of Ruby installed by Homebrew

## `mise tasks`

- **Usage**: `mise tasks [FLAGS] [TASK] <SUBCOMMAND>`
- **Aliases**: `t`
- **Effect**: read-only

Manage tasks

### Arguments

#### `[TASK]`

Task name to get info of

### Flags

#### `-g --global`

Only show global tasks

#### `-J --json`

Output in JSON format

#### `-l --local`

Only show non-global tasks

#### `-x --extended`

Show all columns

#### `--all`

Load all tasks from the entire monorepo, including sibling directories.
By default, only tasks from the current directory hierarchy are loaded.

#### `--hidden`

Show hidden tasks

#### `--name-only`

Only show task names, one per line. Useful for piping to fzf and similar tools.

#### `--no-header`

Do not print table header

#### `--sort <COLUMN>`

Sort by column. Default is name.

**Choices:**

- `name`
- `alias`
- `description`
- `source`

#### `--sort-order <SORT_ORDER>`

Sort order. Default is asc.

**Choices:**

- `asc`
- `desc`

## `mise tasks add`

- **Usage**: `mise tasks add [FLAGS] <TASK> [-- RUN]…`
- **Effect**: modifies state

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

### Arguments

#### `<TASK>`

Tasks name to add

#### `[-- RUN]…`

### Flags

#### `-a --alias… <ALIAS>`

Other names for the task

#### `-d --depends… <DEPENDS>`

Add dependencies to the task

#### `-D --dir <DIR>`

Run the task in a specific directory

#### `-f --file`

Create a file task instead of a toml task

#### `-H --hide`

Hide the task from `mise tasks` and completions

#### `-q --quiet`

Do not print the command before running

#### `-r --raw`

Directly connect stdin/stdout/stderr

#### `-s --sources… <SOURCES>`

Glob patterns of files this task uses as input

#### `-w --wait-for… <WAIT_FOR>`

Wait for these tasks to complete if they are to run

#### `--depends-post… <DEPENDS_POST>`

Dependencies to run after the task runs

#### `--description <DESCRIPTION>`

Description of the task

#### `--outputs… <OUTPUTS>`

Glob patterns of files this task creates, to skip if they are not modified

#### `--run-windows <RUN_WINDOWS>`

Command to run on windows

#### `--shell <SHELL>`

Run the task in a specific shell

#### `--silent`

Do not print the command or its output

Examples:

    $ mise tasks add pre-commit --depends "test" --depends "render" -- echo pre-commit

## `mise tasks deps`

- **Usage**: `mise tasks deps [FLAGS] [TASKS]…`
- **Effect**: read-only

Display a tree visualization of a dependency graph

### Arguments

#### `[TASKS]…`

Tasks to show dependencies for
Can specify multiple tasks by separating with spaces
e.g.: mise tasks deps lint test check

### Flags

#### `--compact`

Collapse repeated dependencies after their first occurrence

#### `--dot`

Display dependencies in DOT format

#### `--hidden`

Show hidden tasks

Examples:

    # Show dependencies for all tasks
    $ mise tasks deps

    # Show dependencies for the "lint", "test" and "check" tasks
    $ mise tasks deps lint test check

    # Show dependencies in DOT format
    $ mise tasks deps --dot

    # Collapse repeated dependencies
    $ mise tasks deps --compact

## `mise tasks edit`

- **Usage**: `mise tasks edit [-p --path] <TASK>`
- **Effect**: modifies state

Edit a task with $EDITOR

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

### Arguments

#### `<TASK>`

Task to edit

### Flags

#### `-p --path`

Display the path to the task instead of editing it

Examples:

    $ mise tasks edit build
    $ mise tasks edit test

## `mise tasks graph`

- **Usage**: `mise tasks graph [FLAGS]`
- **Effect**: read-only

[experimental] Inspect the workspace project graph

### Flags

#### `-J --json`

Output the project graph as JSON

#### `--explain`

Explain provider attribution for inferred projects and tasks

#### `--no-header`

Do not print table headers

Examples:

    # Inspect projects and their dependency edges
    $ mise tasks graph

    # Emit the project graph as JSON
    $ mise tasks graph --json

    # Explain where inferred projects and task fields came from
    $ mise tasks graph --explain

## `mise tasks info`

- **Usage**: `mise tasks info [-J --json] <TASK>`
- **Effect**: read-only

Get information about a task

### Arguments

#### `<TASK>`

Name of the task to get information about

### Flags

#### `-J --json`

Output in JSON format

Examples:

    $ mise tasks info
    Name: test
    Aliases: t
    Description: Test the application
    Source: ~/src/myproj/mise.toml

    $ mise tasks info test --json
    {
      "name": "test",
      "aliases": "t",
      "description": "Test the application",
      "source": "~/src/myproj/mise.toml",
      "config_sources": ["~/src/myproj/mise.toml"],
      "depends": [],
      "env": {},
      "dir": null,
      "hide": false,
      "raw": false,
      "sources": [],
      "outputs": [],
      "run": [
        "echo \"testing!\""
      ],
      "file": null,
      "usage_spec": {}
    }

## `mise tasks ls`

- **Usage**: `mise tasks ls [FLAGS]`
- **Effect**: read-only

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.

### Flags

#### `-g --global`

Only show global tasks

#### `-J --json`

Output in JSON format

#### `-l --local`

Only show non-global tasks

#### `-x --extended`

Show all columns

#### `--all`

Load all tasks from the entire monorepo, including sibling directories.
By default, only tasks from the current directory hierarchy are loaded.

#### `--hidden`

Show hidden tasks

#### `--name-only`

Only show task names, one per line. Useful for piping to fzf and similar tools.

#### `--no-header`

Do not print table header

#### `--sort <COLUMN>`

Sort by column. Default is name.

**Choices:**

- `name`
- `alias`
- `description`
- `source`

#### `--sort-order <SORT_ORDER>`

Sort order. Default is asc.

**Choices:**

- `asc`
- `desc`

Examples:

    $ mise tasks ls

## `mise tasks run`

- **Usage**: `mise tasks run [FLAGS] [TASK] [ARGS]…`
- **Aliases**: `r`

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

### Arguments

#### `[TASK]`

Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
Defaults to `default` when omitted

#### `[ARGS]…`

Arguments to pass to the tasks. Use ":::" to separate tasks.

### Flags

#### `--affected`

Run matching tasks only for projects affected by Git changes

#### `--affected-base <REV>`

Git base revision for --affected
Defaults to MISE_AFFECTED_BASE, CI metadata, or HEAD~1

#### `--affected-explain`

Explain why projects and tasks were selected by --affected

#### `--affected-head <REV>`

Git head revision for --affected
Defaults to MISE_AFFECTED_HEAD, CI metadata, or HEAD

#### `--affected-json`

Output affected projects and tasks as JSON without running tasks

#### `--all`

Open the interactive selector with all tasks from the entire monorepo

#### `-c --continue-on-error`

Continue running tasks even if one fails

#### `-C --cd <CD>`

Change to this directory before executing the command

#### `-f --force`

Force the tasks to run even if outputs are up to date

#### `-j --jobs <JOBS>`

Number of tasks to run in parallel
Values below 1 are treated as 1
[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Don't actually run the task(s), just print them in order of execution

#### `-o --output <OUTPUT>`

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

**Environment Variable:** `MISE_TASK_OUTPUT`

#### `-q --quiet`

Don't show extra output

**Environment Variable:** `MISE_QUIET`

#### `-r --raw`

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

#### `-s --shell <SHELL>`

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.

#### `-S --silent`

Don't show any output except for errors

**Environment Variable:** `MISE_SILENT`

#### `-t --tool… <TOOL@VERSION>`

Tool(s) to run in addition to what is in mise.toml files
e.g.: node@20 python@3.10

#### `--allow-env… <VAR>`

Allow specific env var through (implies --deny-env for everything else)
Supports wildcards, e.g. --allow-env='MYAPP_*'

#### `--allow-net… <HOST>`

Allow network to specific host (implies --deny-net for everything else)

#### `--allow-read… <PATH>`

Allow reads from specific path (implies --deny-read for everything else)

#### `--allow-write… <PATH>`

Allow writes to specific path (implies --deny-write for everything else)

#### `--deny-all`

Block reads, writes, network, and env vars

#### `--deny-env`

Block env var inheritance (only PATH, HOME, USER, SHELL, TERM, LANG pass through)

#### `--deny-net`

Block all network access

#### `--deny-read`

Block filesystem reads (system libs and tool dirs still accessible)

#### `--deny-write`

Block all filesystem writes

#### `--fresh-env`

Bypass the environment cache and recompute the environment

#### `--no-cache`

Do not use cache on remote tasks

**Environment Variable:** `MISE_TASK_REMOTE_NO_CACHE`

#### `--no-deps`

Skip automatic dependency preparation

#### `--no-timings`

Hides elapsed time after each task completes

Default to always hide with `MISE_TASK_TIMINGS=0`

#### `--skip-deps`

Run only the specified tasks skipping all dependencies

**Environment Variable:** `MISE_TASK_SKIP_DEPENDS`

#### `--skip-tools`

Skip installing tools before running tasks

Can also be set persistently with the `task.run_auto_install` setting or `MISE_TASK_RUN_AUTO_INSTALL=false` env var

#### `--task-cache <TASK_CACHE>`

Set task output cache access for this run

- `read-write` - Read cached results and write new results - `read-only` - Read cached results without writing new results - `write-only` - Write new results without reading cached results - `off` - Disable task output caching - `local-only` - Read and write only the local cache; currently equivalent to `read-write`

**Choices:**

- `read-write`
- `read-only`
- `write-only`
- `off`
- `local-only`

**Default:** `read-write`

**Environment Variable:** `MISE_TASK_CACHE`

#### `--task-cache-explain`

Explain the inputs that produced each task's output cache key

#### `--task-cache-explain-json`

Output cache-key input details as JSON Lines without running tasks

#### `--task-cache-stats`

Report task output cache hits, restored bytes, and time saved

#### `--timeout <TIMEOUT>`

Timeout for the task to complete
e.g.: 30s, 5m

Examples:

    # Runs the "lint" tasks. This needs to either be defined in mise.toml
    # or as a standalone script. See the project README for more information.
    $ mise run lint

    # Forces the "build" tasks to run even if its sources are up-to-date.
    $ mise run --force build

    # Run "test" with stdin/stdout/stderr all connected to the current terminal.
    # This forces `--jobs=1` to prevent interleaving of output.
    $ mise run --raw test

    # Runs the "lint", "test", and "check" tasks in parallel.
    $ mise run lint ::: test ::: check

    # Execute multiple tasks each with their own arguments.
    $ mise run cmd1 arg1 arg2 ::: cmd2 arg1 arg2

## `mise tasks validate`

- **Usage**: `mise tasks validate [--errors-only] [--json] [TASKS]…`
- **Effect**: read-only

Validate tasks for common errors and issues

### Arguments

#### `[TASKS]…`

Tasks to validate
If not specified, validates all tasks

### Flags

#### `--errors-only`

Only show errors (skip warnings)

#### `--json`

Output validation results in JSON format

Examples:

    # Validate all tasks
    $ mise tasks validate

    # Validate specific tasks
    $ mise tasks validate build test

    # Output results as JSON
    $ mise tasks validate --json

    # Only show errors (skip warnings)
    $ mise tasks validate --errors-only

Validation Checks:

The validate command performs the following checks:

  • Circular Dependencies: Detects dependency cycles
  • Missing References: Finds references to nonexistent tasks
  • Usage Spec Parsing: Validates #USAGE directives and specs
  • Timeout Format: Checks timeout values are valid durations
  • Alias Conflicts: Detects duplicate aliases across tasks
  • File Existence: Verifies file-based tasks exist
  • Directory Templates: Validates directory paths and templates
  • Shell Commands: Checks shell executables exist
  • Glob Patterns: Validates source and output patterns
  • Run Entries: Ensures tasks reference valid dependencies

## `mise test-tool`

- **Usage**: `mise test-tool [FLAGS] [TOOLS]…`

Test a tool installs and executes

### Arguments

#### `[TOOLS]…`

Tool(s) to test

### Flags

#### `-a --all`

Test every tool specified in registry/

#### `-j --jobs <JOBS>`

Number of tool tests to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_TEST_TOOL_JOBS`

#### `--all-config`

Test all tools specified in config files

#### `--include-non-defined`

Also test tools not defined in registry/, guessing how to test it

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies --jobs=1

Examples:

    $ mise test-tool ripgrep

## `mise token`

- **Usage**: `mise token <SUBCOMMAND>`
- **Effect**: read-only

Display git provider tokens mise will use

## `mise token forgejo`

- **Usage**: `mise token forgejo [--unmask] [HOST]`
- **Effect**: read-only

Display the Forgejo token mise will use for a given host

Shows which token source mise would use, useful for debugging
authentication issues. The token is masked by default.

### Arguments

#### `[HOST]`

Forgejo hostname

**Default:** `codeberg.org`

### Flags

#### `--unmask`

Show the full unmasked token

Examples:

    $ mise token forgejo
    codeberg.org: a180…61f6 (source: FORGEJO_TOKEN)

    $ mise token forgejo --unmask
    codeberg.org: a18099ca69064be387fbe37b8ad1d333758361f6 (source: FORGEJO_TOKEN)

    $ mise token forgejo forgejo.mycompany.com
    forgejo.mycompany.com: (none)

## `mise token github`

- **Usage**: `mise token github [FLAGS] [HOST]`
- **Effect**: read-only

Display the GitHub token mise will use for a given host

Shows which token source mise would use, useful for debugging
authentication issues. The token is masked by default.

### Arguments

#### `[HOST]`

GitHub hostname

**Default:** `github.com`

### Flags

#### `--oauth`

Resolve only via the native GitHub OAuth source (cache,
refresh, or device-code flow), bypassing other token sources

#### `--raw`

Print only the token value

#### `--refresh`

Mint a fresh OAuth token even if the cached one has not
expired, via the refresh-token grant or a new device-code flow.
Use after changing the GitHub App's installations or permissions:
cached tokens keep their original access until they expire

#### `--unmask`

Show the full unmasked token

Examples:

    $ mise token github
    github.com: ghp_…xxxx (source: GITHUB_TOKEN)

    $ mise token github --unmask
    github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)

    $ mise token github github.mycompany.com
    github.mycompany.com: (none)

    $ mise token github --oauth --refresh
    github.com: gho_…xxxx (source: GitHub OAuth)

## `mise token gitlab`

- **Usage**: `mise token gitlab [--unmask] [HOST]`
- **Effect**: read-only

Display the GitLab token mise will use for a given host

Shows which token source mise would use, useful for debugging
authentication issues. The token is masked by default.

### Arguments

#### `[HOST]`

GitLab hostname

**Default:** `gitlab.com`

### Flags

#### `--unmask`

Show the full unmasked token

Examples:

    $ mise token gitlab
    gitlab.com: glpa…xxxx (source: GITLAB_TOKEN)

    $ mise token gitlab --unmask
    gitlab.com: glpat-xxxxxxxxxxxx (source: GITLAB_TOKEN)

    $ mise token gitlab gitlab.mycompany.com
    gitlab.mycompany.com: (none)

## `mise tool`

- **Usage**: `mise tool [FLAGS] <TOOL>`
- **Effect**: read-only

Gets information about a tool

### Arguments

#### `<TOOL>`

Tool name to get information about

### Flags

#### `-J --json`

Output in JSON format

#### `--active`

Only show active versions

#### `--backend`

Only show backend field

#### `--config-source`

Only show config source

#### `--description`

Only show description field

#### `--installed`

Only show installed versions

#### `--requested`

Only show requested versions

#### `--tool-options`

Only show tool options

Examples:

    $ mise tool node
    Backend:            core
    Installed Versions: 20.0.0 22.0.0
    Active Version:     20.0.0
    Requested Version:  20
    Config Source:      ~/.config/mise/mise.toml
    Tool Options:       [none]

## `mise tool-stub`

- **Usage**: `mise tool-stub <FILE> [ARGS]…`

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

### 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.

## `mise trust`

- **Usage**: `mise trust [FLAGS] [CONFIG_FILE]`
- **Effect**: modifies state

Marks a config file as trusted

This means mise is allowed to parse the file when it needs to read config that may execute code or affect the environment. Without trust, mise may prompt, skip the config in some discovery paths, or fail with an untrusted-config error when it cannot prompt.

In normal mode, commands that execute project-defined behavior (`mise run`, naked task invocations such as `mise <TASK>`, `mise install`, `mise exec`, and `mise watch`) automatically trust their active config. Paranoid mode requires explicit, content-bound trust for every non-global config.

In normal mode, safe config files do not require trust: files that only contain `min_version`, `[tools]` entries with plain version strings (or arrays of them), and `[tasks]` without templates or tool options.

Trust is shared across git worktrees: a config file inside a linked worktree is trusted when the equivalent path in the repository's main checkout has been trusted. Paranoid mode disables this sharing since worktrees can check out branches with different config contents.

### Arguments

#### `[CONFIG_FILE]`

The config file whose trust status to change

### Flags

#### `-a --all`

Trust all config files in the current directory, its parents, and its subdirectories

Subdirectories are walked respecting .gitignore, skipping hidden directories and common build/dependency directories (node_modules, vendor, target, dist, build).

#### `--ignore`

Do not trust this config and ignore it in the future

#### `--show`

Show the trusted status of config files from the current directory and its parents.
Does not trust or untrust any files.

#### `--untrust`

Remove explicit trust for this config

Examples:

    # trusts ~/some_dir/mise.toml
    $ mise trust ~/some_dir/mise.toml

    # trusts mise.toml in the current or parent directory
    $ mise trust

## `mise uninstall`

- **Usage**: `mise uninstall [FLAGS] [INSTALLED_TOOL@VERSION]…`
- **Effect**: destructive — may delete or irreversibly overwrite

Removes installed tool versions

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

### Arguments

#### `[INSTALLED_TOOL@VERSION]…`

Tool(s) to remove

### Flags

#### `-a --all`

Delete all installed versions

#### `-n --dry-run`

Do not actually delete anything

#### `--dry-run-code`

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.

Examples:

    # will uninstall specific version
    $ mise uninstall node@18.0.0

    # will uninstall the current node version (if only one version is installed)
    $ mise uninstall node

    # will uninstall all installed versions of node
    $ mise uninstall --all node@18.0.0 # will uninstall all node versions

## `mise unset`

- **Usage**: `mise unset [-f --file <FILE>] [-g --global] [ENV_KEY]…`
- **Effect**: modifies state

Remove environment variable(s) from the config file.

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

### Arguments

#### `[ENV_KEY]…`

Environment variable(s) to remove
e.g.: NODE_ENV

### Flags

#### `-f --file <FILE>`

**Aliases:** `--path`

Specify a file to use instead of `mise.toml`

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`](https://mise.jdx.dev/configuration.html#mise_default_config_filename) environment variable, or `mise.toml`. Use [`MISE_GLOBAL_CONFIG_FILE`](https://mise.jdx.dev/configuration.html#mise_global_config_file) to choose a different global config path.

#### `-g --global`

Use the global config file

Examples:

    # Remove NODE_ENV from the current directory's config
    $ mise unset NODE_ENV

    # Remove NODE_ENV from the global config
    $ mise unset NODE_ENV -g

## `mise untrust`

- **Usage**: `mise untrust [CONFIG_FILE]`
- **Effect**: modifies state

Remove explicit trust for a config

### Arguments

#### `[CONFIG_FILE]`

The config file to untrust

## `mise unuse`

- **Usage**: `mise unuse [FLAGS] <INSTALLED_TOOL@VERSION>…`
- **Aliases**: `rm`, `remove`
- **Effect**: destructive — may delete or irreversibly overwrite

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`](https://mise.jdx.dev/configuration.html#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 [`MISE_GLOBAL_CONFIG_FILE`](https://mise.jdx.dev/configuration.html#mise_global_config_file) to choose a different global config path.

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

### Arguments

#### `<INSTALLED_TOOL@VERSION>…`

Tool(s) to remove

### Flags

#### `-e --env <ENV>`

Create/modify an environment-specific config file like .mise.<env>.toml

#### `-g --global`

Use the global config file (`~/.config/mise/config.toml`) instead of the local one

#### `-p --path <PATH>`

**Aliases:** `--file`

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.

#### `--no-prune`

Do not also prune the installed version

Examples:

    # will uninstall specific version
    $ mise unuse node@18.0.0

    # will uninstall specific version from global config
    $ mise unuse -g node@18.0.0

    # will uninstall specific version from .mise.local.toml
    $ mise unuse --env local node@20

    # will uninstall specific version from .mise.staging.toml
    $ mise unuse --env staging node@20

## `mise upgrade`

- **Usage**: `mise upgrade [FLAGS] [INSTALLED_TOOL@VERSION]…`
- **Aliases**: `up`
- **Effect**: modifies state

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

### Arguments

#### `[INSTALLED_TOOL@VERSION]…`

Tool(s) to upgrade
e.g.: node@20 python@3.10
If not specified, all current tools will be upgraded

### Flags

#### `-b --bump`

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"`.

#### `-i --interactive`

Display multiselect menu to choose which tools to upgrade

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Just print what would be done, don't actually do it

#### `-x --exclude… <INSTALLED_TOOL>`

Tool(s) to exclude from upgrading
e.g.: go python

#### `--dry-run-code`

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.

#### `--inactive`

Upgrade all tools, including installed-but-inactive tools not present in the current config

#### `--local`

Only upgrade tools defined in local config files

This will only upgrade tools that are defined in project-local mise.toml and will skip tools defined in the global config (~/.config/mise/config.toml).

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only upgrade to versions released before this date or older than this duration

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.

#### `--monorepo`

Placeholder for future monorepo upgrades; `mise upgrade --monorepo` is not implemented yet.

#### `--no-prune`

Do not uninstall the versions that were upgraded away from

By default the old version is removed once the new one installs, unless another tracked config or tool stub still needs it. Use this to keep it anyway, e.g. when something outside of mise points at the old install directory.

Set `upgrade.auto_prune = false` to make this the default.

#### `--prune`

Uninstall the versions that were upgraded away from

This is already the default. Use it to override `upgrade.auto_prune = false` for a single run.

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies --jobs=1

Deprecation:

The `-l` shorthand for `--bump` is deprecated and will be removed in mise 2027.8.5.
After removal, `-l` will become shorthand for `--local`. Use `-b` or `--bump` instead.

Examples:

    # Upgrades node to the latest version matching the range in mise.toml
    $ mise upgrade node

    # Upgrades node to the latest version and bumps the version in mise.toml
    $ mise upgrade node --bump

    # Upgrades all tools to the latest versions
    $ mise upgrade

    # Upgrades all tools to the latest versions and bumps the version in mise.toml
    $ mise upgrade --bump

    # Just print what would be done, don't actually do it
    $ mise upgrade --dry-run

    # Upgrades node and python to the latest versions
    $ mise upgrade node python

    # Upgrade all tools except go
    $ mise upgrade --exclude go

    # Show a multiselect menu to choose which tools to upgrade
    $ mise upgrade --interactive

    # Only upgrade tools defined in local mise.toml, not global ones
    $ mise upgrade --local

## `mise usage`

- **Usage**: `mise usage`
- **Effect**: read-only

Generate a usage CLI spec

See https://usage.jdx.dev for more information on this specification.

## `mise use`

- **Usage**: `mise use [FLAGS] [TOOL@VERSION]…`
- **Aliases**: `u`
- **Effect**: modifies state

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`](https://mise.jdx.dev/configuration.html#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 [`MISE_GLOBAL_CONFIG_FILE`](https://mise.jdx.dev/configuration.html#mise_global_config_file) to choose a different global config path.

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

### 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]

### Flags

#### `-e --env <ENV>`

Create/modify an environment-specific config file like .mise.<env>.toml

#### `-f --force`

Force reinstall even if already installed

#### `-g --global`

Use the global config file (`~/.config/mise/config.toml`) instead of the local one

#### `-j --jobs <JOBS>`

Number of jobs to run in parallel
Values below 1 are treated as 1
[default: 4]

**Environment Variable:** `MISE_JOBS`

#### `-n --dry-run`

Perform a dry run, showing what would be installed and modified without making changes

#### `-p --path <PATH>`

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.

#### `--dry-run-code`

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.

#### `--fuzzy`

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`

#### `--minimum-release-age <MINIMUM_RELEASE_AGE>`

Only install versions released before this date or older than this duration

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

#### `--pin`

Save the resolved concrete version to the config file

If the request exactly matches an available release, that release is preferred over installed fuzzy matches. Use `prefix:` to explicitly request recursive prefix matching. e.g.: `mise use --pin node@20` will save the resolved `20.x.y` 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

#### `--raw`

Connect backend install command stdin/stdout/stderr directly to the terminal
Implies `--jobs=1`

#### `--remove… <TOOL>`

Remove the tool(s) from config file

Examples:

    # run with no arguments to use the interactive selector
    $ mise use

    # set the current version of node to 20.x in mise.toml of current directory
    # will write the fuzzy version (e.g.: 20)
    $ mise use node@20

    # set the current version of node to 20.x in ~/.config/mise/config.toml
    # will write the precise version (e.g.: 20.0.0)
    $ mise use -g --pin node@20

    # sets .mise.local.toml (which is intended not to be committed to a project)
    $ mise use --env local node@20

    # sets .mise.staging.toml (which is used if MISE_ENV=staging)
    $ mise use --env staging node@20

## `mise version`

- **Usage**: `mise version [-J --json]`
- **Aliases**: `v`
- **Effect**: read-only

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.

### Flags

#### `-J --json`

Print the version information in JSON format

Examples:

    $ mise version
    $ mise --version
    $ mise -v
    $ mise -V

## `mise watch`

- **Usage**: `mise watch [FLAGS] [TASK] [ARGS]…`
- **Aliases**: `w`

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

### Arguments

#### `[TASK]`

Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: `mise run task1 arg1 arg2 ::: task2 arg1 arg2`
Defaults to `default`

#### `[ARGS]…`

Task and arguments to run

### Flags

#### `--skip-deps`

Run only the specified tasks skipping all dependencies

#### `-o --on-busy-update <MODE>`

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.

**Choices:**

- `queue`
- `do-nothing`
- `restart`
- `signal`

**Default:** `do-nothing`

#### `-r --restart`

Restart the process if it's still running

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

#### `-s --signal <SIGNAL>`

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".

#### `--stop-signal <SIGNAL>`

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.

#### `--stop-timeout <TIMEOUT>`

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`

#### `--map-signal… <SIGNAL:SIGNAL>`

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.

#### `-d --debounce <TIMEOUT>`

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`

#### `--stdin-quit`

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.

#### `-p --postpone`

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.

#### `--delay-run <DURATION>`

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 [INTERVAL]`

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'.

#### `--project-origin <DIRECTORY>`

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.

#### `--workdir <DIRECTORY>`

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.

### Filtering

#### `-w --watch… <PATH>`

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.

#### `-W --watch-non-recursive… <PATH>`

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.

#### `-F --watch-file <PATH>`

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'.

#### `--no-vcs-ignore`

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.

#### `--no-project-ignore`

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.

#### `--no-global-ignore`

Don't load global ignores

This disables loading of global or user ignore files, like '~/.gitignore', '~/.config/watchexec/ignore', or '%APPDATA%\Bazaar\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%/Bazaar/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.

#### `--no-default-ignore`

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.

#### `--no-discover-ignore`

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'.

#### `--ignore-nothing`

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.

#### `-e --exts… <EXTENSIONS>`

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.

#### `-f --filter… <PATTERN>`

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.

#### `--filter-file… <PATH>`

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.

**Environment Variable:** `WATCHEXEC_FILTER_FILES`

#### `-J --filter-prog… <EXPRESSION>`

[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'

#### `-i --ignore… <PATTERN>`

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.

#### `--ignore-file… <PATH>`

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.

**Environment Variable:** `WATCHEXEC_IGNORE_FILES`

#### `--fs-events… <EVENTS>`

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.

**Choices:**

- `access`
- `create`
- `remove`
- `rename`
- `modify`
- `metadata`

**Default:** `create,remove,rename,modify,metadata`

#### `--no-meta`

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.

### Output

#### `-c --clear [MODE]`

Clear screen before running command

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

**Choices:**

- `clear`
- `reset`

#### `--only-emit-events`

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.

#### `-N --notify`

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.

#### `--color <MODE>`

When to use terminal colours

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

**Choices:**

- `auto`
- `always`
- `never`

**Default:** `auto`

#### `--timings`

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.

#### `-q --quiet`

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.

#### `--bell`

Ring the terminal bell on command completion

### Command

#### `--shell <SHELL>`

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

#### `-n`

Shorthand for '--shell=none'

#### `--emit-events-to <MODE>`

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.

**Choices:**

- `environment`
- `stdio`
- `file`
- `json-stdio`
- `json-file`
- `none`

**Default:** `none`

#### `-E --env… <KEY=VALUE>`

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.

#### `--wrap-process <MODE>`

Configure how the process is wrapped

By default, Watchexec will run the command in a session on macOS, in a process group on other Unix platforms, 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.

**Choices:**

- `group`
- `session`
- `none`

### Debugging

#### `--print-events`

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.

#### `--manual`

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).

Examples:

    $ mise watch build
    Runs the "build" tasks. Will re-run the tasks when any of its sources change.
    Uses "sources" from the tasks definition to determine which files to watch.

    $ mise watch build --glob src/**/*.rs
    Runs the "build" tasks but specify the files to watch with a glob pattern.
    This overrides the "sources" from the tasks definition.

    $ mise watch build --clear
    Extra arguments are passed to watchexec. See `watchexec --help` for details.

    $ mise watch serve --watch src --exts rs --restart
    Starts an api server, watching for changes to "*.rs" files in "./src" and kills/restarts the server when they change.

## `mise where`

- **Usage**: `mise where <TOOL@VERSION>`
- **Effect**: read-only

Display the installation path for a tool

The tool must be installed for this to work.

### 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

Examples:

    # Show the latest installed version of node
    # If it is is not installed, errors
    $ mise where node@20
    /home/jdx/.local/share/mise/installs/node/20.0.0

    # Show the current, active install directory of node
    # Errors if node is not referenced in any .tool-version file
    $ mise where node
    /home/jdx/.local/share/mise/installs/node/20.0.0

## `mise which`

- **Usage**: `mise which [FLAGS] [BIN_NAME]`
- **Effect**: read-only

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

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

### Arguments

#### `[BIN_NAME]`

The bin to look up

### Flags

#### `-t --tool <TOOL@VERSION>`

Use a specific tool@version
e.g.: `mise which npm --tool=node@20`

#### `--plugin`

Show the plugin name instead of the path

#### `--version`

Show the version instead of the path

Examples:

    $ mise which node
    /home/username/.local/share/mise/installs/node/20.0.0/bin/node

    $ mise which node --plugin
    node

    $ mise which node --version
    20.0.0
