Skip to main content
Tokens are variables and functions that can be used by command, args, env, inputs, and outputs when configuring a task. They provide a way of accessing file group paths, referencing values from other task fields, and referencing metadata about the project and task itself.

​
Functions

A token function is labeled as such because it takes a single argument, starts with an @, and is formatted as @name(arg). Token functions expand to file paths, globs, or other values based on the function.
Token functions must be the only content within a value, as they can expand to multiple items. When used in an env value, multiple files are joined with a comma (,).

​
File groups

These functions reference file groups by name, where the name is passed as the argument.

​
@group(name)

​
Usable in
string
args, env, inputs, outputs
The @group(file_group) token is a standard token that will be replaced with the file group items as-is, for both file paths and globs. This token exists for reusability purposes.
moon.yml
fileGroups:
  storybook:
    - '.storybook/**/*'
    - 'src/**/*'
    - '**/*.stories.*'

tasks:
  build:
    command: 'build-storybook'
    inputs:
      - '@group(storybook)'  # Reuse the file group
Expands to: 
tasks:
  build:
    command: 'build-storybook'
    inputs:
      - '/path/to/project/.storybook/**/*'
      - '/path/to/project/src/**/*'
      - '/path/to/project/**/*.stories.*'

​
@dirs(name)

​
Usable in
string
args, env, inputs, outputs
The @dirs(file_group) token will be replaced with an expanded list of directory paths, derived from the file group of the same name. If a glob pattern is detected, it will aggregate all directories found.
This token walks the file system to verify each directory exists, and filters out those that don’t. If using within outputs, you’re better off using @group instead.
moon.yml
fileGroups:
  lintable:
    - 'src'
    - 'tests'
    - 'scripts'

tasks:
  lint:
    command: 'eslint @dirs(lintable) --color'
Expands to: 
eslint src tests scripts --color

​
@files(name)

​
Usable in
string
args, env, inputs, outputs
The @files(file_group) token will be replaced with an expanded list of file paths, derived from the file group of the same name. If a glob pattern is detected, it will aggregate all files found.
This token walks the file system to verify each file exists, and filters out those that don’t. If using within outputs, you’re better off using @group instead.
moon.yml
fileGroups:
  config:
    - '*.config.js'
    - 'package.json'

tasks:
  build:
    command: 'webpack build @files(config)'
Expands to: 
webpack build babel.config.js webpack.config.js package.json

​
@globs(name)

​
Usable in
string
args, env, inputs, outputs
The @globs(file_group) token will be replaced with the list of glob patterns as-is, derived from the file group of the same name. If a non-glob pattern is detected, it will be ignored.
moon.yml
fileGroups:
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'

tasks:
  test:
    command: 'jest --testMatch @globs(tests)'
Expands to: 
jest --testMatch tests/**/* **/__tests__/**/*

​
@root(name)

​
Usable in
string
args, env, inputs, outputs
The @root(file_group) token will be replaced with the lowest common directory, derived from the file group of the same name. If a glob pattern is detected, it will walk the file system and aggregate all directories found before reducing.
moon.yml
fileGroups:
  sources:
    - 'src/app'
    - 'src/packages'
    - 'src/scripts'

tasks:
  format:
    command: 'prettier --write @root(sources)'
Expands to: 
prettier --write src
When there are no directories, or too many directories at different levels, this function will return the project root using ..

​
@envs(name)

​
Usable in
string
inputs only
The @envs(file_group) token will be replaced with all environment variables that have been configured in the group of the provided name.
moon.yml
fileGroups:
  sources:
    - 'src/**/*'
    - '$NODE_ENV'

tasks:
  build:
    command: 'vite build'
    inputs:
      - '@envs(sources)'  # Tracks NODE_ENV changes

​
Inputs & outputs

​
@in(index)

​
Usable in
string
script and args only
The @in(index) token will be replaced with a single path, derived from inputs by numerical index. If a glob pattern is referenced by index, the glob will be used as-is.
moon.yml
tasks:
  build:
    command:
      - 'babel'
      - '--copy-files'
      - '--config-file'
      - '@in(1)'  # Reference second input
      - '@in(0)'  # Reference first input
    inputs:
      - 'src'
      - 'babel.config.js'
Expands to: 
babel --copy-files --config-file babel.config.js src

​
@out(index)

​
Usable in
string
script and args only
The @out(index) token will be replaced with a single path, derived from outputs by numerical index.
moon.yml
tasks:
  build:
    command:
      - 'babel'
      - '.'
      - '--out-dir'
      - '@out(0)'  # Reference first output
    outputs:
      - 'lib'
