mise Configuration as Single Source of Truth

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

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 .venv if it doesn't exist

• Activates the venv automatically

• 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

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.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.

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.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

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