aussiegingersnap/mise

Mise Comprehensive Skill

Table of Contents

• STRICT ENFORCEMENT: Usage Field Required
• Overview
• Task Definition Methods
• Task Arguments - Usage Spec Reference
  • Positional Arguments (arg)
  • Flags (flag)
  • Custom Completions (complete)
  • Accessing Arguments in Scripts
  • File Task Headers
• Task Configuration Reference
  • All Task Fields
  • Structured run Array
  • Structured depends with Args/Env
  • Task Inheritance (extends)
  • Global Task Configuration
  • Variables (vars)
• Running Tasks (CLI)
• Task Dependencies and Caching
• Dev Tools Management
  • Backends Overview
  • TOML Syntax for Tools
  • Per-Tool Options
  • Backend-Specific Configuration
  • Shims and Aliases
• Environment Configuration
  • Basic Variables
  • Special Directives (env._)
  • Profiles (MISE_ENV)
  • Required and Redacted Variables
  • Templates (Tera)
• Hooks and Watchers
• Configuration and Settings
  • File Hierarchy
  • Key Settings Reference
• Prepare Feature (Experimental)
• Monorepo Tasks (Experimental)
• Best Practices

---

STRICT ENFORCEMENT: Usage Field Required

This skill WILL NOT generate tasks with shell-native argument handling.

All task arguments MUST be defined using the usage field. This is non-negotiable.

REQUIRED Pattern

[tasks.deploy]
description = "Deploy to environment"
usage = 'arg "<env>" help="Target environment" choices "dev" "staging" "prod"'
run = 'deploy.sh ${usage_env?}'

#!/usr/bin/env bash
#MISE description="Process files"
#USAGE arg "<input>" help="Input file"
#USAGE arg "[output]" default="out.txt" help="Output file"
echo "Processing ${usage_input?} -> ${usage_output:-out.txt}"

BLOCKED Patterns

# BLOCKED: Bash positional arguments
[tasks.bad]
run = 'deploy.sh $1 $2'

# BLOCKED: Bash special variables
[tasks.also_bad]
run = 'process.sh "$@"'

# BLOCKED: Inline Tera templates (deprecated, removed 2026.11)
[tasks.deprecated]
run = 'echo {{arg(name="x")}}'

Why This is Enforced

| Benefit | Description | |---------|-------------| | Type Safety | Arguments validated before execution | | Auto-completion | Shell completions generated automatically | | Cross-platform | Works on bash, zsh, fish, PowerShell | | Self-documenting | mise run --help shows all options | | No Parsing Bugs | Eliminates shell quoting/escaping issues | | Choices Validation | Invalid values rejected immediately |

---

Overview

mise is an all-in-one developer environment tool that manages:

• Dev tools - install and manage language runtimes, CLIs, and build tools (18 backends)
• Tasks - project-specific commands with argument handling, dependencies, caching
• Environments - manage env vars, profiles, dotenv files, secrets
• Hooks - run commands on directory changes, project enter/leave, tool install

Key Features:

• Parallel dependency building (concurrent by default)
• Last-modified and content-hash checking (avoid unnecessary rebuilds)
• File watching (mise watch rebuilds on changes)
• Cross-platform argument handling via usage spec
• Hierarchical configuration with profile support
• 18 tool backends (aqua, github, npm, cargo, pipx, go, etc.)

---

Task Definition Methods

TOML-Based Tasks (in mise.toml)

Simple Tasks

[tasks]
build = "cargo build"
test = "cargo test"
lint = "cargo clippy"

Detailed Tasks

[tasks.build]
description = "Build the CLI"
run = "cargo build"

[tasks.test]
description = "Run tests"
depends = ["build"]
run = "cargo test"

File-Based Tasks (executable scripts)

Place in mise-tasks/ or .mise/tasks/ directory. Files must be executable (chmod +x).

#!/usr/bin/env bash
#MISE description="Build the CLI"
#MISE depends=["lint"]
cargo build

Supported directories:

• mise-tasks/
• .mise-tasks/
• mise/tasks/
• .mise/tasks/
• .config/mise/tasks/

File tasks use #MISE or #USAGE comment headers for configuration.

