mise Configuration as Single Source of Truth
Use mise [env] as centralized configuration with backward-compatible defaults.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
When to Use This Skill
Use this skill when:
- Centralizing environment variables in mise.toml
- Setting up Python venv auto-creation with mise
- Implementing hub-spoke configuration for monorepos
- Creating backward-compatible environment patterns
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 |
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} |
For detailed directive examples with options (redact, tools, multi-file): Code Patterns
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:
- Creates
.venvif it doesn't exist - Activates the venv automatically
- Works with
uvfor fast venv creation
Alternative via [settings]:
[settings]
python.uv_venv_auto = trueHub-Spoke Architecture (CRITICAL)
Keep root mise.toml lean by delegating domain-specific tasks to subfolder mise.toml files. Applies to monorepos, ML/research projects, infrastructure, and data pipelines.
Key rules:
- Hub owns
[tools]and orchestration tasks - Spokes inherit hub's
[tools]automatically - Spoke
[env]extends hub's[env](can override per domain) .mise.local.tomlapplies at directory level (secrets stay local)
Full guide with directory structures, examples, and anti-patterns: Hub-Spoke Architecture
Wiki Reference: Pattern-mise-Configuration
Monorepo Workspace Pattern
For Python monorepos using uv workspaces, the venv is created at the workspace root. Dev dependencies should be hoisted to root pyproject.toml using [dependency-groups] (PEP 735).
Full guide: Monorepo Workspace Pattern
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 |
For functions (get_env, exec, arch, read_file, hash_file), filters (snakecase, trim, absolute), and conditionals: Code Patterns - Template Syntax
Required & Redacted Variables
[env]
# Required - fails if not set
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }
# Redacted - hides from output
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }
# Pattern-based redactions
redactions = ["*_TOKEN", "*_KEY", "PASSWORD"]For combined patterns and detailed examples: Code Patterns - Required & Redacted
Lazy Evaluation (tools = true)
By default, env vars resolve BEFORE tools install. Use tools = true to access tool-generated paths:
[env]
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }
_.file = { path = ".env", tools = true }[settings] and [tools]
[settings]
experimental = true
python.uv_venv_auto = true
[tools]
python = "<version>"
node = "latest"
uv = "latest"
rust = { version = "<version>", profile = "minimal" }
# SSoT-OK: mise min_version directive, not a package version
min_version = "2024.9.5"For full settings reference and version pinning options: Code Patterns - Settings & Tools
Implementation Steps
- Identify hardcoded values - timeouts, paths, thresholds, feature flags
- Create
.mise.toml- add[env]section with documented variables - Add venv auto-creation -
_.python.venv = {path = ".venv", create = true} - Update scripts - use env vars with original values as defaults
- Add ADR reference - comment:
# ADR: 2025-12-08-mise-env-centralized-config - Test without mise - verify script works using defaults
- Test with mise - verify activated shell uses
.mise.tomlvalues
GitHub Token Multi-Account Patterns {#github-token-multi-account-patterns}
For multi-account GitHub setups, mise [env] provides per-directory token configuration that overrides gh CLI's global authentication.
Rule: Always set BOTH GH_TOKEN and GITHUB_TOKEN pointing to the same token file.
| Variable | Usage Context |
|---|---|
GH_TOKEN | mise [env], Doppler, verification tasks |
GITHUB_TOKEN | npm scripts, GitHub Actions, semantic-release |
Full guide with templates, verification, and 1Password integration: GitHub Token Patterns
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 |
[env] secrets for pueue jobs | Pueue runs clean shell, no mise | Use python-dotenv + .env file |
__MISE_DIFF leaks via SSH | Remote trust errors | unset __MISE_DIFF before SSH |
Critical detail on non-interactive shell secrets: Anti-Patterns Guide
Task Orchestration Integration
When detecting multi-step project workflows during mise configuration, invoke the mise-tasks skill for task definitions with dependency management.
Detection triggers: multi-step workflows, repeatable commands, dependency chains, file-tracked builds.
Full guide with examples: Task Orchestration | mise-tasks skill
Additional Resources
- Code Patterns & Templates - Complete code examples for Python, Bash, JS, Go, Rust, and full
.mise.tomltemplate - Hub-Spoke Architecture - Directory structures, hub/spoke responsibilities, inheritance rules
- GitHub Token Patterns - Multi-account setup, verification, 1Password integration
- Anti-Patterns Guide - Non-interactive shell secrets, pueue/cron/systemd gotchas
- Task Orchestration - Workflow detection triggers, environment-to-tasks example
- Monorepo Workspace - uv workspaces, hoisted dev dependencies (PEP 735)
- Wiki: Pattern-mise-Configuration
ADR Reference: When implementing mise configuration, create an ADR at docs/adr/YYYY-MM-DD-mise-env-centralized-config.md in your project.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Env vars not loading | mise not activated | Add mise activate to shell rc file |
| Venv not created | Python not installed | Run mise install python |
| Tasks not found | Wrong mise.toml location | Ensure mise.toml is in project root |
| PATH not updated | Shims not in PATH | Add mise shims to ~/.zshenv |
| .file not loading | .env file missing | Create.env file or remove.file directive |
| Subfolder config ignored | Missing min_version | Add min_version to subfolder mise.toml |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.