# Repository: jdx/mise # Stars: 26799 ## CLAUDE.md # Repository Agent Guide This file provides guidance to AI coding agents when working with code in this repository. It keeps the `CLAUDE.md` filename for compatibility with existing tooling, and `AGENTS.md` symlinks to it for other agents. ## Development Commands ### Building and Testing - `mise run build` or `mise run b` - Build the project with cargo - `target/debug/mise` - Run the built binary directly - `mise run test` or `mise run t` - Run all tests (unit + e2e) - `mise run test:unit` - Run unit tests only - `mise run test:e2e` - Run end-to-end tests only - `mise run snapshots` - Update test snapshots with `cargo insta` ### Debugging - Use `MISE_DEBUG=1` or `MISE_TRACE=1` environment variables to enable debug output (not `RUST_LOG`) ### Code Quality and Testing - `mise run lint` - Run all linting tasks - `mise run lint-fix` - Run linting and automatically fix issues - `mise run format` - Format code (part of CI task) - `mise run ci` - Run format, build, and test - `mise run test:e2e [test_filename]...` - Run specific e2e tests (use this instead of executing test files directly) - `mise --cd crates/vfox run test` - Run tests for the vfox crate - `mise --cd crates/vfox run lint` - Run linting for the vfox crate - `mise --cd crates/vfox run lint-fix` - Run linting and fix issues for the vfox crate - `mise task ls` - List all available tasks ### Documentation and Generation - `mise run render` - Generate all documentation and completions - `mise run render:usage` - Generate CLI usage documentation - `mise run render:completions` - Generate shell completions - `mise run docs` - Start documentation dev server - `mise run docs:build` - Build documentation ### Development - `mise run install-dev` - Install development version locally - `mise run clean` - Clean cargo build artifacts ## Code Architecture ### High-Level Structure Mise is a Rust CLI tool that manages development environments, tools, tasks, and environment variables. The codebase follows a modular architecture: **Core Components:** - `src/main.rs` - Entry point and CLI initialization - `src/cli/` - Command-line interface implementation with subcommands - `src/config/` - Configuration file parsing and management - `src/backend/` - Tool backend implementations (asdf, vfox, cargo, npm, etc.) - `src/toolset/` - Tool version management and installation logic - `src/task/` - Task execution system - `src/plugins/` - Plugin system for extending tool support **Key Backend Systems:** - `src/backend/asdf.rs` - ASDF plugin compatibility - `src/backend/vfox.rs` - VersionFox plugin system - `src/backend/cargo.rs` - Rust Cargo tool backend - `src/backend/npm.rs` - Node.js/npm tool backend - `src/backend/github.rs` - GitHub releases backend - `src/backend/aqua.rs` - Aqua tool registry integration **Core Tools (Built-in):** - `src/plugins/core/` - Built-in tool implementations (Node, Python, Go, Ruby, etc.) **Configuration System:** - `mise.toml` files for project configuration - `.tool-versions` files for ASDF compatibility - Environment variable management and templating - Task definition and execution ### Key Design Patterns 1. **Backend Architecture**: Tools are implemented through a unified backend interface, allowing multiple sources (ASDF plugins, vfox plugins, cargo, npm, etc.) 2. **Toolset Management**: The `Toolset` manages collections of tool versions and their installation state 3. **Configuration Layering**: Config files are loaded hierarchically from system → global → local with environment-specific overrides 4. **Task System**: Tasks can be defined in TOML files with dependencies, environment variables, and multiple execution modes ### Configuration Files - `mise.toml` - Main configuration file format - `settings.toml` - Global settings definitions (generates code/docs) - `registry/` - Tool registry mappings - `tasks.toml` - Project task definitions ### Test Structure - Unit tests within source files - E2E tests in `e2e/` directory organized by feature area (e.g., `e2e/cli/`, `e2e/backend/`) - E2E tests are bash scripts using assertion helpers from `e2e/assert.sh` (e.g., `assert`, `assert_contains`, `assert_fail`) - E2E tests do not need cleanup steps (rm, etc.) — the test harness handles that - Snapshot tests using `insta` crate for CLI output verification - Windows-specific tests in `e2e-win/` ### Build System - Rust project using Cargo with workspace for `crates/vfox` - Custom build script in `build.rs` for generating metadata - Multiple build profiles including `release` and `serious` (with LTO) - Cross-compilation support via `Cross.toml` ## Development Guidelines ### Conventional Commits (REQUIRED) All commit messages and PR titles MUST follow conventional commit format: **Format:** `(): ` **Types:** - `feat:` - New features - `fix:` - Bug fixes that affect the CLI behavior (not CI, docs, or infrastructure) - `refactor:` - Code refactoring - `docs:` - Documentation changes - `style:` - Code style/formatting (no logic changes) - `perf:` - Performance improvements - `test:` - Testing changes - `chore:` - Maintenance tasks, releases, dependency updates, CI/infrastructure changes - `security:` - Security-related changes - `registry:` - Any changes to `registry/` (no scope needed, use for both new tools and fixes) **Scopes:** - For command-specific changes, use the command name: `install`, `activate`, `use`, `exec`, etc. - For subsystem changes: `config`, `backend`, `env`, `task`, `vfox`, `python`, `github`, `release`, `completions`, `http`, `schema`, `doctor`, `shim`, `core`, `deps`, `ci` - Use `task` (not `run`) for task-related changes, even if the code lives in `src/cli/run.rs` or `src/cmd.rs` **Description Style:** - Use lowercase after the colon - Use imperative mood ("add feature" not "added feature") - Keep it concise but descriptive **Examples:** - `fix(install): resolve version mismatch for previously installed tools` - `feat(activate): add fish shell support` - `feat(vfox): add semver Lua module for version sorting` - `feat(env): add environment caching with module cacheability support` - `docs(contributing): update hk usages` - `chore: release 2026.1.6` - `chore(ci): add FORGEJO_TOKEN for API authentication` - `registry: add miller` ### Pre-commit Process 1. Run `hk install --mise` once to set up pre-commit hooks (runs `hk fix` automatically on commit) 2. Run `mise run lint-fix` and `git add` any lint fixes before committing 3. Use `mise run test:e2e [test_filename]...` for running specific e2e tests 4. Never run e2e tests by executing them directly - always use the mise task ## Deprecation Policy When deprecating a feature or backend: 1. **Immediately**: Mark as deprecated in docs (add warning banner) 2. **6 months later** (`warn_at`): Display deprecation warning in CLI using `deprecated_at!` macro from `src/output.rs` 3. **12 months after warn** (`remove_at`): `debug_assert!` in `deprecated_at!` fires, signaling the code should be removed Use mise version format for dates (e.g., `deprecated_at!("2026.10.0", "2027.10.0", "id", "message")`). If the replacement has been available for a long time, the CLI warning can start immediately (set `warn_at` to the current version). ## Important Implementation Notes ### Backend System When implementing new tool backends, follow the pattern in `src/backend/mod.rs`. Each backend must implement the `Backend` trait with methods for listing versions, installing tools, and managing tool metadata. ### Plugin Development - Core tools are implemented in `src/plugins/core/` - External plugins use ASDF or vfox compatibility layers - Plugin metadata is defined in `mise.plugin.toml` files ### Configuration Parsing The configuration system supports multiple file formats and environment-specific configs. Changes to settings require updating `settings.toml` and running `mise run render:schema`. ### Testing Strategy - E2E tests are organized by feature area (cli/, config/, backend/, etc.) - Use snapshot testing for CLI output verification - Backend-specific tests verify tool installation and version management - Slow tests (marked with `_slow` suffix) test actual tool compilation/installation ### Cross-Platform Considerations - Windows-specific implementations in files ending with `_windows.rs` - Platform-specific tool installation logic in core plugins - Shim system varies by platform (especially Windows) - we don't chmod mise e2e tests to be executable ## GitHub Interactions When posting comments on GitHub PRs or discussions, always include a note that the comment was AI-generated (e.g., "*This comment was generated by an AI coding assistant.*"). ## Documentation ### URL Structure When referencing mise documentation URLs, use the correct path structure based on the `docs/` directory layout: - **Dev tools & backends**: `mise.jdx.dev/dev-tools/backends/.html` (e.g., `mise.jdx.dev/dev-tools/backends/s3.html`) - **Configuration**: `mise.jdx.dev/configuration/...` - **Tasks**: `mise.jdx.dev/tasks/...` - **Environments**: `mise.jdx.dev/environments/...` - **CLI reference**: `mise.jdx.dev/cli/...` Do NOT use shortened paths like `mise.jdx.dev/backends/...` - always include the full path matching the `docs/` directory structure. ## README.md

