mise Configuration as Single Source of Truth

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

Special Directives

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:

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

Hub-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.toml applies 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

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

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

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.

Full guide with templates, verification, and 1Password integration: GitHub Token Patterns

Anti-Patterns

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.toml template
• 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

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. 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.