Tokens

Tokens are variables and functions that can be used by command, args, env (>= v1.12), 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 as it takes a single argument, starts with an @, and is formatted as @name(arg). The following token functions are available, grouped by their functionality.

caution

Token functions must be the only content within a value, as they expand to multiple files. 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

Usable in args, env, inputs, and 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 merely exists for reusability purposes.

fileGroups:
  storybook:
    - '.storybook/**/*'
    - 'src/**/*'
    - '**/*.stories.*'

# Configured as
tasks:
  build:
    command: 'build-storybook'
    inputs:
      - '@group(storybook)'
  start:
    command: 'start-storybook'
    inputs:
      - '@group(storybook)'

# Resolves to
tasks:
  build:
    command: 'build-storybook'
    inputs:
      - '/path/to/project/.storybook/**/*'
      - '/path/to/project/src/**/*'
  start:
    command: 'start-storybook'
    inputs:
      - '/path/to/project/.storybook/**/*'
      - '/path/to/project/src/**/*'

@dirs

Usable in args, env, inputs, and 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 within the file group, it will aggregate all directories found.

warning

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.

fileGroups:
  lintable:
    - 'src'
    - 'tests'
    - 'scripts'
    - '*.config.js'

# Configured as
tasks:
  lint:
    command: 'eslint @dirs(lintable) --color'
    inputs:
      - '@dirs(lintable)'

# Resolves to
tasks:
  lint:
    command:
      - 'eslint'
      - 'src'
      - 'tests'
      - 'scripts'
      - '--color'
    inputs:
      - '/path/to/project/src'
      - '/path/to/project/tests'
      - '/path/to/project/scripts'

@files

Usable in args, env, inputs, and 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 within the file group, it will aggregate all files found.

warning

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.

fileGroups:
  config:
    - '*.config.js'
    - 'package.json'

# Configured as
tasks:
  build:
    command: 'webpack build @files(config)'
    inputs:
      - '@files(config)'

# Resolves to
tasks:
  build:
    command:
      - 'webpack'
      - 'build'
      - 'babel.config.js'
      - 'webpack.config.js'
      - 'package.json'
    inputs:
      - '/path/to/project/babel.config.js'
      - '/path/to/project/webpack.config.js'
      - '/path/to/project/package.json'

@globs

Usable in args, env, inputs, and 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 within the file group, it will be ignored.

fileGroups:
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'

# Configured as
tasks:
  test:
    command: 'jest --testMatch @globs(tests)'
    inputs:
      - '@globs(tests)'

# Resolves to
tasks:
  test:
    command:
      - 'jest'
      - '--testMatch'
      - 'tests/**/*'
      - '**/__tests__/**/*'
    inputs:
      - '/path/to/project/tests/**/*'
      - '/path/to/project/**/__tests__/**/*'

@root

Usable in args, env, inputs, and 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 within the file group, it will walk the file system and aggregate all directories found before reducing.

fileGroups:
  sources:
    - 'src/app'
    - 'src/packages'
    - 'src/scripts'

# Configured as
tasks:
  format:
    command: 'prettier --write @root(sources)'
    inputs:
      - '@root(sources)'

# Resolves to
tasks:
  format:
    command:
      - 'prettier'
      - '--write'
      - 'src'
    inputs:
      - '/path/to/project/src'

When there's no directies, or too many directories, this function will return the project root using ..

@envsv1.21.0

Usable in inputs.

The @envs(file_group) token will be replaced with all environment variables that have been configured in the group of the provided name.

fileGroups:
  sources:
    - 'src/**/*'
    - '$NODE_ENV'

# Configured as
tasks:
  build:
    command: 'vite build'
    inputs:
      - '@envs(sources)'


# Resolves to
tasks:
  build:
    command: 'vite build'
    inputs:
      - '$NODE_ENV'

Inputs & outputs

@in

Usable in 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, instead of returning the expanded list of files.

# Configured as
tasks:
  build:
    command:
      - 'babel'
      - '--copy-files'
      - '--config-file'
      - '@in(1)'
      - '@in(0)'
    inputs:
      - 'src'
      - 'babel.config.js'