mise
mise-en-place

Crates.io GitHub GitHub Workflow Status Discord

The front-end to your dev env

Getting Started • Documentation • Dev Tools • Environments • Tasks

## What is it? - Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) but for any language) it manages [dev tools](https://mise.jdx.dev/dev-tools/) like node, python, cmake, terraform, and [hundreds more](https://mise.jdx.dev/registry.html). - Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](https://mise.jdx.dev/environments/) for different project directories. - Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](https://mise.jdx.dev/tasks/) used to build and test projects. ## Demo The following demo shows how to install and use `mise` to manage multiple versions of `node` on the same system. Note that calling `which node` gives us a real path to node, not a shim. It also shows that you can use `mise` to install and many other tools such as `jq`, `terraform`, or `go`. [![demo](./docs/tapes/demo.gif)](https://mise.jdx.dev/demo.html) See [demo transcript](https://mise.jdx.dev/demo.html). ## Quickstart ### Install mise See [Getting started](https://mise.jdx.dev/getting-started.html) for more options. ```sh-session $ curl https://mise.run | sh $ ~/.local/bin/mise --version _ __ ____ ___ (_)_______ ___ ____ ____ / /___ _________ / __ `__ \/ / ___/ _ \______/ _ \/ __ \______/ __ \/ / __ `/ ___/ _ \ / / / / / / (__ ) __/_____/ __/ / / /_____/ /_/ / / /_/ / /__/ __/ /_/ /_/ /_/_/____/\___/ \___/_/ /_/ / .___/_/\__,_/\___/\___/ /_/ by @jdx 2026.4.16 macos-arm64 (2026-04-17) ``` Hook mise into your shell (pick the right one for your shell): ```sh-session # note this assumes mise is located at ~/.local/bin/mise # which is what https://mise.run does by default echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish echo '~/.local/bin/mise activate pwsh | Out-String | Invoke-Expression' >> ~/.config/powershell/Microsoft.PowerShell_profile.ps1 ``` ### Execute commands with specific tools ```sh-session $ mise exec node@26 -- node -v mise node@26.x.x ✓ installed v26.x.x ``` ### Install tools ```sh-session $ mise use --global node@26 go@1 $ node -v v26.x.x $ go version go version go1.x.x macos/arm64 ``` See [dev tools](https://mise.jdx.dev/dev-tools/) for more examples. ### Manage environment variables ```toml # mise.toml [env] SOME_VAR = "foo" ``` ```sh-session $ mise set SOME_VAR=bar $ echo $SOME_VAR bar ``` Note that `mise` can also [load `.env` files](https://mise.jdx.dev/environments/#env-directives). ### Run tasks ```toml # mise.toml [tasks.build] description = "build the project" run = "echo building..." ``` ```sh-session $ mise run build building... ``` See [tasks](https://mise.jdx.dev/tasks/) for more information. ### Example mise project Here is a combined example to give you an idea of how you can use mise to manage your a project's tools, environment, and tasks. ```toml # mise.toml [tools] terraform = "1" aws-cli = "2" [env] TF_WORKSPACE = "development" AWS_REGION = "us-west-2" AWS_PROFILE = "dev" [tasks.plan] description = "Run terraform plan with configured workspace" run = """ terraform init terraform workspace select $TF_WORKSPACE terraform plan """ [tasks.validate] description = "Validate AWS credentials and terraform config" run = """ aws sts get-caller-identity terraform validate """ [tasks.deploy] description = "Deploy infrastructure after validation" depends = ["validate", "plan"] run = "terraform apply -auto-approve" ``` Run it with: ```sh-session mise install # install tools specified in mise.toml mise run deploy ``` Find more examples in the [mise cookbook](https://mise.jdx.dev/mise-cookbook/). ## Full Documentation See [mise.jdx.dev](https://mise.jdx.dev) ## GitHub Issues & Discussions Due to the volume of issue submissions mise received, using GitHub Issues became unsustainable for the project. Instead, mise uses GitHub Discussions which provide a more community-centric platform for communication and require less management on the part of the maintainers. Please note the following discussion categories, which match how issues are often used: - [Announcements](https://github.com/jdx/mise/discussions/categories/announcements) - [Ideas](https://github.com/jdx/mise/discussions/categories/ideas): for feature requests, etc. - [Troubleshooting & Bug Reports](https://github.com/jdx/mise/discussions/categories/troubleshooting-and-bug-reports) ## Special Thanks We're grateful for Cloudflare's support through [Project Alexandria](https://www.cloudflare.com/lp/project-alexandria/). ## Contributors [![Contributors](https://contrib.rocks/image?repo=jdx/mise)](https://github.com/jdx/mise/graphs/contributors)