@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mise/references/dev-tools/packslip-verification-html.md

@@ -0,0 +1,178 @@
+Packslip Verification and Policy
+
+Packslip Verification and Policy [​](#packslip-verification-and-policy)
+
+mise uses Packslip's signed metadata to discover releases, verify publishers, and select compatible builds. This guide describes the discovery and policy rules behind the [Packslip backend](https://mise.jdx.dev/dev-tools/backends/packslip.html). For installation examples and tool options, start with that page.
+
+A **manifest** describes a release, a **bundle** contains that manifest and its signature evidence, and an **artifact** is a downloadable build named by the manifest. A **signed release list** indexes versions and can recommend or withdraw them.
+
+## Inspect the tool and accepted signers [​](#inspect-the-tool-and-accepted-signers)
+
+Before investigating a verification error, identify the backend and version in use, then inspect the signer state without changing it:
+
+sh
+
+```
+mise tool hk
+mise ls --current
+mise packslip pins
+mise packslip pins --json
+```
+
+Replace `hk` with the affected tool. The pins commands list previously accepted identities; they do not re-verify an installed executable or grant trust to a new signer. Compare the relevant project with its lockfile entry and the error before following a signer-rotation procedure.
+
+## Project discovery [​](#project-discovery)
+
+| Project form | Where mise looks |
+| --- | --- |
+| `github.com/owner/repo` | GitHub releases carrying `packslip.sigstore.json`. |
+| `github.com/owner/repo/tools/mytool` | The repository's releases, using `packslip.tools-mytool.sigstore.json`. |
+| `tool.example.com` | `https://tool.example.com/.well-known/packslip.json`. |
+| `example.com/tools/mytool` | `https://example.com/.well-known/packslip/tools/mytool.json`. |
+
+A GitHub monorepo subpath identifies one tool, but the signing identity is still pinned to the repository. The signed project and version must match the requested tool and release, regardless of the bundle's filename.
+
+For domain projects, the signed list supplies bundle URLs; artifacts may live on another download host. A domain without a signed list cannot be installed. Recognizing a forge's signing issuer does not provide release discovery: GitHub has a release-API integration; other hosts need the signed-list location.
+
+## Version resolution [​](#version-resolution)
+
+Packslip versions use semantic versioning, including compatible date versions such as `2026.9.1`. The version determines ordering and prerelease status; GitHub's release order and editable prerelease flag do not determine either.
+
+For GitHub discovery, mise reads versions from tags such as `v1.2.3`, `mytool-v1.2.3`, or `v4.1` (normalized to `4.1.0`). Tags that do not map to a version need an explicit mapping in a signed list. At installation, the manifest's version must agree with the tag or list entry.
+
+### Signed release lists [​](#signed-release-lists)
+
+A GitHub repository can publish a supplementary signed list on its default branch at `.well-known/packslip.json`, or `.well-known/packslip/<tool>.json` for a monorepo tool. The list can withdraw a version, supply a bundle URL and digest, or add a version that the release API does not expose.
+
+Omitted versions can still come from GitHub releases: omission does not withdraw them. For a domain project, the signed list supplies the entire release index. A vendor withdrawal excludes a version even if a trusted stamper approved it.
+
+### Release-list continuity and minimum age [​](#release-list-continuity-and-minimum-age)
+
+mise rejects expired signed lists and sequences below the highest it has accepted for the project. Once it has accepted a supplementary GitHub list, that list disappearing is an error. This prevents a missing list from silently undoing a withdrawal. The remembered list state is stored alongside the [signer pin](#signer-continuity).
+
+With [minimum release age](https://mise.jdx.dev/configuration/settings.html#minimum_release_age) enabled, discovery timestamps help filter candidates. Before downloading an artifact, mise checks the verified transparency-log timestamp against the effective cutoff. Only an explicitly allowed unlogged bundle uses the signed publication timestamp instead.
+
+The cutoff decides which release a fuzzy request may pick, so it does not apply to a release that was already chosen: an exact pin such as `"packslip:github.com/jdx/hk" = "2.0.1"` and a version recorded in `mise.lock` both install and lock while the release is still cooling. Fuzzy requests like `latest` or `2` stay behind the cutoff, and the `npm:` and `pipx:` backends still apply it to unpinned transitive dependencies.
+
+### Recommendations and fallback [​](#recommendations-and-fallback)
+
+For an unconstrained `latest` request, mise considers the vendor's signed recommendation first, then GitHub's latest release if there is no signed pointer. Without an eligible recommendation, mise selects the highest eligible semantic version. Prefix and channel requests keep their normal matching rules; the recommendation does not reorder them.
+
+A recommendation must pass signature, identity, digest, release-age, stamping, and host checks. A policy exclusion warns and tries another candidate. An ineligible signed recommendation falls directly back to semantic-version selection, without consulting GitHub's pointer. Signature or digest failures and invalid, expired, rolled-back, or unexpectedly missing lists stop resolution.
+
+For a stamped release, mise fetches the bundle from the stamp's URL and checks the vendor's list for withdrawals and any recorded digest. Resolution and installation use the same source and verification policy.
+
+### Caching and offline use [​](#caching-and-offline-use)
+
+Online version listing and `latest` resolution read policy afresh so withdrawals and trust changes take effect. They write the results to mise's remote-version cache. Offline, both use that cache, or return no versions if it is empty. Installation still rechecks verification policy. A cached version list alone is not sufficient for an offline install: required bundles, artifacts, and trust evidence must also be available.
+
+## Verification checks [​](#verification-checks)
+
+Before unpacking a release, mise checks:
+
+1. The bundle's signature and applicable certificate and transparency-log evidence against the expected repository identity or configured key.
+2. The manifest's structure, requested project and version, and any bundle digest recorded by a vendor list or trusted stamper.
+3. Signer continuity, lockfile commitments, and applicable release-age policy.
+4. The selected artifact's digest and size, plus any existing lockfile checksum.
+
+The verified manifest is retained as `.mise-packslip.json` in the install directory. It supplies executable paths and metadata for resources.
+
+Verification authenticates the signer and downloaded bytes. A provenance link in the manifest is separate evidence: mise records its presence for continuity checks but does not fetch and verify the linked build provenance.
+
+## Signer continuity [​](#signer-continuity)
+
+mise preserves trust in two places:
+
+| State | What it records |
+| --- | --- |
+| `packslip/pins.toml` under the [state directory](https://mise.jdx.dev/directories.html#local-state-mise) | Previously accepted signers, signing scheme, vendor versus repackager status, provenance-link presence, and release-list continuity. |
+| `mise.lock` | The project's signer and attestor commitment alongside each platform's artifact URL and checksum, including on another machine's first install. |
+
+For a keyless signer, continuity compares the workflow path without its tag or branch ref. A new release tag of the same workflow is the same signer. A new workflow path or key requires an explicit trust decision. A signing-scheme change, a vendor-to-repackager change, or lost provenance links can also be refused.
+
+Deleting `pins.toml` resets local continuity for every recorded project. It is not a routine remedy for an installation failure, and it does not remove signer commitments from a project lockfile.
+
+See [signer changes](https://mise.jdx.dev/dev-tools/backends/packslip.html#pinned-signers) for inspection and reset commands, including how explicit options and lockfile commitments affect a rotation.
+
+## Stamps [​](#stamps)
+
+A stamper is a registry, mirror, or review service that publishes a signed list of releases it approves. No stamps are required by default. To require them, configure the hosts you trust and the key or identity allowed to sign each host's lists:
+
+toml
+
+```
+[settings.packslip]
+stampers = [
+  "stamps.example.com=/path/to/stamper.pub",
+  "reviews.example.com=https://github.com/example/reviews/",
+]
+```
+
+Each entry is `host=PIN`. The pin may be a minisign-format public-key line, a public-key file path, or a GitHub identity prefix. Replace the example hosts and key path with a service and pin you trust.
+
+A host publishes one list per project at `https://<host>/.well-known/packslip/<project>.json`. With stampers configured:
+
+- A version needs a non-yanked approval from at least one trusted host to be listed or installed. One host's withdrawal does not veto another's approval.
+- A vendor withdrawal still excludes the release, regardless of stamps.
+- mise checks the stamped bundle digest and the vendor-list digest, when present, then verifies the vendor signature. A stamp never replaces that signature.
+- A stamp without a digest is refused: the approval must identify the bundle's contents, not just its URL.
+- Expired, rolled-back, invalid, or previously accepted but now missing stamper lists cause errors.
+
+To exempt one tool while retaining vendor verification, set its [`trust = "vendor"`](https://mise.jdx.dev/dev-tools/backends/packslip.html#trust) tool option.
+
+### Mirrors [​](#mirrors)
+
+A stamper can mirror the exact vendor-signed bundle. mise fetches it from the stamp's URL and checks the vendor's list for withdrawals and any recorded digest. Deleting a GitHub release asset does not block an approved mirror of a release that the vendor has not withdrawn. Re-signed repackager bundles requiring a separate identity policy are not supported here.
+
+## Interpreting policy failures [​](#interpreting-policy-failures)
+
+| Failure | Next step |
+| --- | --- |
+| Signer or signing scheme changed | Compare the old pin and lockfile commitment with the publisher's announced rotation |
+| Signed list expired, rolled back, or disappeared | Check the publisher or stamper's current list; removing local state would discard the continuity check |
+| Release withdrawn or lacks a required stamp | Select a release allowed by the configured policy |
+| Bundle or artifact digest mismatch | Check the release source or mirror; do not accept new bytes merely to clear the error |
+| No matching artifact or unresolved tie | Check the platform and variant, or ask the publisher to distinguish its builds |
+| Host requirement failed | Install the requirement or use a supported host; bypassing the check does not supply it |
+
+The errors identify different stages. Changing an artifact option cannot repair an invalid signature, and forgetting a signer pin cannot repair a digest mismatch.
+
+## Artifact selection [​](#artifact-selection)
+
+mise uses signed metadata to select one artifact:
+
+1. Match OS, architecture, and libc. An absent field leaves only that dimension unrestricted: a universal macOS build still requires macOS.
+2. With a `variant`, consider only that variant. Without one, consider only artifacts that have no variant.
+3. Keep formats mise can install, preferring the most specific platform match, then its archive/compression format preference over a bare executable.
+4. Refuse an unresolved tie rather than guessing between builds.
+
+Installer formats such as `deb`, `dmg`, and `msi` are not selected. A glibc host may use a matching static musl artifact when there is no GNU artifact, or when the selected GNU artifact declares a `glibc_min` above the host's detected version. mise reports that fallback in the debug log. The publisher must distinguish alternative builds with variants. A client option cannot resolve two identically described artifacts.
+
+## Host requirements [​](#host-requirements)
+
+After selecting an artifact, mise checks its declared requirements before downloading it. Requirements do not break a selection tie. A confirmed `glibc_min` incompatibility may select the matching static musl build as described above; other requirements do not select another build.
+
+| Requirement result | mise behavior |
+| --- | --- |
+| Insufficient glibc with a matching static musl artifact | Select the musl artifact. |
+| Confirmed missing library, insufficient glibc without a fallback, or insufficient OS version | Refuse installation. |
+| Missing or outdated required command | Warn and continue. |
+| A check cannot be completed | Warn instead of assuming the host is incompatible. |
+
+Command checks prefer active mise tools over ambient PATH. mise checks for a path the OS can execute: on Windows, `git.exe` or `node.cmd` counts, but a shebang-only script does not.
+
+Library detection is platform-dependent. For example, an absent macOS library file may still exist in the dyld shared cache, so mise reports that absence as unknown. On Linux, the OS version is the kernel release from `uname -r`, read up to the distribution's suffix: `6.8.0-31-generic` is compared as `6.8.0`.
+
+The [`ignore_requirements`](https://mise.jdx.dev/dev-tools/backends/packslip.html#ignore-requirements) tool option permits installation despite confirmed failures. It also bypasses the glibc-to-musl fallback and retains the selected GNU artifact. It does not supply missing libraries or make an incompatible executable run.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/packslip-verification.md)
+
+Last updated:
+
+Pager
+
+[Previous pagePackslip Man Pages, Completions, and Skills](https://mise.jdx.dev/dev-tools/packslip-resources.html)
+
+[Next pageOCI Images (experimental)](https://mise.jdx.dev/dev-tools/mise-oci.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/shims-html.md

@@ -0,0 +1,397 @@
+Shims
+
+Shims [​](#shims)
+
+There are several ways to load the `mise` context (dev tools, environment variables) into your shell:
+
+- `mise activate` (also called ["mise PATH activation"](#path-activation)), where `mise` updates your `PATH` and other environment variables every time your prompt is displayed.
+- [`mise activate --shims`](#mise-activate-shims), which uses shims to load dev tools.
+- Using [`mise x|exec`](https://mise.jdx.dev/cli/exec.html) or [`mise r|run`](https://mise.jdx.dev/cli/run.html) for ad-hoc commands or tasks (see ["neither shims nor PATH"](#neither-shims-nor-path)).
+
+This page explains the differences between these methods and how to use them. In particular, it will help you decide whether to use shims or `mise activate` in your shell.
+
+## Overview of the `mise` activation methods [​](#overview)
+
+### PATH activation [​](#path-activation)
+
+mise's "PATH" activation method updates environment variables every time the prompt is displayed. In particular, it updates the `PATH` environment variable, which your shell uses to search for the programs it can run.
+
+INFO
+
+For Bash, add `eval "$(mise activate bash)"` to `~/.bashrc`. Run an `echo ... >> ~/.bashrc` setup command in your terminal only once; do not put that append command in the startup file itself.
+
+For example, by default, your `PATH` variable might look like this:
+
+sh
+
+```
+echo "$PATH"
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+With [`mise activate`](https://mise.jdx.dev/cli/activate.html), `mise` automatically adds the required tools to `PATH`.
+
+sh
+
+```
+PATH="$HOME/.local/share/mise/installs/python/3.14.7/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+```
+
+In this example, the python `bin` directory was added at the beginning of `PATH`, making it available in the current shell session. When a fuzzy version like `python = "3.14"` or `node = "26"` is active, this path may use the requested-version symlink, such as `~/.local/share/mise/installs/python/3.14/bin`, instead of the fully resolved patch version.
+
+Use shims when a program needs a stable path to a tool, such as an IDE configured with a Python executable. For scripts, `mise exec -- <command>` loads both tools and environment variables explicitly.
+
+### Shims [​](#mise-activate-shims)
+
+WARNING
+
+`mise activate --shims` does not support all the features of `mise activate`.  
+ See [shims vs path](https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path) for more information.
+
+When using shims, `mise` places small executables (`shims`) in a directory that is included in your `PATH`. You can think of `shims` as symlinks to the mise binary that intercept commands and load the appropriate context.
+
+sh
+
+```
+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` (on Windows: `%LOCALAPPDATA%\mise\shims`). When you install a tool (for example, `node`), `mise` adds an entry to the `shims` directory for every binary the tool provides (for example, `~/.local/share/mise/shims/node`).
+
+sh
+
+```
+mise use node@24 npm:prettier@3
+
+~/.local/share/mise/shims/node --version
+~/.local/share/mise/shims/prettier --version
+```
+
+These commands use the versions selected for the current directory. The paths above assume the default Unix data directory. To find shims by command name, add their directory to the existing `PATH`:
+
+sh
+
+```
+export PATH="$HOME/.local/share/mise/shims:$PATH"
+```
+
+Child processes inherit this `PATH`. Independently launched applications, CI jobs, and other shells need their own environment setup; editing one shell's profile does not configure every process on the machine.
+
+## Lazy tools [​](#lazy-tools)
+
+Set `lazy = true` on a tool when it should be installed the first time one of its commands is invoked instead of by a bare `mise install`:
+
+toml
+
+```
+[tools]
+node = { version = "24", lazy = true }
+```
+
+For registry shorthands, mise creates bootstrap shims from the registry's `bins` metadata. Explicit backends and tools that are not in the registry must declare their command names with `lazy_bins`:
+
+toml
+
+```
+[tools]
+"github:example/acme" = { version = "1.2.3", lazy = true, lazy_bins = ["acme", "acmectl"] }
+```
+
+Run `mise reshim` after editing a lazy declaration directly. Commands such as `mise use` that update tool configuration rebuild the shim farm automatically. Invoking a lazy shim installs its configured provider, plus any configured tools that provider [depends](https://mise.jdx.dev/dev-tools/#tool-dependencies) on that are not installed yet, and then executes it. Nothing else in the toolset is installed. This is independent of `not_found_auto_install`; an explicit project tool selection is never bypassed by a lower-precedence lazy declaration.
+
+A bare `mise install` skips missing lazy tools. Pass `--include-lazy` to install all configured tools, including lazy declarations, or name one explicitly, such as `mise install node`, to install only that lazy tool immediately. Once installed, normal `mise activate` places the real tool path ahead of the shim farms, so later calls have no shim dispatch overhead. `mise activate --shims` remains project-aware and dispatches every call through mise by design.
+
+Tasks and `mise x` work the same way. `mise run` does not preinstall lazy tools. Instead, whenever the toolset has a lazy declaration, the environment mise builds for a task (and for `mise x` and `mise env`) places the shim farms behind the tool paths if they are not already on PATH, and any missing bootstrap shims are created first. The task installs the tool the first time it runs one of its commands. `mise x -- <command>` installs the provider of a lazy command directly.
+
+TIP
+
+[`mise activate --shims`](https://mise.jdx.dev/cli/activate.html#flags) is a shorthand for adding the shims directory to PATH.
+
+## How to add mise shims to PATH [​](#how-to-add-mise-shims-to-path)
+
+Use `mise activate --shims` when `mise` itself is already on `PATH`. Add the following lines to the indicated files, preserving existing setup. Bash and Zsh profiles run for **login shells**; they are not startup files for arbitrary non-interactive scripts.
+
+Bash: \~/.bash\_profileBash: \~/.bashrcZsh: \~/.zprofileZsh: \~/.zshrcFish: \~/.config/fish/config.fish
+
+sh
+
+```
+# Use ~/.profile instead if that is your existing login startup file.
+eval "$(mise activate bash --shims)"
+```
+
+sh
+
+```
+eval "$(mise activate bash)"
+```
+
+sh
+
+```
+eval "$(mise activate zsh --shims)"
+```
+
+sh
+
+```
+eval "$(mise activate zsh)"
+```
+
+fish
+
+```
+if status is-interactive
+    mise activate fish | source
+else
+    mise activate fish --shims | source
+end
+```
+
+Bash login shells read the first available file among `~/.bash_profile`, `~/.bash_login`, and `~/.profile`. They read `~/.bashrc` only if the profile sources it. Check your existing startup files before adding a new profile that would hide the old one. Zsh reads `~/.zprofile` for login shells and `~/.zshrc` for interactive shells.
+
+For a script or CI command, prefer `mise exec -- <command>`. A script launched from an already configured shell inherits its `PATH`, but a scheduler or IDE may not inherit that shell's environment. See [IDE integration](https://mise.jdx.dev/ide-integration.html) and [Windows setup](https://mise.jdx.dev/installing-mise.html#windows-scoop) for those environments.
+
+INFO
+
+It's fine to call [`mise activate --shims`](https://mise.jdx.dev/cli/activate.html#flags) in your shell profile file and then later call [`mise activate`](https://mise.jdx.dev/cli/activate.html) in an interactive session. PATH activation keeps the user and existing system shim farms behind real tool paths when the effective toolset contains a lazy declaration or `not_found_auto_install` is enabled. Without either, full activation removes the shim farms as before. This makes lazy bootstrap commands available without adding dispatch overhead after installation. `not_found_auto_install` still controls general missing-tool installation, but does not disable an explicit `lazy = true` declaration.
+
+To explicitly keep tool shims out of full shell activation, including when auto-install or lazy tools are enabled, run `mise settings set activate_shims false` and restart your shell. See [`activate_shims`](https://mise.jdx.dev/configuration/settings.html#activate_shims) for the tradeoffs. Shims serve several purposes: installing missing configured versions, bootstrapping lazy tools, and dispatching configured command wrappers. Wrappers such as `cargo` through [mr-boxington](https://github.com/jdx/mr-boxington) use their own `command-wrappers/bin` directory, which remains active with this setting disabled. Explicit `mise activate --shims` also continues to work.
+
+INFO
+
+When a shim cannot resolve a mise-managed tool (for example, a version pinned in `mise.toml` that hasn't been installed and [`not_found_auto_install`](https://mise.jdx.dev/configuration/settings.html#not_found_auto_install) is disabled), it falls back to the first same-named executable found elsewhere on `PATH` rather than erroring. This is convenient for tools you also want available outside of mise, but for a tool the OS also ships (`python3` on Debian/Ubuntu, for example) it means the shim can silently run a completely different, unrelated binary instead of failing loudly.
+
+Set [`not_found_system_fallback`](https://mise.jdx.dev/configuration/settings.html#not_found_system_fallback) to `false`, alongside `not_found_auto_install = false`, if you'd rather an unresolvable shim fail outright.
+
+### Excluding command names [​](#excluding-command-names)
+
+Some commands are also provided by the OS, and other software on the machine depends on getting the system one. [`shims.exclude`](https://mise.jdx.dev/configuration/settings.html#shims.exclude) keeps those names out of the shim directory — mise still installs and manages the tool, it just never generates a shim for that name:
+
+toml
+
+```
+[settings.shims]
+exclude = ["python", "python3", "pip", "pip3"]
+```
+
+On Arch Linux, for example, `/usr/bin/python` is the distro interpreter and its modules live in a matching `site-packages` directory. Without this setting, entering a project that pins `python` changes which interpreter a `#!/usr/bin/env python` script gets, and a `PKGBUILD` that calls `python` during a build picks up the pinned version rather than the system one.
+
+Excluded names are removed from the shim directory on the next `mise reshim`, and are skipped by the other shim producers too: lazy-tool bootstrap shims and plugin-provided shims. Version-qualified shims are unaffected, so `python3.12` still resolves to whatever version a config selects. Because no shim exists, mise is out of that command's execution path and no longer loads configuration on each invocation of it.
+
+WARNING
+
+Excluding `python3` means `python3 -m venv` builds a virtualenv from the system interpreter rather than the configured one, silently. Use the version-qualified command (`python3.12 -m venv`) when you want the mise-managed version.
+
+This setting only affects generated shims. Under `mise activate` without `--shims`, a tool's `bin` directory joins `PATH` as a whole, so excluded names remain visible there.
+
+- You can also decide to use only `shims` if you prefer, though this comes with some [limitations](https://mise.jdx.dev/dev-tools/shims.html#shims-vs-path).
+- An alternative to [`mise activate --shims`](https://mise.jdx.dev/cli/activate.html#flags) is to use `export PATH="$HOME/.local/share/mise/shims:$PATH"`. This can be helpful if `mise` is not yet available at that point.
+
+### mise reshim [​](#mise-reshim)
+
+To force `mise` to update the contents of the `shims` directory, run `mise reshim`.
+
+Use `mise reshim --system` for the system shim farm. If `shims_dir` and `system_shims_dir` resolve to the same physical path, either command reconciles one combined farm containing both scopes.
+
+mise rebuilds shims when it installs, updates, or removes a tool. If another package manager adds executables inside an existing installation, run `mise reshim`. The Node.js core plugin can do this after `npm install -g` through its [`node.npm_shim`](https://mise.jdx.dev/configuration/settings.html#node.npm_shim) wrapper; this is not a general hook for every package manager.
+
+`mise reshim` only creates and removes shims. Some users treat it as a "fix it" button, but it is only necessary when `~/.local/share/mise/shims` doesn't contain something it should.
+
+For `mise reshim`, the configured shim directory may be a shared executable directory such as `~/.local/bin` or `/usr/local/bin`: reshim only replaces or removes entries it recognizes as mise shims, and leaves a same-named unmanaged file in place. Other mise features still identify shim directories as whole `PATH` entries, however, so a shared directory is not yet supported with `mise activate`, hook-env, or internal dependency lookups. Use a dedicated `shims_dir` if you use those features.
+
+## Command wrappers [​](#command-wrappers)
+
+Use `[wrappers]` when a command should always pass through another program while keeping its ordinary name. For example, this routes every `cargo` invocation through [Mr Boxington](https://github.com/jdx/mr-boxington):
+
+toml
+
+```
+[tools]
+mr-boxington = "1.4.1"
+
+[wrappers.cargo]
+command = "mbx"
+env = { MBX_CARGO_SHIM_MODE = "1" }
+```
+
+Run `mise reshim` after adding or removing a wrapper. The wrapper is available with both `mise activate` and `mise activate --shims`, and takes precedence over an executable with the same name. When it delegates, mise removes its dispatch directories from `PATH`, so `mbx` resolves Cargo from mise-managed Rust when configured and otherwise falls through to rustup or the system installation.
+
+A short form is available when no arguments or environment variables are needed:
+
+toml
+
+```
+[wrappers]
+terraform = "tofu"
+```
+
+The detailed form can insert arguments before those supplied by the user:
+
+toml
+
+```
+[wrappers.python]
+command = "uv"
+args = ["run", "python"]
+```
+
+## Shims vs PATH [​](#shims-vs-path)
+
+The following features are affected when shims are used **instead** of [PATH activation](#path-activation):
+
+- [Env vars](https://mise.jdx.dev/environments/) defined in mise are only available to mise tools
+- Most [hooks](https://mise.jdx.dev/hooks.html) won't trigger
+- The Unix `which` command points to the shim, obscuring the real executable
+
+In general, PATH activation (`mise activate`) is recommended over shims for *interactive* situations.
+
+With `activate`, every time the prompt is displayed, mise determines what `PATH` and other env vars should be and exports them. This is why it doesn't work well for non-interactive situations like scripts: the prompt is never displayed, so you have to call `mise hook-env` manually to get mise to update the env vars (though there are exceptions; see [hook on `cd`](#hook-on-cd)).
+
+### Env vars and shims [​](#env-vars-and-shims)
+
+A downside of shims is that environment variables are only loaded when a shim is called. This means that if you set an [environment variable](https://mise.jdx.dev/environments/) in `mise.toml`, it is only applied when a shim is called.
+
+The following example only works under `mise activate`:
+
+sh
+
+```
+$ mise set NODE_ENV=production
+$ echo $NODE_ENV
+production
+```
+
+But this works with either:
+
+sh
+
+```
+$ mise set NODE_ENV=production
+$ node -p process.env.NODE_ENV
+production
+```
+
+You can also use [`mise x|exec`](https://mise.jdx.dev/cli/exec.html) and [`mise r|run`](https://mise.jdx.dev/cli/run.html) to load the environment even if you don't need any mise tools:
+
+sh
+
+```
+$ mise set NODE_ENV=production
+$ mise x -- bash -c "echo \$NODE_ENV"
+production
+$ mise r some_task_that_uses_NODE_ENV
+production
+```
+
+TIP
+
+In general, [tasks](https://mise.jdx.dev/tasks/) are a good way to ensure that the mise environment is always loaded.
+
+### Hooks and shims [​](#hooks-and-shims)
+
+The [hooks](https://mise.jdx.dev/hooks.html) `cd`, `enter`, and `leave` only trigger with `mise activate`. The separate [`watch_files`](https://mise.jdx.dev/hooks.html#watch-files-hook) configuration also requires `mise activate`. However, `preinstall` and `postinstall` still work with shims because they don't require shell integration.
+
+### `which` [​](#which)
+
+Many users find `which` valuable. Shims effectively "break" `which`, causing it to show the location of the shim. A workaround is `mise which`, which shows the actual location. Some users prefer the "cleanliness" of running `which node` and getting back a real path with a version number in it, e.g.:
+
+sh
+
+```
+$ which node
+~/.local/share/mise/installs/node/24/bin/node
+```
+
+### Performance [​](#performance)
+
+PATH activation does its work at prompts and supported directory-change hooks. Shims resolve the environment when a command is invoked. Which costs less depends on how you run commands.
+
+For example, a script that repeatedly calls a shim resolves the environment on each call:
+
+bash
+
+```
+for i in {1..500}; do
+    node script.js
+done
+```
+
+Run the enclosing script with `mise exec -- bash benchmark.sh` to prepare the environment once. Child processes then inherit the real tool directories ahead of the shim directory. Similarly, a process launched by a shim passes the resolved environment to its children.
+
+See [slow shell prompts](https://mise.jdx.dev/troubleshooting.html#slow-shell-prompts) to diagnose activation overhead. Hook behavior and parent-shell environment updates also differ, so choose an activation method based on those requirements as well as performance.
+
+## Neither shims nor PATH [​](#neither-shims-nor-path)
+
+[`mise exec`](https://mise.jdx.dev/cli/exec.html), [`mise run`](https://mise.jdx.dev/cli/run.html), and [`mise en`](https://mise.jdx.dev/cli/en.html) load tools and environment variables explicitly:
+
+sh
+
+```
+mise exec -- node --version
+mise run build
+```
+
+The second command requires a task named `build`. This approach works for CI, scripts, and projects where you do not want to change shell startup files. It requires `mise` on `PATH`, but no shell activation or shim directory.
+
+## Hook on `cd` [​](#hook-on-cd)
+
+For some shells (`bash`, `zsh`, `fish`, `xonsh`), `mise` hooks into the `cd` command, while in others, it only runs when the prompt is displayed. This relies on `chpwd` in `zsh`, a `chpwd` emulation (wrapping `cd`/`pushd`/`popd`) plus `PROMPT_COMMAND` in `bash`, `fish_prompt` in `fish`, and `on_chdir` in `xonsh`.
+
+Directory-change hooks let those shells apply the new project environment before the next command, even if no prompt has appeared yet.
+
+<details>
+
+<summary>Running several commands in a single line</summary>
+
+
+
+If you run a set of commands in a single line like the following:
+
+sh
+
+```
+cd ~
+cd ~/src/proj1 && node -v && cd ~/src/proj2 && node -v
+```
+
+With <code>mise activate</code> in a shell without a <code>cd</code> hook, this uses the tools from <code>~</code>, not from <code>~/src/proj1</code> or <code>~/src/proj2</code>, even after the directory changes.
+
+This is because in these shells <code>mise</code> runs just before your prompt is displayed, whereas in others it hooks into <code>cd</code>. Shims *will* always work with the inline example above.
+
+</details>
+
+## Using mise in rc files [​](#using-mise-in-rc-files)
+
+rc files like `.zshrc` are unusual: they are scripts, but they run only for interactive sessions. If you need to access tools provided by mise inside an rc file, you have two options:
+
+hook-envshims
+
+sh
+
+```
+eval "$(mise activate zsh)"
+eval "$(mise hook-env -s zsh)"
+node some_script.js
+```
+
+sh
+
+```
+eval "$(mise activate zsh --shims)" # should be first
+eval "$(mise activate zsh)"
+node some_script.js
+```
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/shims.md)
+
+Last updated:
+
+Pager
+
+[Previous pageComparison to asdf](https://mise.jdx.dev/dev-tools/comparison-to-asdf.html)
+
+[Next pageTool Aliases](https://mise.jdx.dev/dev-tools/aliases.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)