Expands to: 
babel . --out-dir lib

​
Miscellaneous

​
@meta(key)

​
Usable in
string
command, script, args, env
The @meta(key) token can be used to access project metadata and will be replaced with a value derived from project in moon.*. Built-in fields (like name and description) are used as-is. Custom metadata defined in project can also be accessed by key.
moon.yml
project:
  title: 'example'
  description: 'An example project'
  customField: 'custom value'

tasks:
  build:
    command: 'build --name @meta(title) --desc "@meta(description)"'
Expands to: 
build --name example --desc "An example project"

​
Variables

A token variable is a value that starts with $ and is substituted to a value derived from the current workspace, project, and task. Unlike token functions, token variables can be placed within content when necessary, and support multiple variables within the same content.

​
Environment

​
$arch
string
The current host architecture, derived from the Rust ARCH constant.Examples: x86_64, aarch64
​
$os
string
The current operating system, derived from the Rust OS constant.Examples: linux, macos, windows
​
$osFamily
string
The current operating system family, either unix or windows.
moon.yml
tasks:
  build:
    command: 'example --arch $arch --os $os'
Expands to: 
example --arch aarch64 --os macos

​
Workspace

​
$workingDir
string
The current working directory.
​
$workspaceRoot
string
Absolute file path to the workspace root.
moon.yml
tasks:
  build:
    command: 'example --cwd $workspaceRoot'

​
Project

Most values are derived from settings in moon.*. When a setting is not defined, the variable defaults to “unknown” (for enums) or an empty string.
​
$language
string
Programming language the project is written in, as defined with language.
​
$project
string
ID of the project that owns the currently running task.
​
$projectAlias
string
Alias of the project that owns the currently running task.
​
$projectAliases
string
Comma-separated list of all project aliases.
​
$projectChannel
string
The discussion channel for the project, as defined with project.channel.
​
$projectLayer
string
The project layer, as defined with layer.
​
$projectTitle
string
The human-readable name of the project, as defined with project.title.
​
$projectOwner
string
The owner of the project, as defined with project.owner.
​
$projectRoot
string
Absolute file path to the project root.
​
$projectSource
string
Relative file path from the workspace root to the project root.
​
$projectStack
string
The stack of the project, as defined with stack.
moon.yml
tasks:
  build:
    command: 'build --project $project --lang $language'

​
Task

​
$target
string
Fully-qualified target that is currently running (e.g., app:build).
​
$task
string
ID of the task that is currently running. Does not include the project ID.
​
$taskToolchain
string
The toolchain that the task will run against.
​
$taskToolchains
string
Comma-separated list of all toolchains for the task.
​
$taskType
string
The type of task, based on its configured settings.
moon.yml
tasks:
  build:
    command: 'example $target'
Expands to: 
example web:build

​
Date/Time

​
$date
string
The current date in the format of YYYY-MM-DD.
​
$datetime
string
The current date and time in the format of YYYY-MM-DD_HH:MM:SS.
​
$time
string
The current time in the format of HH:MM:SS.
​
$timestamp
string
The current date and time as a UNIX timestamp in seconds.
moon.yml
tasks:
  build:
    command: 'build --date $date --timestamp $timestamp'

​
VCS

​
$vcsBranch
string
The current branch.
​
$vcsRepository
string
The repository slug, in the format of owner/repo.
​
$vcsRevision
string
The current revision (commit hash, etc).
moon.yml
tasks:
  build:
    command: 'build --branch $vcsBranch --commit $vcsRevision'

​
Token expansion

Tokens are expanded during task execution through the TokenExpander which:
  1. Scans the task configuration - Identifies all tokens in command, args, env, inputs, and outputs
  2. Validates token usage - Ensures tokens are used in valid scopes
  3. Expands functions - Replaces function tokens with their expanded values
  4. Substitutes variables - Replaces variable tokens with their actual values
  5. Resolves paths - Converts relative paths to appropriate formats based on task settings

​
Scope validation

Different tokens are valid in different contexts:
  • Command scope - Only certain variables allowed
  • Args scope - Functions and variables allowed
  • Env scope - Functions and variables allowed
  • Inputs scope - File group functions and specific tokens
  • Outputs scope - File group functions and specific tokens
If you use a token in an invalid scope, moon will display an error.

​
Path resolution

When tokens expand to file paths, they are resolved based on:
  • Task’s runFromWorkspaceRoot setting - Determines if paths are relative to workspace or project
  • Operating system - Adjusts path separators and formats
  • Negated globs - Preserves ! prefix for exclusion patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us