---

name: mise Configuration SSoT description: This skill should be used when the user asks to "configure environment variables", "use mise env", "add mise configuration", "refactor hardcoded values", "centralize configuration", "set up Python venv", "mise templates", mentions "mise [env]", "mise.toml", "[settings]", "[tools]", or needs guidance on environment variable patterns with backward compatibility.

mise Configuration as Single Source of Truth

Use mise [env] as centralized configuration with backward-compatible defaults.

Core Principle

Define all configurable values in .mise.toml [env] section. Scripts read via environment variables with fallback defaults. Same code path works WITH or WITHOUT mise installed.

Key insight: mise auto-loads [env] values when shell has mise activate configured. Scripts using os.environ.get("VAR", "default") pattern work identically whether mise is present or not.

Quick Reference

Language Patterns

Language	Pattern	Notes
Python	os.environ.get("VAR", "default")	Returns string, cast if int
Bash	${VAR:-default}	Standard POSIX expansion
JavaScript	process.env.VAR || "default"	Falsy check, watch for "0"
Go	os.Getenv("VAR") with default	Empty string if unset
Rust	std::env::var("VAR").unwrap_or()	Returns Result<String>

Special Directives

Directive	Purpose	Example
_.file	Load from .env files	_.file = ".env"
_.path	Extend PATH	_.path = ["bin", "node_modules/.bin"]
_.source	Execute bash scripts	_.source = "./scripts/env.sh"
_.python.venv	Auto-create Python venv	_.python.venv = { path = ".venv", create = true }

Python Venv Auto-Creation (Critical)

Auto-create and activate Python virtual environments:

[env]
_.python.venv = { path = ".venv", create = true }

This pattern is used in ALL projects. When entering the directory with mise activated:

1. Creates .venv if it doesn't exist
2. Activates the venv automatically
3. Works with uv for fast venv creation

Alternative via [settings]:

[settings]
python.uv_venv_auto = true

Special Directives

Load from .env Files (_.file)

[env]
# Single file
_.file = ".env"

# Multiple files with options
_.file = [
    ".env",
    { path = ".env.secrets", redact = true }
]

Extend PATH (_.path)

[env]
_.path = [
    "{{config_root}}/bin",
    "{{config_root}}/node_modules/.bin",
    "scripts"
]

Source Bash Scripts (_.source)

[env]
_.source = "./scripts/env.sh"
_.source = { path = ".secrets.sh", redact = true }

Lazy Evaluation (tools = true)

By default, env vars resolve BEFORE tools install. Use tools = true to access tool-generated paths:

[env]
# Access PATH after tools are set up
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }

# Load .env files after tool setup
_.file = { path = ".env", tools = true }

Template Syntax (Tera)

mise uses Tera templating. Delimiters: {{ }} expressions, {% %} statements, {# #} comments.

Built-in Variables

Variable	Description
{{config_root}}	Directory containing .mise.toml
{{cwd}}	Current working directory
{{env.VAR}}	Environment variable
{{mise_bin}}	Path to mise binary
{{mise_pid}}	mise process ID
{{xdg_cache_home}}	XDG cache directory
{{xdg_config_home}}	XDG config directory
{{xdg_data_home}}	XDG data directory

Functions

[env]
# Get env var with fallback
NODE_VER = "{{ get_env(name='NODE_VERSION', default='20') }}"

# Execute shell command
TIMESTAMP = "{{ exec(command='date +%Y-%m-%d') }}"

# System info
ARCH = "{{ arch() }}"      # x64, arm64
OS = "{{ os() }}"          # linux, macos, windows
CPUS = "{{ num_cpus() }}"

# File operations
VERSION = "{{ read_file(path='VERSION') | trim }}"
HASH = "{{ hash_file(path='config.json', len=8) }}"

Filters

[env]
# Case conversion
SNAKE = "{{ name | snakecase }}"
KEBAB = "{{ name | kebabcase }}"
CAMEL = "{{ name | lowercamelcase }}"

# String manipulation
TRIMMED = "{{ text | trim }}"
UPPER = "{{ text | upper }}"
REPLACED = "{{ text | replace(from='old', to='new') }}"

# Path operations
ABSOLUTE = "{{ path | absolute }}"
BASENAME = "{{ path | basename }}"
DIRNAME = "{{ path | dirname }}"

Conditionals

[env]
{% if env.DEBUG %}
LOG_LEVEL = "debug"
{% else %}
LOG_LEVEL = "info"
{% endif %}

Required & Redacted Variables

Required Variables

Enforce variable definition with helpful messages:

[env]
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }

Redacted Variables

Hide sensitive values from output:

[env]
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }

# Pattern-based redactions
redactions = ["*_TOKEN", "*_KEY", "PASSWORD"]

[settings] Section

[settings]
experimental = true              # Enable experimental features
python.uv_venv_auto = true       # Auto-create venv with uv

[tools] Version Pinning

Pin tool versions for reproducibility:

[tools]
python = "3.11"  # minimum baseline; use 3.12, 3.13 as needed
node = "latest"
uv = "latest"

# With options
rust = { version = "1.75", profile = "minimal" }

min_version: Enforce mise version compatibility:

min_version = "2024.9.5"

Implementation Steps

1. Identify hardcoded values - timeouts, paths, thresholds, feature flags
2. Create .mise.toml - add [env] section with documented variables
3. Add venv auto-creation - _.python.venv = { path = ".venv", create = true }
4. Update scripts - use env vars with original values as defaults
5. Add ADR reference - comment: # ADR: 2025-12-08-mise-env-centralized-config
6. Test without mise - verify script works using defaults
7. Test with mise - verify activated shell uses .mise.toml values

Anti-Patterns

Anti-Pattern	Why	Instead
mise exec -- script.py	Forces mise dependency	Use env vars with defaults
Secrets in .mise.toml	Visible in repo	Use Doppler or redact = true
No defaults in scripts	Breaks without mise	Always provide fallback
Mixing env/tools resolution	Order matters	Use tools = true for tool-dependent vars

Task Orchestration Integration

When you detect workflow opportunities during mise configuration, prescriptively invoke the mise-tasks skill.

Detection Triggers

• Multi-step workflows (test + build + deploy)
• Repeatable project commands (lint, format, release)
• Dependency chains (db-migrate depends on db-init)
• File-tracked builds (sources/outputs caching)

Prescriptive AI Reminder

PRESCRIPTIVE: When detecting multi-step project workflows, invoke mise-tasks skill to generate appropriate [tasks] definitions with dependency management.

Example: From Environment to Tasks

Step 1: Configure environment (this skill):

[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.python.venv = { path = ".venv", create = true }

Step 2: Define tasks (mise-tasks skill):

[tasks.test]
depends = ["lint"]
run = "pytest tests/"

[tasks.deploy]
depends = ["test", "build"]
run = "deploy.sh"

Tasks automatically inherit [env] values.

---

Additional Resources

For complete code patterns and examples, see: references/patterns.md

For task orchestration, see: mise-tasks skill - Dependencies, arguments, file tracking, watch mode

ADR Reference: When implementing mise configuration, create an ADR at docs/adr/YYYY-MM-DD-mise-env-centralized-config.md in your project.