# Resolves to
tasks:
  build:
    command:
      - 'babel'
      - '--copy-files'
      - '--config-file'
      - 'babel.config.js'
      - 'src'
    inputs:
      - '/path/to/project/src'
      - '/path/to/project/babel.config.js'

@out

Usable in args only.

The @out(index) token will be replaced with a single path, derived from outputs by numerical index. If a token function is referenced by index, the process will fail, as it requires literal folder and file paths.

# Configured as
tasks:
  build:
    command:
      - 'babel'
      - '.'
      - '--out-dir'
      - '@out(0)'
    outputs:
      - 'lib'

# Resolves to
tasks:
  build:
    command:
      - 'babel'
      - '.'
      - '--out-dir'
      - 'lib'
    outputs:
      - '/path/to/project/lib'

Variables

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

Workspace

$workspaceRoot

Absolute file path to the workspace root.

# Configured as
tasks:
  build:
    command:
      - 'example'
      - '--cwd'
      - '$workspaceRoot'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--cwd'
      - '/path/to/repo'

Project

$language

Programming language the project is written in, as defined in moon.yml. If the project has not defined the language setting, or does not have a config, this defaults to "unknown".

# Configured as
tasks:
  build:
    command: 'example debug $language'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - 'debug'
      - 'node'

$project

ID/name of the project that owns the currently running task, as defined in .moon/workspace.yml.

# Configured as
tasks:
  build:
    command: 'example --project $project'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--project'
      - 'web'

$projectAlias

Alias of the project that owns the currently running task. If not enabled, or no alias exists for the project, this will return an empty string.

# Configured as
tasks:
  build:
    command: 'example --projectAlias $projectAlias'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--projectAlias'
      - '@web/app'

$projectRoot

Absolute file path to the project root.

# Configured as
tasks:
  build:
    command: 'example --cwd $projectRoot'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--cwd'
      - '/path/to/repo/apps/web'

$projectSource

Relative file path from the workspace root to the project root, as defined in .moon/workspace.yml.

# Configured as
tasks:
  build:
    command:
      - 'example'
      - '--cache-dir'
      - '../../.cache/$projectSource'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--cache-dir'
      - '../../.cache/apps/web'

$projectStackv1.22.0

The stack of the project, as defined in moon.yml. If the project has not defined the stack setting, or does not have a config, this defaults to "unknown".

# Configured as
tasks:
  build:
    command: 'example debug $projectStack'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - 'debug'
      - 'backend'

$projectType

The type of project, as defined in moon.yml. If the project has not defined the type setting, or does not have a config, this defaults to "unknown".

# Configured as
tasks:
  build:
    command: 'example debug $projectType'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - 'debug'
      - 'application'

Task

$target

Target that is currently running.

# Configured as
tasks:
  build:
    command: 'example $target'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - 'web:build'

$task

ID/name of the task that is currently running.

# Configured as
tasks:
  build:
    command: 'example --task=$task'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--task=build'

$taskPlatform

The platform that task will run against, as defined in moon.yml.

# Configured as
tasks:
  build:
    command: 'example --platform $taskPlatform'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--platform'
      - 'system'

$taskType

The type of task, based on its configured settings.

# Configured as
tasks:
  build:
    command: 'example --type $taskType'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--type'
      - 'build'

Date/Time

$date

The current date in the format of YYYY-MM-DD.

# Configured as
tasks:
  build:
    command: 'example --date $date'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--date'
      - '2023-03-17'

$time

The current time in the format of HH:MM:SS.

# Configured as
tasks:
  build:
    command: 'example --time $time'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--time'
      - '14:05:10'

$datetime

The current date and time in the format of YYYY-MM-DD_HH:MM:SS.

# Configured as
tasks:
  build:
    command: 'example --datetime $datetime'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--datetime'
      - '2023-03-17_14:05:10'

$timestamp

The current date and time as a UNIX timestamp in seconds.

# Configured as
tasks:
  build:
    command: 'example --timestamp $timestamp'

# Resolves to
tasks:
  build:
    command:
      - 'example'
      - '--timestamp'
      - '1679087127'