Alternative header syntax (if formatters modify #MISE):

# [MISE] description="Build"
# [MISE] depends=["lint"]

Task Grouping (Namespaces)

Subdirectories create namespaced tasks:

mise-tasks/
├── test/
│   ├── unit          → test:unit
│   ├── integration   → test:integration
│   └── e2e           → test:e2e
└── lint/
    ├── eslint        → lint:eslint
    └── prettier      → lint:prettier

Remote Tasks

Fetch tasks from external sources:

[tasks.build]
file = "https://example.com/build.sh"

[tasks.release]
file = "git::https://github.com/org/repo.git//scripts/release.sh?ref=v1.0.0"

Remote files are cached in MISE_CACHE_DIR.

---

Task Arguments - Usage Spec Reference

REMINDER: Always use the usage field. Never use $1, $@, or shell-native argument handling.

The usage field uses KDL-inspired syntax to define arguments, flags, and completions.

Positional Arguments (arg)

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | (name) | string | required | "<name>" = required, "[name]" = optional. "<file>" triggers file completion, "<dir>" triggers dir completion. | | help | string | none | Short help text shown with -h | | long_help | string | none | Extended help text shown with --help | | default | string | none | Default value if not provided. default="" sets to empty string (different from unset). | | env | string | none | Environment variable that can provide this arg's value. Priority: CLI > env > default. | | var | boolean | #false | Variadic mode (accept multiple values). "<name>" requires 1+, "[name]" accepts 0+. | | var_min | integer | none | Minimum values when variadic | | var_max | integer | none | Maximum values when variadic | | choices | values | none | Restrict to enumerated set | | double_dash | string | none | "required", "optional", "automatic", "preserve" | | hide | boolean | #false | Exclude from help output |

Examples:

arg "<file>" help="Input file to process"
arg "[output]" default="out.txt" help="Output file"
arg "<files>" var=#true var_min=1 help="One or more files"
arg "<env>" choices "dev" "staging" "prod" help="Target environment"
arg "<args>..." double_dash="automatic" help="Pass-through arguments"

Variadic args in bash:

# Values are shell-escaped string in usage_files
eval "files=($usage_files)"
for f in "${files[@]}"; do
  echo "Processing: $f"
done

Flags (flag)

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | (definition) | string | required | "-s --long" (boolean) or "-s --long <value>" (with value). Short flag optional. | | help | string | none | Short help text | | long_help | string | none | Extended help for --help | | default | string/bool | none | Default value. Boolean flags use #true/#false. | | env | string | none | Environment variable backing the flag | | global | boolean | #false | Available on all subcommands | | count | boolean | #false | Value = number of times used (e.g., -vvv = 3) | | var | boolean | #false | Flag repeatable, collecting values | | var_min | integer | none | Min values when var=#true | | var_max | integer | none | Max values when var=#true | | negate | string | none | Negative form (e.g., "--no-color"). Sets env var to false. | | choices | block | none | Restrict values to enumerated set | | hide | boolean | #false | Exclude from docs/completions | | required_if | string | none | Required if named flag is set | | required_unless | string | none | Required unless named flag is present | | overrides | string | none | If set, named flag's value is ignored |

Examples:

flag "-v --verbose" help="Enable verbose output"
flag "-f --force" help="Skip confirmation prompts"
flag "--port <port>" default="8080" help="Server port"
flag "--color" negate="--no-color" default=#true help="Enable colors"
flag "-d --debug" count=#true help="Debug level (-ddd for max)"
flag "--include <pattern>" var=#true help="Include patterns (repeatable)"
flag "--shell <shell>" { choices "bash" "zsh" "fish" }
flag "--file <file>" required_if="--dir" help="Required if --dir is set"

Count flags: -vvv sets $usage_verbose to 3. Short flags chain: -abc = -a -b -c.

Negate flags: flag "--color" negate="--no-color" default=#true — --no-color sets $usage_color to false.

Custom Completions (complete)

Provide dynamic tab-completion for arguments. Preferred over choices when values change.

complete "<arg_name>" run="<shell command outputting one value per line>"

Key rules:

• Must appear after the arg it applies to
• Names must match exactly
• Do not combine with choices on the same arg

Examples:

usage = '''
arg "<service>" help="Service name"
complete "service" run="ls -d infrastructure/*/application 2>/dev/null | sed 's|infrastructure/||;s|/application||'"
arg "<environment>" help="Target environment"
complete "environment" run="ls infrastructure/${usage_service}/application/env/ 2>/dev/null | sed 's/.tfvars//'"
'''

With descriptions:

complete "plugin" run="mise plugins ls" descriptions=#true

Output format: value:description per line.

choices vs complete:

| Feature | choices | complete | |---------|-----------|------------| | Values | Hardcoded in spec | Dynamic from command | | Validation | Rejects invalid input | Tab-completion only | | Maintenance | Must edit to add options | Auto-discovers new options | | Best for | Stable enums (yes/no, log levels) | File/directory-derived values |

Accessing Arguments in Scripts

Environment variables (prefixed with usage_):

| Definition | Environment Variable | |------------|---------------------| | arg "<file>" | $usage_file | | arg "[output]" | $usage_output | | flag "-v --verbose" | $usage_verbose | | flag "--dry-run" | $usage_dry_run | | flag "-o --output <file>" | $usage_output |

Naming rules: usage_ prefix, hyphens to underscores, lowercase, long name used.

Bash variable expansion patterns:

| Pattern | Use Case | |---------|----------| | ${var?} | Required args - fail if missing | | ${var:-default} | Optional with fallback | | ${var:?msg} | Required with custom error | | ${var:+value} | Conditional (if set, use value) |

Values by type:

| Type | Present | Absent | |------|---------|--------| | Boolean flag | "true" | unset (or "false" with default=#false) | | Count flag | "1", "2", etc. | "0" | | Value flag/arg | the string value | unset or default | | Variadic | shell-escaped space-separated | unset or empty |

Critical distinction: default="" makes variable SET to empty string. No default + not provided = UNSET.

# Required arg - error if not provided
echo "Deploying to ${usage_environment?}"

# Optional with default
clean="${usage_clean:-false}"

# Conditional flag forwarding
docker build ${usage_verbose:+--verbose} .

# Boolean flag check
if [ -n "${usage_dry_run:-}" ]; then
  echo "Dry run mode"
fi

# Variadic to array
eval "files=($usage_files)"

File Task Headers

#!/usr/bin/env bash
#MISE description="Deploy application"
#USAGE arg "<environment>" help="Environment" {
#USAGE   choices "dev" "prod"
#USAGE }
#USAGE flag "-f --force" help="Skip confirmation"

echo "Deploying to ${usage_environment?}"

Supported shebangs: bash, node, python, deno, pwsh, fish, zsh.

---

Task Configuration Reference

All Task Fields

Core Execution

| Field | Type | Default | Description | |-------|------|---------|-------------| | run | string \| string[] \| object[] | — | Command(s) to execute. Supports structured array (see below). | | run_windows | same as run | — | Windows-specific override | | file | string | — | External script path (local, HTTP, or Git URL) | | shell | string | — | Interpreter (e.g., "bash -c", "node -e") | | usage | string | — | Usage spec for arguments/flags |

Metadata

| Field | Type | Default | Description | |-------|------|---------|-------------| | description | string | — | Task help text | | alias | string \| string[] | — | Alternative name(s) | | hide | bool | false | Exclude from listings |

Dependencies

| Field | Type | Default | Description | |-------|------|---------|-------------| | depends | string \| string[] \| object[] | — | Tasks to run BEFORE (supports structured objects) | | depends_post | string \| string[] \| object[] | — | Tasks to run AFTER | | wait_for | string \| string[] \| object[] | — | Wait for tasks without adding as deps |

Environment & Tools

| Field | Type | Default | Description | |-------|------|---------|-------------| | env | table | — | Task-specific env vars (NOT passed to depends). Supports age-encrypted values. | | tools | table | — | Tools to install before running |

Execution Context

| Field | Type | Default | Description | |-------|------|---------|-------------| | dir | string | {{config_root}} | Working directory. Use {{cwd}} for user's cwd. | | raw | bool | false | Direct stdin/stdout connection (disables parallel execution) |

Output Control

| Field | Type | Default | Description | |-------|------|---------|-------------| | quiet | bool | false | Suppress mise output | | silent | bool \| "stdout" \| "stderr" | false | Suppress all/specific output |

Caching

| Field | Type | Default | Description | |-------|------|---------|-------------| | sources | string \| string[] | — | Input files (glob patterns) | | outputs | string \| string[] \| {auto: true} | — | Generated files. Use {auto = true} for implicit tracking. |

Safety

| Field | Type | Default | Description | |-------|------|---------|-------------| | confirm | string | — | Prompt before running. Supports Tera templates with usage.*. |

Timeout & Inheritance

| Field | Type | Default | Description | |-------|------|---------|-------------| | timeout | string | — | Max execution duration (e.g., "30s", "5m"). Overrides global task_timeout. | | extends | string | — | Template task to inherit configuration from. |

Structured run Array

Mix inline scripts with task references, including parallel sub-task execution:

[tasks.pipeline]
run = [
  { task = "lint" },                 # run lint (with its dependencies)
  { tasks = ["test", "typecheck"] }, # run test and typecheck in parallel
  "echo 'All checks passed!'",      # then run a script
]

Structured depends with Args/Env

Pass arguments and environment variables to dependencies:

[tasks.deploy]
depends = [
  { task = "build", args = ["--release"], env = { RUSTFLAGS = "-C opt-level=3" } }
]
run = "./deploy.sh"

Env vars passed to dependencies are scoped to that dependency only.

Task Inheritance (extends)

A task can inherit configuration from another task:

[tasks._base_deploy]
hide = true
depends = ["build", "test"]
env = { DEPLOY_TIMESTAMP = "{{now()}}" }
tools = { node = "22" }

[tasks.deploy-staging]
extends = "_base_deploy"
env = { DEPLOY_ENV = "staging" }
run = "./scripts/deploy.sh staging"

[tasks.deploy-prod]
extends = "_base_deploy"
confirm = "Deploy to production?"
env = { DEPLOY_ENV = "production" }
run = "./scripts/deploy.sh production"

Global Task Configuration

[task_config] Section

[task_config]
dir = "{{cwd}}"  # Default working directory for all tasks
includes = [
  "tasks/*.toml",                              # Local task files
  ".mise/tasks/",                              # Task directory
  "git::https://github.com/org/tasks?ref=v1"  # Remote tasks
]

[vars] Section

Shared variables between tasks (NOT environment variables):

[vars]
project_name = "myapp"
version = "1.0.0"
registry = "ghcr.io/myorg"

[vars._.file]
path = "vars.toml"  # Load vars from external file

[tasks.build]
run = "echo Building {{vars.project_name}} v{{vars.version}}"

Vars are accessed via {{vars.key_name}} Tera templates. They are not passed as environment variables.

Global Task Settings

| Setting | Type | Default | Description | |---------|------|---------|-------------| | task_output | string | "prefix" | Output mode: prefix, interleave, keep-order, replacing, timed, quiet, silent | | task_timeout | string | none | Default timeout (e.g., "30m") | | task_timings | bool | false | Show elapsed time per task | | task_skip | string[] | [] | Tasks to skip by default | | task_skip_depends | bool | false | Skip dependencies | | task_run_auto_install | bool | true | Auto-install missing tools | | task_show_full_cmd | bool | false | Disable command truncation in output | | task_disable_paths | string[] | [] | Paths to exclude from task discovery | | task_remote_no_cache | bool | false | Always fetch latest remote tasks | | task.source_freshness_hash_contents | bool | false | Use blake3 content hashing instead of mtime | | task.source_freshness_equal_mtime_is_fresh | bool | false | Equal mtime = fresh | | jobs | int | 8 | Max concurrent task execution |

---

Running Tasks (CLI)

Commands

| Command | Description | |---------|-------------| | mise run <task> / mise r <task> | Execute task | | mise <task> | Shorthand (if no command conflict) | | mise tasks / mise tasks ls | List all tasks | | mise tasks --hidden | Include hidden tasks | | mise tasks deps | Show dependency tree | | mise tasks deps --dot | DOT format for Graphviz | | mise tasks info <task> | Show task details | | mise tasks add <name> -- <cmd> | Create task via CLI | | mise watch <task> / mise w <task> | Watch and re-run on file changes |

Execution Flags

| Flag | Description | |------|-------------| | -j, --jobs N | Parallel job limit (default: 4) | | -f, --force | Ignore source/output caching | | -n, --dry-run | Preview without executing | | -o, --output MODE | prefix, interleave, keep-order, replacing, timed, quiet, silent | | -r, --raw | Direct stdin/stdout/stderr | | -c, --continue-on-error | Continue running tasks even if one fails | | -s, --shell SHELL | Shell spec (default: sh -c -o errexit -o pipefail) | | -t, --tool TOOL@VERSION | Additional tools beyond mise.toml | | --timings | Show elapsed time per task | | --timeout DURATION | Task timeout (e.g., 30s, 5m) | | --fresh-env | Bypass environment cache | | --skip-deps | Run only specified tasks, skip dependencies | | --no-cache | Skip cache on remote tasks | | --no-prepare | Skip automatic dependency preparation |

Parallel Tasks and Wildcards

mise run test:*         # All test:* tasks
mise run lint:**        # All nested lint tasks
mise run {build,test}   # Multiple specific tasks
mise run lint ::: test ::: check  # Parallel task groups with :::
mise run cmd1 arg1 ::: cmd2 arg2 # Parallel with separate args

Default Task

[tasks.default]
depends = ["build", "test"]
run = "echo 'Ready!'"

---

Task Dependencies and Caching

Dependencies

[tasks.deploy]
depends = ["build", "test", "lint"]  # Run before (parallel by default)
depends_post = ["notify"]             # Run after
wait_for = ["db:migrate"]             # Wait if running, don't add

Caching with sources/outputs

[tasks.build]
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = ["target/release/myapp"]
run = "cargo build --release"
# Skips if sources unchanged and outputs exist

Auto outputs:

[tasks.build]
sources = ["src/**/*.rs"]
outputs = { auto = true }  # Implicit tracking via task hash
run = "cargo build"

Redactions (Experimental)

Hide sensitive values from task output:

redactions = ["API_KEY", "PASSWORD", "SECRETS_*"]

---

Dev Tools Management

Backends Overview

mise supports 18 backend types. Recommended priority order:

| Priority | Backend | Description | |----------|---------|-------------| | 1 | aqua | Most features, best security (cosign/SLSA/attestation). No plugins needed. | | 2 | github | GitHub releases with auto OS/arch detection | | 3 | gitlab | GitLab releases | | 4 | forgejo | Forgejo/Codeberg releases | | 5 | http | Direct HTTP/HTTPS downloads with URL templating | | 6 | s3 | S3/MinIO (experimental) | | 7 | pipx | Python CLIs in isolated environments | | 8 | npm | Node packages | | 9 | go | Go packages (requires compilation) | | 10 | cargo | Rust packages (requires compilation) | | 11 | gem | Ruby gems | | 12 | dotnet | .NET tools (experimental) | | 13 | conda | Conda packages (experimental) | | 14 | spm | Swift packages (experimental) | | 15 | vfox | vfox plugins (cross-platform, Windows) | | 16 | asdf | asdf plugins (legacy, no Windows) |

TOML Syntax for Tools

[tools]
# Simple version
node = "22"
python = "3.12"
ruby = "latest"

# Multiple versions
python = ["3.12", "3.11"]

# With options
node = { version = "22", postinstall = "corepack enable" }
python = { version = "3.11", os = ["linux", "macos"] }
ripgrep = { version = "latest", os = ["linux", "macos"] }

# Explicit backend
"aqua:BurntSushi/ripgrep" = "latest"
"github:cli/cli" = "latest"
"npm:prettier" = "latest"
"pipx:psf/black" = "latest"
"cargo:eza" = "latest"
"go:github.com/DarthSim/hivemind" = "latest"

Version formats:

| Format | Example | Description | |--------|---------|-------------| | Exact | "20.0.0" | Specific version | | Prefix | "20" | Latest matching prefix | | Latest | "latest" | Most recent stable | | ref:<SHA> | "ref:abc123" | Compile from git ref | | path:<PATH> | "path:/opt/node" | Use custom binary | | sub-<N>:<BASE> | "sub-1:latest" | N versions behind base |

Per-Tool Options

Every tool supports these options regardless of backend:

| Option | Type | Description | |--------|------|-------------| | version | string | Tool version | | os | string[] | Restrict to OS: "linux", "macos", "windows" | | install_env | table | Environment variables during installation | | postinstall | string | Command after installation. MISE_TOOL_INSTALL_PATH available. |

Backend-Specific Configuration

GitHub Backend Options

[tools."github:cli/cli"]
version = "latest"
asset_pattern = "gh_*_linux_x64.tar.gz"  # Match specific release asset
bin = "gh"                                 # Rename binary
filter_bins = "gh"                         # Only expose specific bins
no_app = true                              # Skip macOS .app bundles

HTTP Backend

[tools."http:my-tool"]
version = "1.0.0"
[tools."http:my-tool".platforms]
macos-x64 = { url = "https://example.com/tool-macos-x64.tar.gz", checksum = "sha256:..." }
linux-x64 = { url = "https://example.com/tool-linux-x64.tar.gz", checksum = "sha256:..." }

URL template variables: {{ version }}, {{ os() }}, {{ arch() }}, {{ os_family() }} OS/arch remapping: {{ os(macos="darwin") }}, {{ arch(x64="amd64") }}

Cargo Backend

[tools]
"cargo:eza" = "latest"
"cargo:cargo-edit" = { version = "latest", features = "add" }

Settings: cargo.binstall = true (use precompiled binaries, default), cargo.binstall_only = false.

Pipx Backend

[tools]
"pipx:black" = "latest"
"pipx:harlequin" = { version = "latest", extras = "postgres,s3" }
"pipx:ansible" = { version = "latest", uvx = false }  # Disable uv

Shims and Aliases

Shims location: ~/.local/share/mise/shims

# Shim mode (non-interactive shells)
eval "$(mise activate zsh --shims)"  # in ~/.zprofile

# PATH mode (interactive shells)
eval "$(mise activate zsh)"          # in ~/.zshrc

Best practice: Use both — shims in profile for non-interactive, PATH activation in rc for interactive.

Tool aliases (remap to different backend):

[tool_alias]
node = 'asdf:company/our-custom-node'

[tool_alias.node.versions]
lts = '22'

Shell aliases:

[shell_alias]
ll = "ls -la"
gs = "git status"

CLI Commands for Tools

mise use node@22            # Install + activate + write to mise.toml
mise use -g node@22         # Write to global config
mise install node@20        # Install without activation
mise install                # Install all configured tools
mise ls                     # List installed
mise ls-remote node         # List available versions
mise which node             # Show real binary path
mise x [email protected] -- script.py  # Run with specific tool
mise reshim                 # Rebuild shims
mise registry               # List all available tools

---

Environment Configuration

Basic Variables

[env]
NODE_ENV = 'production'
DEBUG = 'app:*'
PORT = 3000

# Unset a variable
UNWANTED_VAR = false

mise set NODE_ENV=development   # Set via CLI
mise set                        # View all
mise unset NODE_ENV             # Remove
mise env                        # Export all
mise env --json                 # Export as JSON
mise env --dotenv               # Export as dotenv

Special Directives (env._)

_.path — Prepend to PATH

[env]
_.path = ["tools/bin", "{{config_root}}/scripts"]
_.path = { path = ["{{env.GEM_HOME}}/bin"], tools = true }  # Lazy eval

_.file — Load from .env/json/yaml files

[env]
_.file = '.env'
_.file = ['.env', '.env.local', '.env.{{env.MISE_ENV}}']
_.file = { path = ".secrets.yaml", redact = true }

_.source — Source shell scripts

[env]
_.source = "./setup-env.sh"
_.source = { path = "my/env.sh", tools = true }

Profiles (MISE_ENV)

Profiles enable environment-specific config files:

MISE_ENV=staging mise run deploy

This loads mise.staging.toml in addition to mise.toml. Config file order:

• mise.toml (base)
• mise.staging.toml (profile overlay)
• mise.staging.local.toml (local overrides, gitignored)

Important: MISE_ENV cannot be set in mise.toml — it must be in .miserc.toml, an env var, or CLI flag because it determines which config files to load.

Required and Redacted Variables

[env]
# Required — error if not set
DATABASE_URL = { required = "Set postgres connection string" }

# Redacted — hidden from output
API_KEY = { value = "secret_key_here", redact = true }
redactions = ["*_TOKEN", "SECRET_*", "API_*"]

Templates (Tera)

mise.toml values support Tera templates:

[env]
PROJECT_DIR = "{{config_root}}"
LOG_FILE = "{{config_root}}/logs/{{now() | date(format='%Y-%m-%d')}}.log"
NODE_PATH = "{{env.npm_config_prefix}}/lib/node_modules"

Available template variables:

| Variable | Description | |----------|-------------| | env.* | Current environment variables | | config_root | Directory containing mise.toml | | cwd | Current working directory | | mise_bin | Path to mise binary | | mise_pid | Process ID | | xdg_cache_home | XDG cache directory | | xdg_config_home | XDG config directory | | xdg_data_home | XDG data directory | | xdg_state_home | XDG state directory |

Key Tera functions:

| Function | Description | |----------|-------------| | exec(command="cmd") | Execute shell command, return stdout | | arch() | System architecture | | os() | Operating system | | os_family() | OS family (unix/windows) | | num_cpus() | CPU count | | now() | Current datetime | | get_env(name, default) | Get env var with fallback | | chomp(str) | Remove trailing newline |

Key Tera filters:

| Filter | Description | |--------|-------------| | lower, upper, capitalize | Case transforms | | trim, replace(from, to) | String manipulation | | split(pat), join(sep) | Array operations | | basename, dirname, extname | Path operations | | hash, hash_file | SHA256/BLAKE3 hashing | | absolute, canonicalize | Path resolution | | kebabcase, snakecase, uppercamelcase | Case conversion |

Shell-style variable expansion (requires env_shell_expand = true):

[settings]
env_shell_expand = true

[env]
LD_LIBRARY_PATH = "$MY_LIB:$LD_LIBRARY_PATH"

---

Hooks and Watchers

Hook Types

| Hook | Trigger | Requires mise activate? | |------|---------|--------------------------| | cd | Directory changes | Yes | | enter | Enter a project (once) | Yes | | leave | Leave a project (once) | Yes | | preinstall | Before tool installation | No | | postinstall | After tool installation | No |

Syntax

[hooks]
cd = "echo 'changed directory'"
enter = "echo 'entered project'"
leave = "echo 'left project'"
preinstall = "echo 'about to install'"
postinstall = "echo 'installed'"

# Multiple hooks
enter = ["echo 'first'", "echo 'second'"]

# Shell hooks (execute in current shell context)
[hooks.enter]
shell = "bash"
script = "source completions.sh"

Watch Files

[[watch_files]]
patterns = ["src/**/*.rs"]
run = "cargo fmt"

Sets MISE_WATCH_FILES_MODIFIED env var. Requires watchexec.

Hook Environment Variables

All hooks receive: MISE_ORIGINAL_CWD, MISE_PROJECT_ROOT, MISE_PREVIOUS_DIR (cd hooks). Postinstall receives: MISE_INSTALLED_TOOLS (JSON array), MISE_TOOL_NAME, MISE_TOOL_VERSION, MISE_TOOL_INSTALL_PATH.

---

Configuration and Settings

File Hierarchy

Config files in precedence order (highest first):

1. mise.local.toml
2. mise.toml
3. mise/config.toml
4. .mise/config.toml
5. .config/mise.toml
6. .config/mise/config.toml
7. .config/mise/conf.d/*.toml (alphabetical)

Global: ~/.config/mise/config.toml System: /etc/mise/config.toml Legacy: .tool-versions (asdf-compatible)

mise searches upward from cwd to root (or MISE_CEILING_PATHS). Merge behavior:

• Tools: Additive with overrides
• Env vars: Additive with overrides
• Tasks: Completely replaced per task name
• Settings: Additive with overrides

Key Settings Reference

[settings]
# Execution
jobs = 8                    # Concurrent jobs
experimental = false        # Enable experimental features

# Task defaults
task_output = "prefix"      # prefix|interleave|keep-order|replacing|timed|quiet|silent
task_timeout = "10m"        # Default task timeout
task_timings = true         # Show elapsed time
task_skip = ["slow-task"]   # Tasks to skip
task_skip_depends = false   # Skip dependencies

# Environment
env_shell_expand = true     # Enable $VAR expansion
env_cache = false           # Cache computed environment
env_cache_ttl = "1h"        # Cache TTL

# Tool management
auto_install = true         # Auto-install missing tools
disable_backends = ["asdf"] # Disable backends
pin = false                 # Default --pin for mise use
lockfile = true             # Read/update lockfiles

# Security
paranoid = false            # Extra-secure behavior
gpg_verify = false          # Verify GPG signatures

# Performance
fetch_remote_versions_cache = "1h"  # Version cache
http_timeout = "30s"                # HTTP timeout

# Node-specific
[settings.node]
corepack = false            # Enable corepack
compile = false             # Compile from source

# Python-specific
[settings.python]
uv_venv_auto = false        # Auto-create venv with uv
compile = false             # Compile from source

# Aqua security
[settings.aqua]
cosign = true               # Verify Cosign signatures
slsa = true                 # Verify SLSA provenance

Minimum Version

min_version = '2024.11.1'                               # Hard (errors)
min_version = { soft = '2024.11.1' }                    # Soft (warns)
min_version = { hard = '2024.11.1', soft = '2024.9.0' } # Both

Automatic Environment Variables

Tasks automatically receive:

| Variable | Description | |----------|-------------| | MISE_ORIGINAL_CWD | Original working directory | | MISE_CONFIG_ROOT | Directory containing mise.toml | | MISE_PROJECT_ROOT | Project root directory | | MISE_TASK_NAME | Current task name | | MISE_TASK_DIR | Task script directory | | MISE_TASK_FILE | Full path to task script |

---

Prepare Feature (Experimental)

Ensures dependencies are installed before task execution.

export MISE_EXPERIMENTAL=1
mise prepare

[prepare.npm]
auto = true

[prepare.custom]
sources = ["schema/*.graphql"]
outputs = ["src/generated/"]
run = "npm run codegen"

Built-in providers: npm, yarn, pnpm, bun, go, pip, poetry, uv, bundler, composer.

---

Monorepo Tasks (Experimental)

# Root mise.toml
experimental_monorepo_root = true

Requires MISE_EXPERIMENTAL=1.

mise //projects/frontend:build    # Absolute path from root
mise :build                       # Task in current config_root
mise '//projects/frontend:*'      # All tasks in frontend
mise //...:test                   # Test task in all projects

Settings:

[settings.task]
monorepo_depth = 5
monorepo_exclude_dirs = ["dist", "node_modules"]
monorepo_respect_gitignore = true

---

Best Practices

DO

• Always use usage field for task arguments
• Use ${var?} for required args to fail early
• Set description for discoverability
• Use sources/outputs for cacheable tasks
• Use depends for task ordering
• Use confirm for destructive operations
• Use choices for stable enums, complete for dynamic/filesystem-derived values
• Group related tasks with namespaces (e.g., test:unit, test:e2e)
• Use mise.local.toml for personal overrides (gitignored)
• Prefer aqua backend for security (cosign/SLSA verification)
• Use env._.file for dotenv loading instead of MISE_ENV_FILE
• Redact sensitive values with redact = true
• Use templates for dynamic values instead of hardcoding paths
• Use extends to share config between similar tasks

DON'T

• Use $1, $2, $@, $* for arguments
• Use $args in PowerShell
• Use inline {{arg(name="x")}} syntax (deprecated, removed 2026.11)
• Forget to quote glob patterns in sources
• Set env vars in env that deps need (they don't inherit — use structured depends with env)
• Use raw = true unless interactive input needed
• Set MISE_ENV in mise.toml (it determines which files to load)
• Manually add executables to shims directory (mise reshim removes them)
• Use MISE_RAW=1 without knowing it sets MISE_JOBS=1

Complete Task Example

[tasks.deploy]
description = "Deploy application to environment"
alias = "d"
depends = ["build", "test"]
usage = '''
arg "<env>" choices "dev" "staging" "prod" help="Target environment"
flag "-f --force" help="Skip confirmation"
flag "--dry-run" help="Preview only"
'''
env = { DEPLOY_TIMESTAMP = "{{now()}}" }
tools = { node = "22" }
sources = ["dist/**/*"]
timeout = "5m"
confirm = "Deploy to {{usage.env}}?"
run = '''
#!/usr/bin/env bash
set -euo pipefail

if [ -n "${usage_dry_run:-}" ]; then
  echo "DRY RUN: Would deploy to ${usage_env?}"
  exit 0
fi

./scripts/deploy.sh "${usage_env?}"
'''

Complete File Task Example

#!/usr/bin/env bash
#MISE description="Run database migrations"
#MISE alias="migrate"
#MISE depends=["db:check"]
#MISE tools={postgresql="16"}
#USAGE arg "<direction>" choices "up" "down" help="Migration direction"
#USAGE flag "-n --count <n>" default="1" help="Number of migrations"
#USAGE flag "--dry-run" help="Preview SQL only"

set -euo pipefail

direction="${usage_direction?}"
count="${usage_count:-1}"

if [ -n "${usage_dry_run:-}" ]; then
  echo "Would run $count migration(s) $direction"
  exit 0
fi

migrate "$direction" -n "$count"

Complete Dev Tools + Env Example

min_version = "2024.11.1"

[settings]
jobs = 8
task_output = "interleave"
task_timings = true
env_shell_expand = true

[tools]
node = "22"
python = { version = "3.12", postinstall = "pip install -r requirements.txt" }
"aqua:BurntSushi/ripgrep" = "latest"
"npm:prettier" = "latest"

[env]
NODE_ENV = "development"
DATABASE_URL = { required = "Set postgres connection string" }
API_KEY = { value = "{{env.API_KEY}}", redact = true }
_.path = ["./node_modules/.bin", "{{config_root}}/scripts"]
_.file = [".env", ".env.local"]

[hooks]
enter = "echo 'Welcome to {{vars.project_name}}'"

[vars]
project_name = "myapp"

[tasks.dev]
description = "Start development server"
depends = ["build"]
tools = { node = "22" }
run = "npm run dev"

[tasks.build]
description = "Build project"
sources = ["src/**/*.ts", "tsconfig.json"]
outputs = ["dist/**/*"]
run = "tsc --build"

[tasks.test]
description = "Run tests"
depends = ["build"]
run = "vitest run"