docs: Add a section on how to use environment variables (jdx#4435)

hverlin · web-flow · commit b2529a2f9e98 · 2025-02-17T13:01:10.000-06:00
- update env. vars page to indicate under which conditions they work
- small updates to backend/plugins/registry pages
- clarify that `mise alias` command is only for version aliases (not
backend aliases)
diff --git a/docs/cli/alias.md b/docs/cli/alias.md
@@ -4,7 +4,7 @@
 - **Aliases**: `a`
 - **Source code**: [`src/cli/alias/mod.rs`](https://github.com/jdx/mise/blob/main/src/cli/alias/mod.rs)
 
-Manage aliases
+Manage version aliases.
 
 ## Flags
 
diff --git a/docs/cli/generate/git-pre-commit.md b/docs/cli/generate/git-pre-commit.md
@@ -11,6 +11,8 @@ 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/>
+
 ## Flags
 
 ### `--hook <HOOK>`
diff --git a/docs/components/registry.vue b/docs/components/registry.vue
@@ -4,8 +4,9 @@
     type="text"
     placeholder="Filter by Short or Full"
     v-model="filter"
+    autofocus="autofocus"
   />
-  <table>
+  <table class="full-width">
     <thead>
       <tr>
         <th>Short</th>
@@ -14,21 +15,27 @@
       </tr>
     </thead>
     <tbody>
-      <tr v-for="(entry, index) in filteredData" :key="`backend-${index}`">
+      <tr v-if="filteredData.length === 0">
+        <td colspan="3" class="no-matches">No matches found</td>
+      </tr>
+      <tr
+        v-else
+        v-for="(entry, index) in filteredData"
+        :key="`backend-${index}`"
+      >
         <td v-html="highlightMatches(entry.short)"></td>
         <td>
           <span v-for="(backend, index) in entry.backends">
             <a
               :href="`${backend.url}`"
               v-html="highlightMatches(backend.name)"
             ></a>
-            <span v-if="index < entry.backends.length - 1">,<br /></span>
+            <span v-if="index < entry.backends.length - 1"><br /></span>
           </span>
         </td>
         <td>
-          <span v-for="(os, index) in entry.os">
-            {{ os }}
-            <span v-if="index < entry.os.length - 1">, </span>
+          <span v-for="(os, index) in entry.os"
+            >{{ os }}<span v-if="index < entry.os.length - 1">, </span>
           </span>
         </td>
       </tr>
@@ -42,7 +49,8 @@ import { data } from "/registry.data.ts";
 export default {
   data() {
     return {
-      filter: "",
+      filter:
+        new URLSearchParams(globalThis?.location?.search).get("filter") || "",
       data: data,
     };
   },
@@ -60,6 +68,18 @@ export default {
       });
     },
   },
