Templates
Templates in mise provide a powerful way to configure different aspects of your environment and project settings. You can define and use templates in the following locations:
.tool-versions
files.mise.toml
files for most configuration- (Submit a ticket if you want to see it used elsewhere!)
Template Rendering
Mise uses tera to provide the template feature. In the template, there are 3 kinds of delimiters:
{{
and}}
for expressions{%
and%}
for statements{#
and#}
for comments
Additionally, use raw
block to skip rendering tera delimiters:
{% raw %}
Hello {{ name }}
{% endraw %}
This will become Hello {{name}}
.
Tera supports literals, including:
- booleans:
true
(orTrue
) andfalse
(orFalse
) - integers
- floats
- strings: text delimited by
""
,''
or``
- arrays: a comma-separated list of literals and/or ident surrounded by
[
and]
(trailing comma allowed)
You can render a variable by using the {{ name }}
. For complex attributes, use:
- dot
.
, e.g.{{ product.name }}
- square brackets
[]
, e.g.{{ product["name"] }}
Tera also supports powerful expressions:
- mathematical expressions
+
-
/
*
%
- comparisons
==
!=
>=
<=
<
>
- logic
and
or
not
- concatenation
~
, e.g.{{ "hello " ~ 'world' ~ `!` }
- in checking, e.g.
{{ some_var in [1, 2, 3] }}
Tera also supports control structures such as if
and for
. Read more here.
Tera Filters
You can modify variables using filters. You can filter a variable by a pipe symbol (|
) and may have named arguments in parentheses. You can also chain multiple filters. e.g. {{ "Doctor Who" | lower | replace(from="doctor", to="Dr.") }}
will output Dr. who
.
Tera Functions
Functions provide additional features to templates.
Tera Tests
You can also uses tests to examine variables.
{% if my_number is not odd %}
Even
{% endif %}
Mise Template Features
Mise provides additional variables, functions, filters and tests on top of tera features.
Variables
Mise exposes several variables. These variables offer key information about the current environment:
env: HashMap<String, String>
– Accesses current environment variables as a key-value map.cwd: PathBuf
– Points to the current working directory.config_root: PathBuf
– Locates the directory containing your.mise.toml
file or the.mise
configuration folder.mise_bin: String
- Points to the path to the current mise executablemise_pid: String
- Points to the pid of the current mise processxdg_cache_home: PathBuf
- Points to the directory of XDG cache homexdg_config_home: PathBuf
- Points to the directory of XDG config homexdg_data_home: PathBuf
- Points to the directory of XDG data homexdg_state_home: PathBuf
- Points to the directory of XDG state home
Functions
Tera offers many built-in functions. []
indicates an optional function argument. Some functions:
range(end, [start], [step_by])
- Returns an array of integers created using the arguments given.end: usize
: stop beforeend
, mandatorystart: usize
: where to start from, defaults to0
step_by: usize
: with what number do we increment, defaults to1
now([timestamp], [utc])
- Returns the local datetime as string or the timestamp as integer.timestamp: bool
: whether to return the timestamp instead of the datetimeutc: bool
: whether to return the UTC datetime instead of the local one- Tip: use date filter to format date string. e.g.
{{ now() | date(format="%Y") }}
gets the current year.
throw(message)
- Throws with the message.get_random(end, [start])
- Returns a random integer in a range.end: usize
: upper end of the rangestart: usize
: defaults to 0
get_env(name, [default])
: Returns the environment variable value by name. Preferenv
variable than this function.name: String
: the name of the environment variabledefault: String
: a default value in case the environment variable is not found. Throws when can't find the environment variable anddefault
is not set.
Tera offers more functions. Read more on tera documentation.
Mise offers additional functions:
exec(command) -> String
– Runs a shell command and returns its output as a string.arch() -> String
– Retrieves the system architecture, such asx86_64
orarm64
.os() -> String
– Returns the name of the operating system, e.g. linux, macos, windows.os_family() -> String
– Returns the operating system family, e.g.unix
,windows
.num_cpus() -> usize
– Gets the number of CPUs available on the system.choice(n, alphabet)
- Generate a string ofn
with random sample with replacement ofalphabet
. For example,choice(64, HEX)
will generate a random 64-character lowercase hex string.
A example of function using exec
:
[alias.node]
current = "{{ exec(command='node --version') }}"
Filters
Tera offers many built-in filters. []
indicates an optional filter argument. Some filters:
str | lower -> String
– Converts a string to lowercase.str | upper -> String
– Converts a string to uppercase.str | capitalize -> String
– Converts a string with all its characters lowercased apart from the first char which is uppercased.str | replace(from, to) -> String
– Replaces a string with all instances offrom
toto
. e.g.,{{ name | replace(from="Robert", to="Bob")}}
str | title -> String
– Capitalizes each word inside a sentence. e.g.,{{ "foo bar" | title }}
becomesFoo Bar
.str | trim -> String
– Removes leading and trailing whitespace.str | trim_start -> String
– Removes leading whitespace.str | trim_end -> String
– Removes trailing whitespace.str | truncate -> String
– Truncates a string to the indicated length.str | first -> String
– Returns the first element in an array or string.str | last -> String
– Returns the last element in an array or string.str | join(sep) -> String
– Joins an array of strings with a separator, such as{{ ["a", "b", "c"] | join(sep=", ") }}
to producea, b, c
.str | length -> usize
– Returns the length of a string or array.str | reverse -> String
– Reverses the order of characters in a string or elements in an array.str | urlencode -> String
– Encodes a string to be safely used in URLs, converting special characters to percent-encoded values.str | map(attribute) -> Array
– Extracts an attribute from each object in an array.str | concat(with) -> Array
– Appends values to an array.str | abs -> Number
– Returns the absolute value of a number.str | filesizeformat -> String
– Converts an integer into a human-readable file size (e.g., 110 MB).str | date(format) -> String
– Converts a timestamp to a formatted date string using the provided format, such as{{ ts | date(format="%Y-%m-%d") }}
. Find a list of time format onchrono
documentation.str | split(pat) -> Array
– Splits a string by the given pattern and returns an array of substrings.str | default(value) -> String
– Returns the default value if the variable is not defined or is empty.
Tera offers more filters. Read more on tera documentation.
Hash
str | hash([len]) -> String
– Generates a SHA256 hash for the input string.len: usize
: truncates the hash string to the given size
path | hash_file([len]) -> String
– Returns the SHA256 hash of the file at the given path.len: usize
: truncates the hash string to the given size
Path Manipulation
path | canonicalize -> String
– Converts the input path into absolute input path version. Throws if path doesn't exist.path | basename -> String
– Extracts the file name from a path, e.g./foo/bar/baz.txt
becomesbaz.txt
.path | file_size -> String
– Returns the size of a file in bytes.path | dirname -> String
– Returns the directory path for a file, e.g./foo/bar/baz.txt
becomes/foo/bar
.path | basename -> String
– Returns the base name of a file, e.g./foo/bar/baz.txt
becomesbaz.txt
.path | extname -> String
– Returns the extension of a file, e.g./foo/bar/baz.txt
becomes.txt
.path | file_stem -> String
– Returns the file name without the extension, e.g./foo/bar/baz.txt
becomesbaz
.path | file_size -> String
– Returns the size of a file in bytes.path | last_modified -> String
– Returns the last modified time of a file.path[] | join_path -> String
– Joins an array of paths into a single path.
For example, you can use split()
, concat()
, and join_path
filters to construct a file path:
[env]
PROJECT_CONFIG = "{{ config_root | concat(with='bar.txt') | join_path }}"
String Manipulation
str | quote -> String
– Quotes a string. Converts'
to\'
and then quotes str, e.g'it\'s str'
.str | kebabcase -> String
– Converts a string to kebab-casestr | lowercamelcase -> String
– Converts a string to lowerCamelCasestr | uppercamelcase -> String
– Converts a string to UpperCamelCasestr | shoutycamelcase -> String
– Converts a string to ShoutyCamelCasestr | snakecase -> String
– Converts a string to snake_casestr | shoutysnakecase -> String
– Converts a string to SHOUTY_SNAKE_CASE
Tests
Tera offers many built-in tests. Some tests:
defined
- Returnstrue
if the given variable is defined.string
- Returnstrue
if the given variable is a string.number
- Returnstrue
if the given variable is a number.starting_with
- Returnstrue
if the given variable is a string and starts with the arg given.ending_with
- Returnstrue
if the given variable is a string and ends with the arg given.containing
- Returnstrue
if the given variable contains the arg given.matching
- Returnstrue
if the given variable is a string and matches the regex in the argument.
Tera offers more tests. Read more on tera documentation.
Mise offers additional tests:
if path is dir
– Checks if the provided path is a directory.if path is file
– Checks if the path points to a file.if path is exists
– Checks if the path exists.if version is semver_matching(String)
– Confirms if a version string matches a semantic version pattern (e.g.,if "1.10.2" is semver_matching("^1.10.0")
).
Example Templates
A Node.js Project
min_version = "2024.9.5"
[env]
# Use the project name derived from the current directory
PROJECT_NAME = "{{ cwd | basename }}"
# Set up the path for node module binaries
BIN_PATH = "{{ cwd }}/node_modules/.bin"
NODE_ENV = "{{ env.NODE_ENV | default(value='development') }}"
[tools]
# Install Node.js using the specified version
node = "{{ env['NODE_VERSION'] | default(value='lts') }}"
# Install npm packages globally if needed
"npm:typescript" = "latest"
"npm:eslint" = "latest"
"npm:jest" = "latest"
# Install npm dependencies
[tasks.install]
alias = "i"
run = "npm install"
# Run the development server
[tasks.start]
alias = "s"
run = "npm run start"
# Run linting
[tasks.lint]
alias = "l"
run = "eslint src/"
# Run tests
[tasks.test]
alias = "t"
run = "jest"
# Build the project
[tasks.build]
alias = "b"
run = "npm run build"
# Print project info
[tasks.info]
run = '''
echo "Project: $PROJECT_NAME"
echo "NODE_ENV: $NODE_ENV"
'''
A Python Project with virtualenv
min_version = "2024.9.5"
[env]
# Use the project name derived from the current directory
PROJECT_NAME = "{{ cwd | basename }}"
# Automatic virtualenv activation
_.python.venv = { path = ".venv", create = true }
[tools]
# Install the specified Python version
python = "{{ get_env(name='PYTHON_VERSION', default='3.11') }}"
# Install dependencies
[tasks.install]
alias = "i"
run = "pip install -r requirements.txt"
# Run the application
[tasks.run]
run = "python app.py"
# Run tests
[tasks.test]
run = "pytest tests/"
# Lint the code
[tasks.lint]
run = "ruff src/"
# Print environment information
[tasks.info]
run = '''
echo "Project: $PROJECT_NAME"
echo "Virtual Environment: $VIRTUAL_ENV"
'''
A C++ Project with CMake
min_version = "2024.9.5"
[env]
# Project information
PROJECT_NAME = "{{ cwd | basename }}"
# Build directory
BUILD_DIR = "{{ cwd }}/build"
[tools]
# Install CMake and make
cmake = "latest"
make = "latest"
# Configure the project
[tasks.configure]
run = "mkdir -p $BUILD_DIR && cd $BUILD_DIR && cmake .."
# Build the project
[tasks.build]
alias = "b"
run = "cd $BUILD_DIR && make"
# Clean the build directory
[tasks.clean]
alias = "c"
run = "rm -rf $BUILD_DIR"
# Run the application
[tasks.run]
alias = "r"
run = "$BUILD_DIR/bin/$PROJECT_NAME"
# Print project info
[tasks.info]
run = '''
echo "Project: $PROJECT_NAME"
echo "Build Directory: $BUILD_DIR"
'''
A Ruby on Rails Project
min_version = "2024.9.5"
[env]
# Project information
PROJECT_NAME = "{{ cwd | basename }}"
[tools]
# Install Ruby with the specified version
ruby = "{{ get_env(name='RUBY_VERSION', default='3.3.3') }}"
# Install gem dependencies
[tasks."bundle:install"]
run = "bundle install"
# Run the Rails server
[tasks.server]
alias = "s"
run = "rails server"
# Run tests
[tasks.test]
alias = "t"
run = "rails test"
# Lint the code
[tasks.lint]
alias = "l"
run = "rubocop"