From a5bd463c0016a60bb3812c2a1d4f94747c0cd058 Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Sun, 5 Apr 2026 17:52:40 +0000 Subject: [PATCH 1/4] docs: add Windows default paths and mise.toml examples alongside CLI commands - Add Windows defaults for MISE_DATA_DIR (%LOCALAPPDATA%\mise) and MISE_CACHE_DIR (%TEMP%\mise) in configuration.md - Show the resulting mise.toml after `mise use` in dev-tools/index.md - Add mise.toml equivalent after backend examples in getting-started.md - Note that editing mise.toml directly is equivalent to using `mise use` Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/configuration.md | 7 +++++-- docs/dev-tools/index.md | 14 +++++++++++--- docs/getting-started.md | 11 +++++++++++ 3 files changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 29c82381eb..85b0953bfb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -474,7 +474,9 @@ mise can also be configured via environment variables. The following options are ### `MISE_DATA_DIR` -Default: `~/.local/share/mise` or `$XDG_DATA_HOME/mise` +Default (Linux): `~/.local/share/mise` or `$XDG_DATA_HOME/mise` +Default (macOS): `~/.local/share/mise` or `$XDG_DATA_HOME/mise` +Default (Windows): `%LOCALAPPDATA%\mise` or `$XDG_DATA_HOME/mise` This is the directory where mise stores plugins and tool installs. These are not supposed to be shared @@ -484,6 +486,7 @@ across machines. Default (Linux): `~/.cache/mise` or `$XDG_CACHE_HOME/mise` Default (macOS): `~/Library/Caches/mise` or `$XDG_CACHE_HOME/mise` +Default (Windows): `%TEMP%\mise` or `$XDG_CACHE_HOME/mise` This is the directory where mise stores internal cache. This is not supposed to be shared across machines. It may be deleted at any time mise is not running. @@ -504,7 +507,7 @@ This is the directory where mise stores system-wide configuration. ### `MISE_GLOBAL_CONFIG_FILE` -Default: `$MISE_CONFIG_DIR/config.toml` (Usually ~/.config/mise/config.toml) +Default: `$MISE_CONFIG_DIR/config.toml` (Usually `~/.config/mise/config.toml`) This is the path to the config file. diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md index dda923257a..f2963f5200 100644 --- a/docs/dev-tools/index.md +++ b/docs/dev-tools/index.md @@ -275,14 +275,22 @@ mise ~/my-project/mise.toml tools: node@24.x.x # mise.toml created/updated `mise use node@24` will install the latest version of node-24 and create/update the `mise.toml` -config file in the local directory. Anytime you're in that directory, that version of `node` will be -used. +config file in the local directory. The resulting file looks like this: -`mise use -g node@24` will do the same but update the [global config](/configuration.html#global-config-config-mise-config-toml) (~/.config/mise/config.toml) so +```toml [mise.toml] +[tools] +node = "24" +``` + +Anytime you're in that directory, that version of `node` will be used. + +`mise use -g node@24` will do the same but update the [global config](/configuration.html#global-config-config-mise-config-toml) (`~/.config/mise/config.toml`) so unless there is a config file in the local directory hierarchy, node-24 will be the default version for the user. +You can also edit `mise.toml` directly instead of using `mise use` — the effect is the same. Run `mise install` after editing to install any new tools. + ### [`mise install`](/cli/install) `mise install` will install but not activate tools—meaning it will download/build/compile the tool diff --git a/docs/getting-started.md b/docs/getting-started.md index efef22b60f..8a25fb3267 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -294,6 +294,17 @@ mise use --global github:BurntSushi/ripgrep rg --version ``` +Each `mise use` command above updates your config file. For example, after running all three globally, your `~/.config/mise/config.toml` would contain: + +```toml [~/.config/mise/config.toml] +[tools] +"npm:@anthropic-ai/claude-code" = "latest" +"pipx:black" = "latest" +"github:BurntSushi/ripgrep" = "latest" +``` + +You can also edit `mise.toml` directly instead of using `mise use` — the effect is the same. Run `mise install` after editing to install the tools. + See [Backends](/dev-tools/backends/) for more ecosystems and details. ## 5. Setting environment variables {#environment-variables} From ada148d73cd13f1ad0e1e6b777d9e26e3ddde394 Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Sun, 5 Apr 2026 17:55:39 +0000 Subject: [PATCH 2/4] docs: add trust explanation, hooks syntax warning, Windows shims path, and better examples - Add "Trusting config files" section to getting-started.md explaining why trust prompts appear and how to resolve them - Add warning in hooks.md about common syntax mistake ([hooks.postinstall] vs [hooks] postinstall = "...") - Add Windows shims path (%LOCALAPPDATA%\mise\shims) to shims.md - Update configuration.md example to use typical node+python project instead of terraform+erlang Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/configuration.md | 17 ++++++++++------- docs/dev-tools/shims.md | 2 +- docs/getting-started.md | 20 ++++++++++++++++++++ docs/hooks.md | 5 +++++ 4 files changed, 36 insertions(+), 8 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 85b0953bfb..0935d584c8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -131,18 +131,21 @@ $ mise set NODE_ENV=production # writes to mise.toml ::: -Here is what a `mise.toml` looks like: +Here is what a typical `mise.toml` looks like: ```toml +[tools] +node = '22' +python = '3.12' + [env] -NODE_ENV = 'production' +NODE_ENV = 'development' -[tools] -terraform = '1.0.0' -erlang = '24.0' +[tasks.dev] +run = 'npm run dev' -[tasks.build] -run = 'echo "running build tasks"' +[tasks.test] +run = 'pytest' ``` `mise.toml` files are hierarchical. The configuration in a file in the current directory will diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md index f4e23ffa69..4870550699 100644 --- a/docs/dev-tools/shims.md +++ b/docs/dev-tools/shims.md @@ -49,7 +49,7 @@ ls -l ~/.local/share/mise/shims/node # [...] ~/.local/share/mise/shims/node -> ~/.local/bin/mise ``` -By default, the shim directory is located at `~/.local/share/mise/shims`. When installing a tool (for example, `node`), `mise` will add some entries for every binary provided by this tool in the `shims` directory (for example, `~/.local/share/mise/shims/node`). +By default, the shim directory is located at `~/.local/share/mise/shims` (on Windows: `%LOCALAPPDATA%\mise\shims`). When installing a tool (for example, `node`), `mise` will add some entries for every binary provided by this tool in the `shims` directory (for example, `~/.local/share/mise/shims/node`). ```sh mise use -g node@20 diff --git a/docs/getting-started.md b/docs/getting-started.md index 8a25fb3267..1696a29309 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -307,6 +307,26 @@ You can also edit `mise.toml` directly instead of using `mise use` — the effec See [Backends](/dev-tools/backends/) for more ecosystems and details. +## Trusting config files {#trust} + +When you or a teammate adds a `mise.toml` to a project, mise will prompt you to trust it before it runs any env directives or hooks: + +``` +mise ~/my-project/mise.toml is not trusted. Trust it? [y/n] +``` + +This is a security measure — config files can execute arbitrary code via `[env]` directives, hooks, and tasks. To trust a file, run: + +```sh +mise trust +``` + +This only needs to be done once per file. See [`mise trust`](/cli/trust) for more details. + +::: tip +`mise use` automatically trusts the file it creates, so you'll only see this prompt when pulling a config someone else wrote or when editing `mise.toml` by hand. +::: + ## 5. Setting environment variables {#environment-variables} Define environment variables in `mise.toml` — they'll be loaded whenever mise is activated or when using `mise exec`: diff --git a/docs/hooks.md b/docs/hooks.md index ab7e5d56cb..db91ff04cd 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -41,6 +41,11 @@ preinstall = "echo 'I am about to install tools'" postinstall = "echo 'I just installed tools'" ``` +::: warning +The syntax is `[hooks]` with `postinstall = "..."`, **not** `[hooks.postinstall]` with `run = "..."`. +The `[hooks.]` table syntax is only used for [shell hooks](#shell-hooks) below. +::: + The `postinstall` hook receives a `MISE_INSTALLED_TOOLS` environment variable containing a JSON array of the tools that were just installed: ```toml From 0659ee3506c63aa3b371887468f39fc94da84f50 Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Sun, 5 Apr 2026 18:01:14 +0000 Subject: [PATCH 3/4] docs: add trusted_config_paths tip for disabling trust and revert hooks change - Show how to disable trust prompts entirely with `mise settings trusted_config_paths=["/"]` or MISE_TRUSTED_CONFIG_PATHS=/ - Update trusted_config_paths description in settings.toml to mention the "/" trick for disabling trust - Revert hooks.md syntax warning (removed per review) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/getting-started.md | 8 ++++++++ docs/hooks.md | 5 ----- schema/mise.json | 2 +- settings.toml | 4 +++- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 1696a29309..3ac2bb2a81 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -323,6 +323,14 @@ mise trust This only needs to be done once per file. See [`mise trust`](/cli/trust) for more details. +To disable trust prompts entirely, trust the root path: + +```sh +mise settings trusted_config_paths=["/"] +``` + +Or set the environment variable `MISE_TRUSTED_CONFIG_PATHS=/`. + ::: tip `mise use` automatically trusts the file it creates, so you'll only see this prompt when pulling a config someone else wrote or when editing `mise.toml` by hand. ::: diff --git a/docs/hooks.md b/docs/hooks.md index db91ff04cd..ab7e5d56cb 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -41,11 +41,6 @@ preinstall = "echo 'I am about to install tools'" postinstall = "echo 'I just installed tools'" ``` -::: warning -The syntax is `[hooks]` with `postinstall = "..."`, **not** `[hooks.postinstall]` with `run = "..."`. -The `[hooks.]` table syntax is only used for [shell hooks](#shell-hooks) below. -::: - The `postinstall` hook receives a `MISE_INSTALLED_TOOLS` environment variable containing a JSON array of the tools that were just installed: ```toml diff --git a/schema/mise.json b/schema/mise.json index 3362e156f2..a809e94a40 100644 --- a/schema/mise.json +++ b/schema/mise.json @@ -1583,7 +1583,7 @@ }, "trusted_config_paths": { "default": [], - "description": "This is a list of config paths that mise will automatically mark as trusted.", + "description": "This is a list of config paths that mise will automatically mark as trusted. Any config files under these paths will be trusted without prompting. Set to `[\"/\"]` to trust all config files, effectively disabling the trust mechanism.", "type": "array", "items": { "type": "string" diff --git a/settings.toml b/settings.toml index 26a127e631..a3fd924fa0 100644 --- a/settings.toml +++ b/settings.toml @@ -2179,7 +2179,9 @@ type = "Bool" [trusted_config_paths] default = [] -description = "This is a list of config paths that mise will automatically mark as trusted." +description = """This is a list of config paths that mise will automatically mark as \ +trusted. Any config files under these paths will be trusted without prompting. \ +Set to `["/"]` to trust all config files, effectively disabling the trust mechanism.""" env = "MISE_TRUSTED_CONFIG_PATHS" parse_env = "list_by_colon" rust_type = "BTreeSet" From ed15f04ff25db19b4d9a6db3b01f777b9201c0b3 Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Sun, 5 Apr 2026 18:05:43 +0000 Subject: [PATCH 4/4] docs: update node examples from 22 to 24 for consistency Node 24 is the current LTS. Align all introductory examples to avoid confusion with the pinned version output that shows node 24.x. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/configuration.md | 2 +- docs/dev-tools/index.md | 2 +- docs/mise-cookbook/nodejs.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 0935d584c8..c0065453fa 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -135,7 +135,7 @@ Here is what a typical `mise.toml` looks like: ```toml [tools] -node = '22' +node = '24' python = '3.12' [env] diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md index f2963f5200..28489daa56 100644 --- a/docs/dev-tools/index.md +++ b/docs/dev-tools/index.md @@ -13,7 +13,7 @@ To know which tool version to use, mise will typically look for a `mise.toml` fi ```toml [mise.toml] [tools] -node = '22' +node = '24' python = '3' ruby = 'latest' ``` diff --git a/docs/mise-cookbook/nodejs.md b/docs/mise-cookbook/nodejs.md index 862062c839..56f034dffa 100644 --- a/docs/mise-cookbook/nodejs.md +++ b/docs/mise-cookbook/nodejs.md @@ -110,7 +110,7 @@ This example uses `pnpm` as the package manager. This will skip installing depen ```toml [mise.toml] [tools] -node = '22' +node = '24' [hooks] # Enabling corepack will install the `pnpm` package manager specified in your package.json