+  watch: {
+    filter(newFilter = "") {
+      const url = new URL(window.location);
+      url.hash = "tools";
+      if (newFilter.trim() === "") {
+        url.searchParams.delete("filter");
+      } else {
+        url.searchParams.set("filter", newFilter);
+      }
+      window.history.pushState({}, "", url);
+    },
+  },
   methods: {
     highlightMatches(text) {
       if (this.filter.trim() === "") return text;
@@ -71,7 +91,8 @@ export default {
       const re = new RegExp(this.filter, "ig");
       return text.replace(
         re,
-        (matchedText) => `<strong>${matchedText}</strong>`,
+        (matchedText) =>
+          `<span style="background-color: rgba(173, 216, 230, 0.2)">${matchedText}</span>`,
       );
     },
   },
@@ -88,4 +109,38 @@ export default {
   font-size: 15px;
   color: var(--vp-c-text-2);
 }
+
+.full-width {
+  width: 100%;
+  table-layout: fixed;
+  min-height: 500px;
+}
+
+.full-width th:nth-child(1),
+.full-width td:nth-child(1) {
+  min-width: 40%;
+  width: 50%;
+}
+
+.full-width th:nth-child(2),
+.full-width td:nth-child(2) {
+  min-width: 40%;
+  width: 50%;
+}
+
+.full-width th:nth-child(3),
+.full-width td:nth-child(3) {
+  min-width: 20%;
+}
+
+.full-width th,
+.full-width td {
+  word-wrap: break-word; /* Allows text to wrap within cells */
+}
+
+.no-matches {
+  text-align: center;
+  font-style: italic;
+  color: var(--vp-c-text-2);
+}
 </style>
diff --git a/docs/dev-tools/aliases.md b/docs/dev-tools/aliases.md
@@ -5,7 +5,7 @@
 Tools can be aliased so that something like `node` which normally maps to `core:node` can be changed
 to something like `asdf:company/our-custom-node` instead.
 
-```toml
+```toml [~/.config/mise/config.toml]
 [alias]
 node = 'asdf:company/our-custom-node' # shorthand for https://github.com/company/our-custom-node
 erlang = 'asdf:https://github.com/company/our-custom-erlang'
diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md
@@ -1,12 +1,17 @@
 # asdf Backend
 
-asdf is the original backend for mise. It relies on asdf plugins for each tool. asdf plugins are
-more risky to use because they're typically written by a single developer unrelated to the tool vendor
-they also do not function on Windows.
+`asdf` is the original backend for mise.
+
+It relies on asdf plugins for each tool. asdf plugins are more risky to use because they're typically written by a single developer unrelated to the tool vendor. They also do not function on Windows.
+
+asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry.toml) whenever possible. Sometimes it is not possible to use more secure backends like aqua/ubi because tools have complex install setups or need to export env vars.
+
+All of these are hosted in the mise-plugins org to secure the supply chain so you do not need to rely on plugins maintained by anyone except me.
+
 Because of the extra complexity of asdf tools and security concerns we are actively moving tools in
 the registry away from asdf where possible to backends like aqua and ubi which don't require plugins.
 That said, not all tools can function with ubi/aqua if they have a unique installation process or
-need to set env vars other than PATH.
+need to set env vars other than `PATH`.
 
 ## Writing asdf plugins for mise
 
diff --git a/docs/dev-tools/backends/index.md b/docs/dev-tools/backends/index.md
@@ -1,8 +1,12 @@
 # Backends
 
-In addition to asdf plugins, you can also directly install CLIs with some package managers.
+Backends are the way mise installs [tools](/dev-tools/) and [plugins](/plugins.html). Each backend is responsible for managing the installation and usage of a specific type of tool or package manager. This allows mise to support a wide variety of tools and languages by leveraging different backends.
 
-- [asdf](/dev-tools/backends/asdf)
+When you run the [`mise use`](/cli/use.html) command, mise will determine the appropriate backend to use based on the tool you are trying to manage. The backend will then handle the installation, configuration, and any other necessary steps to ensure the tool is ready to use.
+
+Below is a list of the available backends in mise:
+
+- [asdf](/dev-tools/backends/asdf) (provide tools through [plugins](/plugins.html))
 - [aqua](/dev-tools/backends/aqua)
 - [cargo](/dev-tools/backends/cargo)
 - [dotnet](/dev-tools/backends/dotnet) <Badge type="warning" text="experimental" />
@@ -12,7 +16,7 @@ In addition to asdf plugins, you can also directly install CLIs with some packag
 - [pipx](/dev-tools/backends/pipx)
 - [spm](/dev-tools/backends/spm) <Badge type="warning" text="experimental" />
 - [ubi](/dev-tools/backends/ubi)
-- [vfox](/dev-tools/backends/vfox) <Badge type="warning" text="experimental" />
+- [vfox](/dev-tools/backends/vfox) (provide tools through [plugins](/plugins.html)) <Badge type="warning" text="experimental" />
 
 ::: tip
 If you'd like to contribute a new backend to mise, they're not difficult to write.
diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md
@@ -4,14 +4,9 @@
 > or [pyenv](https://github.com/pyenv/pyenv) but for any language), it manages dev tools like node,
 > python, cmake, terraform, and [hundreds more](/registry.html)._
 
-::: tip
-New developer? Try reading the [Beginner's Guide](https://dev.to/jdxcode/beginners-guide-to-rtx-ac4)
-for a gentler introduction.
-:::
-
-mise is a tool that manages installations of programming language runtimes and other tools for local development. For example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine.
+`mise` is a tool that manages installations of programming language runtimes and other tools for local development. For example, it can be used to manage multiple versions of Node.js, Python, Ruby, Go, etc. on the same machine.
 
-Once [activated](/getting-started.html#activate-mise), mise will automatically switch between different versions of tools based on the directory you're in.
+Once [activated](/getting-started.html#activate-mise), mise can automatically switch between different versions of tools based on the directory you're in.
 This means that if you have a project that requires Node.js 18 and another that requires Node.js 22, mise will automatically switch between them as you move between the two projects. See tools available for mise with in the [registry](/registry).
 
 To know which tool version to use, mise will typically look for a `mise.toml` file in the current directory and its parents. To get an idea of how tools are specified, here is an example of a [mise.toml](/configuration.html) file:
diff --git a/docs/dev-tools/shims.md b/docs/dev-tools/shims.md
@@ -21,7 +21,7 @@ This is the method used when you add the `echo 'eval "$(mise activate bash)"' >>
 For example, by default, your `PATH` variable might look like this:
 
 ```sh
-echo \$PATH
+echo $PATH
 /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
 ```
 
diff --git a/docs/environments/index.md b/docs/environments/index.md
@@ -4,8 +4,9 @@
 > manages _environment variables_ for
 > different project directories.
 
-Use mise to specify environment variables used for different projects. Create a `mise.toml` file
-in the root of your project directory:
+Use mise to specify environment variables used for different projects.
+
+To get started, create a `mise.toml` file in the root of your project directory:
 
 ```toml [mise.toml]
 [env]
@@ -22,13 +23,76 @@ NODE_ENV = false # unset a previously set NODE_ENV
 You can also use the CLI to get/set env vars:
 
 ```sh
-$ mise set NODE_ENV=development
-$ mise set NODE_ENV
-development
-$ mise set
-key       value        source
-NODE_ENV  development  mise.toml
-$ mise unset NODE_ENV
+mise set NODE_ENV=development
+# mise set NODE_ENV
+# development
+
+mise set
+# key       value        source
+# NODE_ENV  development  mise.toml
+
+cat mise.toml
+# [env]
+# NODE_ENV = 'development'
+
+mise unset NODE_ENV
+```
+
+Additionally, the [mise env [--json] [--dotenv]](/cli/env.html) command can be used to export the environment variables in various formats (including `PATH` and environment variables set by tools or plugins).
+
+## Using environment variables
+
+Environment variables are available when using [`mise x|exec`](/cli/exec.html), or with [`mise r|run`](/cli/run.html) (i.e. with [tasks](/tasks/)):
+
+```shell
+mise set MY_VAR=123
+mise exec -- echo $MY_VAR
+# 123
+```
+
+You can of course combine them with [tools](/dev-tools/):
+
+```sh
+mise use node@22
+mise set MY_VAR=123
+cat mise.toml
+# [tools]
+# node = '22'
+# [env]
+# MY_VAR = '123'
+mise exec -- node --eval 'console.log(process.env.MY_VAR)'
+# 123
+```
+
+If [mise is activated](/getting-started.html#activate-mise), it will automatically set environment variables in the current shell session when you `cd` into a directory.
+
+```shell
+cd /path/to/project
+mise set NODE_ENV=production
+cat mise.toml
+# [env]
+# NODE_ENV = 'production'
+
+echo $NODE_ENV
+# production
+```
+
+If you are using [`shims`](/dev-tools/shims.html), the environment variables will be available when using the shim:
+
+```shell
+mise set NODE_ENV=production
+mise use node@22
+# using the absolute path for the example
+~/.local/share/mise/shims/node --eval 'console.log(process.env.NODE_ENV)'
+```
+
+Finally, you can also use [`mise en`](/cli/en.html) to start a new shell session with the environment variables set.
+
+```shell
+mise set FOO=bar
+mise en
+> echo $FOO
+# bar
 ```
 
 ## Lazy eval
diff --git a/docs/plugins.md b/docs/plugins.md
@@ -1,20 +1,34 @@
 # Plugins
 
-Plugins in mise extend functionality. Historically they were the only way to add new tools as the only backend was asdf. The way
-that backend works is every tool has its own plugin which needs to be manually installed. However now with core languages and
-backends like aqua/ubi, plugins are no longer necessary to run most tools in mise.
+Plugins in mise are a way to extend `mise` with new functionality like extra tools or environment variable management.
 
-Meanwhile, plugins have expanded beyond tools and can provide functionality like [setting env vars globally](/environments/#plugin-provided-env-directives) without relying on a tool being installed.
+Historically it was the only way to add new tools (as the only backend was [asdf](/dev-tools/backends/asdf.html)).
+
+The way that backend works is every tool has its own plugin which needs to be manually installed. However, now with [core tools](/core-tools.html)
+and backends like [aqua](/dev-tools/backends/aqua.html)/[ubi](/dev-tools/backends/ubi.html), plugins are no longer necessary to run most tools in mise.
 
 Tool plugins should be avoided for security reasons. New tools will not be accepted into mise built with asdf/vfox plugins unless they are very popular and
 aqua/ubi is not an option for some reason.
+
+The only exception is if the tool needs to set env vars or has a complex installation process, as plugins can provide functionality like [setting env vars globally](/environments/#plugin-provided-env-directives) without relying on a tool being installed. They can also provide [aliases for versions](/dev-tools/aliases.html#aliased-versions).
+
 If you want to integrate a new tool into mise, you should either try to get it into the [aqua registry](https://mise.jdx.dev/dev-tools/backends/aqua.html)
 or see if it can be installed with [ubi](https://mise.jdx.dev/dev-tools/backends/ubi.html). Then add it to the [registry](https://github.com/jdx/mise/blob/main/registry.toml).
 Aqua is definitely preferred to ubi as it has better UX and more features like slsa verification and the ability to use different logic for older versions.
 
+You can manage all installed plugins in `mise` with [`mise plugins`](/cli/plugins.html).
+
+```shell
+mise plugins ls --urls
+# Plugin                          Url                                                     Ref  Sha
+# 1password                       https://github.com/mise-plugins/mise-1password-cli.git  HEAD f5d5aab
+# vfox-mise-plugins-vfox-dart     https://github.com/mise-plugins/vfox-dart               HEAD 1424253
+# ...
+```
+
 ## asdf Plugins
 
-mise uses asdf's plugin ecosystem under the hood. These plugins contain shell scripts like
+mise can use asdf's plugin ecosystem under the hood. These plugins contain shell scripts like
 `bin/install` (for installing) and `bin/list-all` (for listing all of the available versions).
 
 See <https://github.com/jdx/mise/blob/main/registry.toml> for the list of built-in plugins shorthands. See asdf's
@@ -23,7 +37,7 @@ more about how they work.
 
 ## vfox Plugins
 
-Similarly, mise can also use [vfox plugins](https://mise.jdx.dev/dev-tools/backends/vfox.html). These have the advantage of working on Windows so are preferred.
+Similarly, mise can also use [vfox plugins](/dev-tools/backends/vfox.html). These have the advantage of working on Windows so are preferred.
 
 ## Plugin Authors
 
@@ -40,13 +54,13 @@ of tools. One example of this is virtualenv on python runtimes:
 
 ```toml
 [tools]
-python = {version='3.11', virtualenv='.venv'}
+python = { version='3.11', virtualenv='.venv' }
 ```
 
 This will be passed to all plugin scripts as `MISE_TOOL_OPTS__VIRTUALENV=.venv`. The user can specify
-any option and it will be passed to the plugin in that format.
+any option, and it will be passed to the plugin in that format.
 
-Currently this only supports simple strings, but we can make it compatible with more complex types
+Currently, this only supports simple strings, but we can make it compatible with more complex types
 (arrays, tables) fairly easily if there is a need for it.
 
 ## Templates
diff --git a/docs/registry.md b/docs/registry.md
diff --git a/man/man1/mise.1 b/man/man1/mise.1
diff --git a/mise.usage.kdl b/mise.usage.kdl
diff --git a/src/cli/alias/mod.rs b/src/cli/alias/mod.rs
diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts
