---
title: moon
toc_max_heading_level: 6
---

import HeadingApiLink from '@site/src/components/Docs/HeadingApiLink';
import RequiredLabel from '@site/src/components/Docs/RequiredLabel';
import VersionLabel from '@site/src/components/Docs/VersionLabel';

The `moon.*` configuration file _is not required_ but can be used to define additional metadata for
a project, override inherited tasks, and more at the project-level. When used, this file must exist
in a project's root, as configured in [`projects`](./workspace#projects).

## `dependsOn`

<HeadingApiLink to="/api/types/interface/ProjectConfig#dependsOn" />

Explicitly defines _other_ projects that _this_ project depends on, primarily when generating the
project and task graphs. The most common use case for this is building those projects _before_
building this one. When defined, this setting requires an array of project names, which are the keys
found in the [`projects`](./workspace#projects) map.

```yaml title="moon.yml"
dependsOn:
  - 'apiClients'
  - 'designSystem'
```

A dependency object can also be defined, where a specific `scope` can be assigned, which accepts
"production" (default), "development", "build", or "peer".

```yaml title="moon.yml"
dependsOn:
  - id: 'apiClients'
    scope: 'production'
  - id: 'designSystem'
    scope: 'peer'
```

> Learn more about [implicit and explicit dependencies](../concepts/project#dependencies).

## Metadata

## `id`<VersionLabel version="1.18.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#id" />

Overrides the name (identifier) of the project, which was configured in or derived from the
[`projects`](./workspace#projects) setting in [`.moon/workspace.*`](./workspace). This setting is
useful when using glob based project location, and want to avoid using the folder name as the
project name.

```yaml title="moon.yml"
id: 'custom-id'
```

:::info

All references to the project must use the new identifier, including project and task dependencies.

:::

## `language`

<HeadingApiLink to="/api/types/interface/ProjectConfig#language" />

The primary programming language the project is written in. This setting is required for
[task inheritance](./tasks), editor extensions, and more. Supports the following values:

- `bash` - A [Bash](<https://en.wikipedia.org/wiki/Bash_(Unix_shell)>) based project (Unix only).
- `batch` - A [Batch](https://en.wikibooks.org/wiki/Windows_Batch_Scripting)/PowerShell based
  project (Windows only).
- `go` - A [Go](https://go.dev/) based project.
- `javascript` - A [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) based
  project.
- `php` - A [PHP](https://www.php.net) based project.
- `python` - A [Python](https://www.python.org/) based project.
- `ruby` - A [Ruby](https://www.ruby-lang.org/en/) based project.
- `rust` - A [Rust](https://www.rust-lang.org/) based project.
- `typescript` - A [TypeScript](https://www.typescriptlang.org/) based project.
- `unknown` (default) - When not configured or inferred.
- `*` - A custom language. Values will be converted to kebab-case.

```yaml title="moon.yml"
language: 'javascript'

# Custom
language: 'kotlin'
```

> For convenience, when this setting is not defined, moon will attempt to detect the language based
> on configuration files found in the project root. This only applies to non-custom languages!

## `owners`<VersionLabel version="1.8.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#owners" />

Defines ownership of source code within the current project, by mapping file system paths to owners.
An owner is either a user, team, or group.

Currently supports
[GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners),
[GitLab](https://docs.gitlab.com/ee/user/project/codeowners/reference.html), and
[Bitbucket](https://marketplace.atlassian.com/apps/1218598/code-owners-for-bitbucket?tab=overview&hosting=cloud)
(via app).

### `customGroups`<RequiredLabel text="Bitbucket" />

<HeadingApiLink to="/api/types/interface/OwnersConfig#customGroups" />

When using the
[Code Owners for Bitbucket](https://marketplace.atlassian.com/apps/1218598/code-owners-for-bitbucket?tab=overview&hosting=cloud)
app, this setting provides a way to define custom groups that will be injected at the top of the
`CODEOWNERS` file. These groups _must_ be unique across all projects.

```yaml title="moon.yml" {2,3}
owners:
  customGroups:
    '@@@backend': ['@"user name"', '@@team']
```

### `defaultOwner`

<HeadingApiLink to="/api/types/interface/OwnersConfig#defaultOwner" />

The default owner for all [`paths`](#paths). This setting is optional in some cases but helps to
avoid unnecessary repetition.

```yaml title="moon.yml" {2}
owners:
  defaultOwner: '@frontend'
```

### `optional`<RequiredLabel text="GitLab" />

<HeadingApiLink to="/api/types/interface/OwnersConfig#optional" />

For GitLab, marks the project's
[code owners section](https://docs.gitlab.com/ee/user/project/codeowners/reference.html#optional-sections)
as optional. Defaults to `false`.

```yaml title="moon.yml" {2}
owners:
  optional: true
```

### `paths`

<HeadingApiLink to="/api/types/interface/OwnersConfig#paths" />

The primary setting for defining ownership of source code within the current project. This setting
supports 2 formats, the first being a list of file paths relative from the current project. This
format requires [`defaultOwner`](#defaultowner) to be defined, and only supports 1 owner for every
path (the default owner).

```yaml title="moon.yml" {3-6}
owners:
  defaultOwner: '@frontend'
  paths:
    - '**/*.ts'
    - '**/*.tsx'
    - '*.config.js'
```

The second format provides far more granularity, allowing for multiple owners per path. This format
requires a map, where the key is a file path relative from the current project, and the value is a
list of owners. Paths with an empty list of owners will fallback to [`defaultOwner`](#defaultowner).

```yaml title="moon.yml" {3-6}
owners:
  defaultOwner: '@frontend'
  paths:
    '**/*.rs': ['@backend']
    '**/*.js': []
    '*.config.js': ['@frontend', '@frontend-infra']
```

> The syntax for owners is dependent on the provider you are using for version control (GitHub,
> GitLab, Bitbucket). moon provides no validation or guarantees that these are correct.

### `requiredApprovals`<RequiredLabel text="Bitbucket / GitLab" />

<HeadingApiLink to="/api/types/interface/OwnersConfig#requiredApprovals" />

Requires a specific number of approvals for a pull/merge request to be satisfied. Defaults to `1`.

- For Bitbucket, defines the
  [`Check()` condition](https://docs.mibexsoftware.com/codeowners/merge-checks#MergeChecks-2.MergeChecks:HowmanyoftheseCodeOwnersneedtoapprovebeforeapullrequestcanbemerged?)
  when using a [`defaultOwner`](#defaultowner).
- For GitLab, defines a requirement on the
  [code owners section](https://docs.gitlab.com/ee/user/project/codeowners/reference.html#sections-requiring-multiple-approvals).

```yaml title="moon.yml" {2}
owners:
  requiredApprovals: 2
```

## `layer`

<HeadingApiLink to="/api/types/interface/ProjectConfig#layer" />

The layer within a [stack](#stack). Supports the following values:

- `application` - An application of any kind.
- `automation` - An automated testing suite, like E2E, integration, or visual tests.
  <VersionLabel version="1.16.0" />
- `configuration` - Configuration files or infrastructure.
  <VersionLabel version="1.22.0" />
- `library` - A self-contained, shareable, and publishable set of code.
- `scaffolding` - Templates or generators for scaffolding.
  <VersionLabel version="1.22.0" />
- `tool` - An internal tool, CLI, one-off script, etc.
- `unknown` (default) - When not configured.

```yaml title="moon.yml"
layer: 'application'
```

:::info

The project layer is used in [task inheritance](../concepts/task-inheritance),
[constraints and boundaries](./workspace#constraints), editor extensions, and more!

:::

## `project`

<HeadingApiLink to="/api/types/interface/ProjectConfig#project" />

The `project` setting defines metadata about the project itself.

```yaml title="moon.yml"
project:
  title: 'moon'
  description: 'A monorepo management tool.'
  channel: '#moon'
  owner: 'infra.platform'
  maintainers: ['miles.johnson']
```

The information listed within `project` is purely informational and primarily displayed within the
CLI. However, this setting exists for you, your team, and your company, as a means to identify and
organize all projects. Feel free to build your own tooling around these settings!

### `channel`

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#channel" />

The Slack, Discord, Teams, IRC, etc channel name (with leading #) in which to discuss the project.

### `description`<RequiredLabel />

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#description" />

A description of what the project does and aims to achieve. Be as descriptive as possible, as this
is the kind of information search engines would index on.

### `maintainers`

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#maintainers" />

A list of people/developers that maintain the project, review code changes, and can provide support.
Can be a name, email, LDAP name, GitHub username, etc, the choice is yours.

### `title`

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#name" />

A human readable name of the project. This is _different_ from the unique project name configured in
[`projects`](./workspace#projects).

### `owner`

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#owner" />

The team or organization that owns the project. Can be a title, LDAP name, GitHub team, etc. We
suggest _not_ listing people/developers as the owner, use [maintainers](#maintainers) instead.

### Custom fields<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/ProjectMetadataConfig#metadata" />

Additional fields can be configured as custom metadata to associate to this project. Supports all
value types that are valid JSON.

```yaml title="moon.yml"
project:
  # ...
  deprecated: true
```

## `stack`<VersionLabel version="1.22.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#stack" />

The technology stack this project belongs to, primarily for categorization. Supports the following
values:

- `backend` - Server-side APIs, etc.
- `data` - Data sources, database layers, etc. <VersionLabel version="2.0.0" />
- `frontend` - Client-side user interfaces, etc.
- `infrastructure` - Cloud/server infrastructure, Docker, etc.
- `systems` - Low-level systems programming.
- `unknown` (default) - When not configured.

```yaml title="moon.yml"
stack: 'frontend'
```

:::info

The project stack is also used in [constraints and boundaries](./workspace#constraints)!

:::

## `tags`

<HeadingApiLink to="/api/types/interface/ProjectConfig#tags" />

Tags are a simple mechanism for categorizing projects. They can be used to group projects together
for [easier querying](../commands/query/projects), enforcing of
[project boundaries and constraints](./workspace#constraints),
[task inheritance](../concepts/task-inheritance), and more.

```yaml title="moon.yml"
tags:
  - 'react'
  - 'prisma'
```

## Integrations

## `docker`<VersionLabel version="1.27.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#docker" />

Configures Docker integration for the current project.

### `file`

<HeadingApiLink to="/api/types/interface/ProjectDockerConfig#file" />

Configures the `Dockerfile` generation process when [`moon docker file`](../commands/docker/file) is
executed.

#### `buildTask`

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#buildTask" />

The name of a task within the current project that will be used for building the project before
running it. If not defined, does nothing.

```yaml title="moon.yml" {3}
docker:
  file:
    buildTask: 'build'
```

#### `image`

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#image" />

The Docker image to use in the base stage. Defaults to an image based on the first detected
toolchain.

```yaml title="moon.yml" {3}
docker:
  file:
    image: 'node:latest'
```

#### `runPrune`<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#runPrune" />

Run the `moon docker prune` command after building the project, but before starting it. Defaults to
`true`.

```yaml title="moon.yml" {3}
docker:
  file:
    runPrune: false
```

#### `runSetup`<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#runSetup" />

Run the `moon docker setup` command after scaffolding, but before building the project. Defaults to
`true`.

```yaml title="moon.yml" {3}
docker:
  file:
    runSetup: false
```

#### `startTask`

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#startTask" />

The name of a task within the current project that will run the project after it has been built (if
required). This task will be used as `CMD` within the `Dockerfile`.

```yaml title="moon.yml" {3}
docker:
  file:
    startTask: 'start'
```

#### `template`<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/ProjectDockerFileConfig#template" />

A custom template file, relative from the workspace root, to use when rendering the `Dockerfile`.
Powered by Tera.

```yaml title="moon.yml" {3}
docker:
  file:
    template: 'templates/Dockerfile.tera'
```

### `scaffold`

<HeadingApiLink to="/api/types/interface/ProjectDockerConfig#scaffold" />

Configures aspects of the Docker scaffolding process when
[`moon docker scaffold`](../commands/docker/scaffold) is executed. Only applies to the
[sources skeleton](../commands/docker/scaffold#sources).

#### `configsPhaseGlobs`

<HeadingApiLink to="/api/types/interface/ProjectDockerScaffoldConfig#configsPhaseGlobs" />

List of globs in which to copy project-relative files into the `.moon/docker/configs` skeleton. When
not defined, defaults to `**/*`. Applies to both project and workspace level scaffolding.

```yaml title="moon.yml" {3,4}
docker:
  scaffold:
    configsPhaseGlobs:
      - '*.json'
```

#### `sourcesPhaseGlobs`

<HeadingApiLink to="/api/types/interface/ProjectDockerScaffoldConfig#sourcesPhaseGlobs" />

List of globs in which to copy project-relative files into the `.moon/docker/sources` skeleton. When
not defined, defaults to `**/*`. Applies to both project and workspace level scaffolding.

```yaml title="moon.yml" {3,4}
docker:
  scaffold:
    sourcesPhaseGlobs:
      - 'src/**/*'
```

## Tasks

## `env`

<HeadingApiLink to="/api/types/interface/ProjectConfig#env" />

The `env` field is map of strings that are passed as environment variables to _all tasks_ within the
current project. Project-level variables will not override task-level variables of the same name.

```yaml title="moon.yml"
env:
  NODE_ENV: 'production'
```

> View the task [`env`](#env-1) setting for more usage examples and information.

## `fileGroups`

<HeadingApiLink to="/api/types/interface/ProjectConfig#fileGroups" />

Defines [file groups](../concepts/file-group) to be used by local tasks. By default, this setting
_is not required_ for the following reasons:

- File groups are an optional feature, and are designed for advanced use cases.
- File groups defined in [`.moon/tasks/**/*`](./tasks) will be inherited by all projects.

When defined this setting requires a map, where the key is the file group name, and the value is a
list of [globs or file paths](../concepts/file-pattern), or environment variables. Globs and paths
are [relative to a project](../concepts/file-pattern#project-relative) (even when defined
[globally](./tasks)).

```yaml title="moon.yml"
# Example groups
fileGroups:
  configs:
    - '*.config.{js,cjs,mjs}'
    - '*.json'
  sources:
    - 'src/**/*'
    - 'types/**/*'
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'
  assets:
    - 'assets/**/*'
    - 'images/**/*'
    - 'static/**/*'
    - '**/*.{scss,css}'
```

Once your groups have been defined, you can reference them within [`args`](#args),
[`inputs`](#inputs), [`outputs`](#outputs), and more, using
[token functions and variables](../concepts/token).

```yaml title="moon.yml"
tasks:
  build:
    command: 'vite build'
    inputs:
      - '@group(configs)'
      - '@group(sources)'
```

## `tasks`

<HeadingApiLink to="/api/types/interface/ProjectConfig#tasks" />

Tasks are actions that are ran within the context of a [project](../concepts/project), and commonly
wrap an npm binary or system command. This setting requires a map, where the key is a unique name
for the task, and the value is an object of task parameters.

```yaml title="moon.yml"
tasks:
  format:
    command: 'prettier'
  lint:
    command: 'eslint'
  test:
    command: 'jest'
  typecheck:
    command: 'tsc'
```

### `extends`<VersionLabel version="1.12.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#extends" />

The `extends` field can be used to extend the settings from a sibling task within the same project,
or [inherited from the global scope](../concepts/task-inheritance). This is useful for composing
similar tasks with different arguments or options.

When extending another task, the same
[merge strategies](../concepts/task-inheritance#merge-strategies) used for inheritance are applied.

```yaml title="moon.yml" {8}
tasks:
  lint:
    command: 'eslint .'
    inputs:
      - 'src/**/*'

  lint-fix:
    extends: 'lint'
    args: '--fix'
    preset: 'utility'
```

### `description`<VersionLabel version="1.22.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#description" />

A human-readable description of what the task does. This information is displayed within the
[`moon project`](../commands/project) and [`moon task`](../commands/task) commands.

```yaml title="moon.yml" {3}
tasks:
  build:
    description: 'Builds the project using Vite'
    command: 'vite build'
```

### `command`

<HeadingApiLink to="/api/types/interface/TaskConfig#command" />

The `command` field is a _single_ command to execute for the task, including the command binary/name
(must be first) and any optional [arguments](#args). This field supports task inheritance and
merging of arguments.

This setting can be defined using a string, or an array of strings. We suggest using arrays when
dealing with many args, or the args string cannot be parsed easily.

```yaml title="moon.yml" {4,6-9}
tasks:
  format:
    # Using a string
    command: 'prettier --check .'
    # Using an array
    command:
      - 'prettier'
      - '--check'
      - '.'
```

:::info

If you need to support pipes, redirects, or multiple commands, use [`script`](#script) instead.
Learn more about [commands vs scripts](../concepts/task#commands-vs-scripts).

:::

### `args`

<HeadingApiLink to="/api/types/interface/TaskConfig#args" />

The `args` field is a collection of _additional_ arguments to append to the [`command`](#command)
when executing the task. This field exists purely to provide arguments for
[inherited tasks](./tasks#tasks).

This setting can be defined using a string, or an array of strings. We suggest using arrays when
dealing with many args, or the args string cannot be parsed easily.

```yaml title="moon.yml" {5,7-10}
tasks:
  test:
    command: 'jest'
    # Using a string
    args: '--color --maxWorkers 3'
    # Using an array
    args:
      - '--color'
      - '--maxWorkers'
      - '3'
```

However, for the array approach to work correctly, each argument _must_ be its own distinct item,
including argument values. For example:

```yaml title="moon.yml"
tasks:
  test:
    command: 'jest'
    args:
      # Valid
      - '--maxWorkers'
      - '3'
      # Also valid
      - '--maxWorkers=3'
      # Invalid
      - '--maxWorkers 3'
```

### `checks`<VersionLabel version="2.4.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#checks" />

The `checks` field is a list of shell scripts that are executed _before_ the task runs. Depending on
the type of check and the result of its script, the task may fail, be skipped, or continue as
normal. This is useful for asserting preconditions, avoiding redundant work, or invalidating the
cache based on external state.

There are three types of checks, denoted by the `check` field. When a check is defined as a plain
string, it is treated as a [`requirement`](#requirement) by default.

```yaml title="moon.yml" {4-12}
tasks:
  deploy:
    command: './deploy.sh'
    checks:
      # A string is shorthand for a requirement
      - 'command -v aws'
      # Or the expanded object form
      - check: 'condition'
        script: './scripts/already-deployed.sh'
      - check: 'fingerprint'
        script: 'aws --version'
```

Checks support [task inheritance](../concepts/task-inheritance), and the merge behavior can be
customized with the [`mergeChecks`](#mergechecks) option.

#### `requirement`

A `requirement` check must _pass_ (exit code 0) for the task to run. If the script fails, the task
fails and does _not_ execute. This is the default type when a check is defined as a string.

```yaml title="moon.yml" {5-7}
tasks:
  build:
    command: 'cargo build'
    checks:
      - check: 'requirement'
        script: 'rustc --version'
```

#### `condition`

A `condition` check is used to _skip_ a task. When _all_ condition checks pass (exit code 0), the
task is skipped instead of running. If any condition fails, the task runs as normal. This is useful
for idempotency checks, where re-running the task would be redundant.

```yaml title="moon.yml" {5-7}
tasks:
  migrate:
    command: './migrate.sh'
    checks:
      - check: 'condition'
        script: './scripts/is-migrated.sh'
```

#### `fingerprint`

A `fingerprint` check always runs alongside the task, and its output is mixed into the task's
[hash](../concepts/cache). This invalidates the cache when the script's output changes, even if none
of the task's declared [`inputs`](#inputs) changed — useful for tracking external state like tool
versions.

The `hash` field controls what portion of the script's execution is hashed. It accepts a boolean
(hash all output), or one of `exit-code`, `stdout`, or `stderr`. Defaults to `true`.

```yaml title="moon.yml" {5-8}
tasks:
  build:
    command: 'vite build'
    checks:
      - check: 'fingerprint'
        script: 'node --version'
        # Only hash stdout, not the exit code or stderr
        hash: 'stdout'
```

### `deps`

<HeadingApiLink to="/api/types/interface/TaskConfig#deps" />

The `deps` field is a list of other tasks (known as [targets](../concepts/target)), either within
this project or found in another project, that will be executed _before_ this task. It achieves this
by generating a directed task graph based on the project graph.

```yaml title="moon.yml" {4-8}
tasks:
  build:
    command: 'webpack'
    deps:
      - 'apiClients:build'
      - 'designSystem:build'
      # A task within the current project
      - 'codegen'
```

#### Args & env

Furthermore, for each dependency target, you can configure additional command line arguments and
environment variables that'll be passed to the dependent task when it is ran. The `args` field
supports a list of strings, while `env` is an object of key-value pairs.

```yaml title="moon.yml" {4-8}
tasks:
  build:
    command: 'webpack'
    deps:
      - target: 'apiClients:build'
        args: ['--env', 'production']
        env:
          NODE_ENV: 'production'
```

> Dependencies of inherited tasks will be excluded and renamed according to the
> [`workspace.inheritedTasks`](#inheritedtasks) setting. This process _only_ uses filters from the
> current project, and not filters from dependent projects. Furthermore, `args` and `env` are not
> deeply merged.

#### Optional

By default, all dependencies are required to exist when tasks are being built and expanded, but this
isn't always true when dealing with composition and inheritance. For dependencies that may not exist
based on what's inherited, you can mark it as `optional`.

```yaml title="moon.yml" {4-6}
tasks:
  build:
    command: 'webpack'
    deps:
      - target: 'apiClients:build'
        optional: true
```

#### Cache strategy<VersionLabel version="2.3.0" />

The `cacheStrategy` field controls how a dependency's changes invalidate the current task's cache.

When omitted, the strategy is chosen for you based on whether the dependency declares outputs:

- A dependency **with** outputs (e.g. a `build` task) defaults to `hash` — any change to the
  dependency invalidates this task.
- A dependency **without** outputs (e.g. a `lint` or `test` task) defaults to `ignored` — the
  dependency is treated as a sequencing edge only and its changes never invalidate this task.

You can override the default explicitly with one of:

- `hash` - Use the dependency task's hash for cache invalidation. The current task is invalidated
  whenever the dependency changes (inputs, command, args, env, etc.).
- `ignored` - Ignore the dependency task's hash for cache invalidation. The current task is
  **never** invalidated by this dependency's changes.
- `outputs` - Use the dependency task's outputs instead of its hash for cache invalidation. The
  current task is only invalidated when the dependency's outputs change, not when its inputs change.
  Useful for build tasks where you only care about a dependency's outputs, not what triggered the
  dependency to run.

```yaml title="moon.yml" {4-6}
tasks:
  build:
    command: 'webpack'
    deps:
      - target: 'apiClients:build'
        cacheStrategy: 'outputs'
```

The most common use case for `cacheStrategy: outputs` is when you have build dependencies. Instead
of rebuilding a project whenever an upstream task's inputs change, you rebuild only when the
upstream task's outputs change:

```yaml title="moon.yml"
tasks:
  build:
    command: 'npm run build'
    inputs:
      - 'src/**/*'
    outputs:
      - 'dist/**/*'
    deps:
      # Only invalidate if the dependency's dist/ changes, not if its src/ or other inputs change
      - target: '^:build'
        cacheStrategy: 'outputs'
```

### `env`

<HeadingApiLink to="/api/types/interface/TaskConfig#env" />

The `env` field is map of strings that are passed as environment variables when running the command.
Variables defined here will take precedence over those loaded with [`envFile`](#envfile).

```yaml title="moon.yml" {4,5}
tasks:
  build:
    command: 'webpack'
    env:
      NODE_ENV: 'production'
```

Variables also support substitution using the syntax `${VAR_NAME}`. When using substitution, only
variables in the current process can be referenced, and not those currently defined in `env`.

```yaml title="moon.yml" {4,5}
tasks:
  build:
    command: 'webpack'
    env:
      APP_TARGET: '${REGION}-${ENVIRONMENT}'
```

### `inputs`

<HeadingApiLink to="/api/types/interface/TaskConfig#inputs" />

The `inputs` field is a list of sources that calculate whether to execute this task based on the
environment and files that have been touched since the last time the task has been ran. If _not_
defined or inherited, then all files within a project are considered an input (`**/*`), excluding
root-level tasks.

Inputs support the following source types:

- Environment variables
- Environment variable wildcards
  <VersionLabel version="1.22.0" />
- Files, folders, and globs
- [Token functions and variables](../concepts/token)

```yaml title="moon.yml" {4-12}
tasks:
  lint:
    command: 'eslint'
    inputs:
      # Config files anywhere within the project
      - '**/.eslintignore'
      - '**/.eslintrc.js'
      # Config files at the workspace root
      - '/.eslintignore'
      - '/.eslintrc.js'
      # Tokens
      - '$projectRoot'
      - '@group(sources)'
```

#### Environment variables

Environment variables can be used as inputs and must start with a `$`. Wildcard variables can use
`*` to match any character.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      - '$FOO_CACHE'
      - '$FOO_*'
```

:::caution

When using an environment variable, we assume _it's not defined_ by default, and will trigger an
affected state when it _is_ defined. If the environment variable always exists, then the task will
always run and bypass the cache.

:::

#### File paths

File paths support
[project and workspace relative file/folder patterns](../concepts/file-pattern#project-relative).
They can be defined as a literal path, or a `file://` URI <VersionLabel inline version="1.39.0" />,
or as an object with a `file` property <VersionLabel inline version="1.39.0" />. Additionally, the
following parameters are supported as a URI query or as object fields:

- `content`, `match`, `matches` (`string`) - When determining affected state, will match against the
  file's content using the defined regex pattern, instead of relying on file existence.
- `optional` (`boolean`) - When hashing and set to `true` and the file is missing, will not log a
  warning. When set to `false` and the file is missing, will fail with an error. Defaults to logging
  a warning.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      # Literal paths
      - 'project/relative/file.js'
      - '/workspace/relative/file.js'
      # Using file protocol
      - 'file://project/relative/file.js?optional'
      - 'file:///workspace/relative/file.js?content=a|b|c'
      # Using an object
      - file: 'project/relative/file.js'
        optional: true
      - file: '/workspace/relative/file.js'
        content: 'a|b|c'
```

#### File groups<VersionLabel version="1.41.0" />

A file group input will reference the defined files/globs within from a file group in the current
project. It can be defined with a `group://` URI, or as an object with a `group` property.
Additionally, the following parameters are supported as a URI query or as object fields:

- `format`, `as` (`string`) - The format in which to gather the file group results. Supported values
  are `static` (default), `files`, `dirs`, `globs`, `envs`, and `root`.

```yaml title="moon.yml"
fileGroups:
  sources:
    - 'src/**/*'

tasks:
  build:
    # ...
    inputs:
      # Using group protocol
      - 'group://sources?format=dirs'
      # Using an object
      - group: 'sources'
        format: 'dirs'
```

#### Glob patterns

Glob patterns support
[project and workspace relative file/folder patterns](../concepts/file-pattern#project-relative).
They can be defined as a literal path, or a `glob://` URI <VersionLabel inline version="1.39.0" />,
or as an object with a `glob` property <VersionLabel inline version="1.39.0" />. Additionally, the
following parameters are supported as a URI query or as object fields:

- `cache` (`boolean`) - When gathering inputs for hashing, defines whether the glob results should
  be cached for the duration of the moon process. Defaults to `true`.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      # Literal paths
      - 'project/relative/file.*'
      - '/workspace/relative/**/*'
      # Using glob protocol
      - 'glob://project/relative/file.*?cache=false'
      - 'glob:///workspace/relative/**/*?cache'
      # Using an object
      - glob: 'project/relative/file.*'
        cache: false
      - glob: '/workspace/relative/**/*'
```

Globs can also be negated by prefixing the path with `!`, which will exclude all files that match
the glob.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      - '!**/*.md'
      - 'glob://!/workspace/relative/**/*'
      - glob: '!/workspace/relative/**/*'
```

:::warning

Glob patterns that contain `?`, for example `*.tsx?`, cannot be used in URI format, as it conflicts
with the query string syntax. Use the path or object format instead.

:::

:::danger

Be aware that files that match the glob, but are ignored via `.gitignore` (or similar), will _not_
be considered an input. To work around this, use explicit file inputs.

:::

#### External projects<VersionLabel version="1.41.0" />

Tasks can also depend on files and globs from other projects within the same workspace. This is
useful for handling cross-project relationships without needing to define explicit task
dependencies.

External projects can be defined as a `project://` URI, or as an object with a `project` property,
both of which require a project identifier, or `^` for all dependent projects. Additionally, the
following parameters are supported as a URI query or as object fields:

- `group`, `fileGroup` (`id`) - The name of a file group within the external project in which file
  and glob patterns will be used for matching. Takes precedence over `filter`.
- `filter` (`string[]`) - A list of
  [project relative glob patterns](../concepts/file-pattern#project-relative) that will be used for
  matching.

If neither `group` nor `filter` are defined, all files within the external project are considered a
match (`**/*`).

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      # Using project protocol
      - 'project://foo'
      - 'project://bar?group=sources'
      - 'project://baz?filter=src/**/*'
      # Using an object
      - project: 'foo'
      - project: 'bar'
        group: 'sources'
      - project: 'baz'
        filter: ['src/**/*']
```

### `outputs`

<HeadingApiLink to="/api/types/interface/TaskConfig#outputs" />

The `outputs` field is a list of [files and folders](../concepts/file-pattern#project-relative) that
are _created_ as a result of executing this task, typically from a build or compilation related
task. Outputs are necessary for [incremental caching and hydration](../concepts/cache). If you'd
prefer to avoid that functionality, omit this field.

#### File paths

File paths support
[project and workspace relative file/folder patterns](../concepts/file-pattern#project-relative).
They can be defined as a literal path, or a `file://` URI <VersionLabel inline version="1.41.0" />,
or as an object with a `file` property <VersionLabel inline version="1.41.0" />. Additionally, the
following parameters are supported as a URI query or as object fields:

- `optional` (`boolean`) - When archiving and set to `true` and the file is missing, will not fail
  with a missing output error. Defaults to `false`.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      # Literal paths
      - 'build/'
      # Using file protocol
      - 'file://build/'
      # Using an object
      - file: 'build/'
        optional: true
```

#### Glob patterns

Glob patterns support
[project and workspace relative file/folder patterns](../concepts/file-pattern#project-relative).
They can be defined as a literal path, or a `glob://` URI <VersionLabel inline version="1.41.0" />,
or as an object with a `glob` property <VersionLabel inline version="1.41.0" />. Additionally, the
following parameters are supported as a URI query or as object fields:

- `optional` (`boolean`) - When archiving and set to `true` and the glob produced no results, will
  not fail with a missing output error. Defaults to `false`.

```yaml title="moon.yml"
tasks:
  example:
    inputs:
      # Literal paths
      - 'build/**/*.js'
      - '!build/internal.js'
      # Using glob protocol
      - 'glob://build/**/*.js'
      # Using an object
      - glob: 'build/**/*.js'
```

:::warning

Glob patterns that contain `?`, for example `*.tsx?`, cannot be used in URI format, as it conflicts
with the query string syntax. Use the path or object format instead.

:::

:::danger

When using globs and moon hydrates an output (a cache hit), all files not matching the glob will be
**deleted**. Ensure that all files critical for the build to function correctly are included.

:::

### `preset`<VersionLabel version="1.28.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#preset" />

Applies the chosen preset to the task. A preset defines a collection of task options that will be
inherited as the default, and can then be overridden within the task itself. The following presets
are available:

- `server`
  - [`cache`](#cache) -> Turned off
  - [`outputStyle`](#outputstyle) -> Set to "stream"
  - [`persistent`](#persistent) -> Turned on
  - [`runInCI`](#runinci) -> Turned off
- `utility` <VersionLabel version="2.0.0" />
  - [`cache`](#cache) -> Turned off
  - [`interactive`](#interactive) -> Turned on
  - [`outputStyle`](#outputstyle) -> Set to "stream"
  - [`persistent`](#persistent) -> Turned off
  - [`runInCI`](#runinci) -> Skipped

Tasks named "dev", "start", or "serve" are marked as `server` automatically.

```yaml title="moon.yml" {5}
tasks:
  dev:
    command: 'webpack server'
    preset: 'server'
```

### `script`<VersionLabel version="1.27.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#script" />

The `script` field is _one or many_ commands to execute for the task, with support for pipes,
redirects, and more. This field does _not_ support task inheritance merging, and can only be defined
with a string.

If defined, will supersede [`command`](#command) and [`args`](#args).

```yaml title="moon.yml" {4,6,8,10}
tasks:
  exec:
    # Single command
    script: 'cp ./in ./out'
    # Multiple commands
    script: 'rm -rf ./out && cp ./in ./out'
    # Pipes
    script: 'ps aux | grep 3000'
    # Redirects
    script: './gen.sh > out.json'
```

:::info

If you need to support merging during task inheritance, use [`command`](#command) instead. Learn
more about [commands vs scripts](../concepts/task#commands-vs-scripts).

:::

### `tags`<VersionLabel version="2.3.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#tags" />

Tags are a simple mechanism for categorizing tasks. They can be used to group tasks together for
[easier querying](../commands/query/tasks), referencing within targets, and more.

```yaml title="moon.yml"
tasks:
  lint:
    command: 'eslint'
    tags:
      - 'quality'
      - 'ci'
```

### `toolchains`<VersionLabel version="1.31.0" />

<HeadingApiLink to="/api/types/interface/TaskConfig#toolchain" />

The `toolchain` field defines additional [toolchain(s)](../concepts/toolchain) the command runs on,
where to locate its executable, and more. By default, moon will set to a value based on the
project's [`language`](#language), default [`toolchains.default`](#toolchain-1), or via detection.

```yaml title="moon.yml" {4}
tasks:
  env:
    command: 'printenv'
    toolchains: 'system'
```

This setting also supports multiple values.

```yaml title="moon.yml" {4}
tasks:
  build:
    command: 'npm run build'
    toolchains: ['javascript', 'node', 'npm']
```

### `options`

<HeadingApiLink to="/api/types/interface/TaskConfig#options" />

The `options` field is an object of configurable options that can be used to modify the task and its
execution. The following fields can be provided, with merge related fields supporting all
[merge strategies](../concepts/task-inheritance#merge-strategies).

```yaml title="moon.yml"
tasks:
  typecheck:
    command: 'tsc --noEmit'
    options:
      mergeArgs: 'replace'
      runFromWorkspaceRoot: true
```

#### `affectedFiles`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#affectedFiles" />

When enabled and the [`--affected` option](../run-task#running-based-on-affected-files-only) is
provided, all affected files that match this task's [`inputs`](#inputs) will be passed as relative
file paths as command line arguments, and as a `MOON_AFFECTED_FILES` environment variable.

If there are no affected files, `.` (current directory) will be passed instead for arguments, and an
empty value for the environment variable. This functionality can be changed with the
[`affectedPassInputs`](#affectedpassinputs) setting.

```yaml title="moon.yml" {5,7,9}
tasks:
  lint:
    command: 'eslint'
    options:
      affectedFiles: true
      # Only pass args
      affectedFiles: 'args'
      # Only set env var
      affectedFiles: 'env'
```

:::caution

When using this option, ensure that explicit files or `.` _are not present_ in the [`args`](#args)
list. Furthermore, this functionality will only work if the task's command supports an arbitrary
list of files being passed as arguments.

:::

This setting also supports an object format with additional parameters. The `pass` field is
required, which accepts a value described above.

```yaml title="moon.yml" {5,7,9}
tasks:
  lint:
    command: 'eslint'
    options:
      affectedFiles:
        pass: 'args'
```

The following additional parameters are supported:

- `filter` (`boolean`) <VersionLabel version="2.1.0" /> - A list of glob patterns to filter the
  affected files list before passing to the task. Globs must start with `**` to match against
  absolute paths.
- `ignoreProjectBoundary` (`boolean`) <VersionLabel version="2.1.0" /> - When matching affected
  files, ignore the project boundary and include workspace relative files. Otherwise, only files
  within the project are matched. Defaults to `false`.
- `passDotWhenNoResults` (`boolean`) <VersionLabel version="2.1.0" /> - When no affected files are
  found, will pass `.` instead of an empty or no value. Defaults to `true`.
- `passInputsWhenNoMatch` (`boolean`) - When no affected files are found, will pass all configured
  [`inputs`](#inputs) as relative file paths instead. Defaults to `false`.

#### `allowFailure`<VersionLabel version="1.13.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#allowFailure" />

Allows a task to fail without failing the entire pipeline. When enabled, the following changes
occur:

- Other tasks _cannot_ depend on this task, as we can't ensure it's side-effect free.
- For [`moon run`](../commands/run), the process will not bail early and will run to completion.
- For [`moon ci`](../commands/ci), the process will not exit with a non-zero exit code, if the only
  failing tasks are allowed to fail.

```yaml title="moon.yml" {5}
tasks:
  lint:
    command: 'eslint'
    options:
      allowFailure: true
```

#### `cache`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#cache" />

Whether to cache the task's execution result using our [smart hashing](../concepts/cache#hashing)
system. If disabled, _will not_ create a cache hash, and _will not_ persist a task's
[outputs](#outputs). Supports the following values:

- `true` (default) - Cache the task's output.
- `false` - Do not cache the task's output.
- `local` - Only cache locally. <VersionLabel version="1.40.0" />
- `remote` - Only cache [remotely](../guides/remote-cache). <VersionLabel version="1.40.0" />

We suggest disabling caching when defining cleanup tasks, one-off scripts, or file system heavy
operations.

```yaml title="moon.yml" {5}
tasks:
  clean:
    command: 'rm -rf ./temp'
    options:
      cache: false
```

#### `cacheKey`<VersionLabel version="1.35.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#cacheKey" />

A custom key to include in the cache and task hashing process. Can be used to invalidate local and
remote caches.

```yaml title="moon.yml" {5}
tasks:
  build:
    command: 'some-costly-build'
    options:
      cacheKey: 'v1'
```

#### `cacheLifetime`<VersionLabel version="1.29.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#cacheLifetime" />

The lifetime in which a [cached task](#cache) will live before being marked as stale and re-running.
This applies to a task even if it does not produce [outputs](#outputs).

The lifetime can be configured in a human-readable string format, for example, `1 day`, `3 hr`,
`1m`, etc. If the lifetime is not defined, the cache will live forever, or until the task inputs are
touched.

```yaml title="moon.yml" {5}
tasks:
  build:
    command: 'some-costly-build'
    options:
      cacheLifetime: '1 day'
```

> String formats are powered by the
> [humantime](https://docs.rs/humantime/2.1.0/humantime/fn.parse_duration.html) crate.

#### `envFile`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#envFile" />

A boolean or path to a `.env` file (also know as dotenv file) that defines a collection of
[environment variables](#env-1) for the current task. Variables will be loaded on project creation,
but will _not_ override those defined in [`env`](#env-1).

Variables defined in the file support value substitution/expansion by wrapping the variable name in
curly brackets, such as `${VAR_NAME}`.

```yaml title="moon.yml" {6,8,10}
tasks:
  build:
    command: 'webpack'
    options:
      # Defaults to .env
      envFile: true
      # Or
      envFile: '.env.production'
      # Or from the workspace root
      envFile: '/.env.shared'
```

When set to `true`, moon will load the following files in order, with later files taking precedence
over earlier ones:

- `/.env`
- `/.env.local`
- `.env`
- `.env.local`
- `.env.<task_id>`
- `.env.<task_id>.local`

Additionally, a list of file paths can also be provided. When using a list, the order of the files
is important, as environment variables from all files will be aggregated into a single map, with
subsequent files taking precedence over previous ones. Once aggregated, the variables will be passed
to the task, but will _not_ override those defined in [`env`](#env-1).

```yaml title="moon.yml" {5-7}
tasks:
  build:
    command: 'webpack'
    options:
      envFile:
        - '.env'
        - '.env.production'
```

#### `inferInputs`<VersionLabel version="1.31.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#inferInputs" />

Automatically infer [inputs](#inputs) based on the following parameters configured within the task's
`command`, `script`, `args`, or `env`. Defaults to `false`.

- File/glob paths derived from [file group based token functions](../concepts/token#file-groups).
- Environment variables being substituted within a command or script.

```yaml title="moon.yml" {5}
tasks:
  build:
    # ...
    options:
      inferInputs: false
```

#### `internal`<VersionLabel version="1.23.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#internal" />

Marks the task as internal only. [Internal tasks](../concepts/task#internal-only) can not be
explicitly ran on the command line, but can be depended on by other tasks.

```yaml title="moon.yml" {5}
tasks:
  prepare:
    # ...
    options:
      internal: true
```

#### `interactive`<VersionLabel version="1.12.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#interactive" />

Marks the task as interactive. [Interactive tasks](../concepts/task#interactive) run in isolation so
that they can interact with stdin.

This setting also disables caching, turns of CI, and other functionality, similar to the
[`preset`](#preset) setting.

```yaml title="moon.yml" {5}
tasks:
  init:
    # ...
    options:
      interactive: true
```

#### `merge`<VersionLabel version="1.29.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#merge" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging [`args`](#args),
[`deps`](#deps), [`env`](#env-1), [`inputs`](#inputs), and [`outputs`](#outputs) with an inherited
task. This option can be overridden with the field specific merge options below.

#### `mergeArgs`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeArgs" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`args`](#args) list with an inherited task. Defaults to "append".

#### `mergeChecks`<VersionLabel version="2.4.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeChecks" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`checks`](#checks) list with an inherited task. Defaults to "append".

#### `mergeDeps`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeDeps" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`deps`](#deps) list with an inherited task. Defaults to "append".

#### `mergeEnv`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeEnv" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`env`](#env-1) map with an inherited task. Defaults to "append".

#### `mergeInputs`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeInputs" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`inputs`](#inputs) list with an inherited task. Defaults to "append".

#### `mergeOutputs`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeOutputs" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`outputs`](#outputs) list with an inherited task. Defaults to "append".

#### `mergeTags`<VersionLabel version="2.3.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeTags" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`tags`](#tags) list with an inherited task. Defaults to "append".

#### `mergeToolchains`<VersionLabel version="2.0.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mergeToolchains" />

The [strategy](../concepts/task-inheritance#merge-strategies) to use when merging the
[`toolchains`](#toolchains) list with an inherited task. Defaults to "append".

#### `mutex`<VersionLabel version="1.24.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#mutex" />

Creates an exclusive lock on a "virtual resource", preventing other tasks using the same "virtual
resource" from running concurrently.

If you have many tasks that require exclusive access to a resource that can't be tracked by moon
(like a database, an ignored file, a file that's not part of the project, or a remote resource) you
can use the `mutex` option to prevent them from running at the same time.

```yaml title="moon.yml" {5,10}
tasks:
  a:
    # ...
    options:
      mutex: 'virtual_resource_name'

  # b doesn't necessarily have to be in the same project
  b:
    # ...
    options:
      mutex: 'virtual_resource_name'
```

#### `os`<VersionLabel version="1.28.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#os" />

When defined, the task will _only_ run on the configured operating system. For other operating
systems, the task becomes a no-operation. Supports the values `linux`, `macos`, and `windows`.

Can be defined as a single value, or a list of values.

```yaml title="moon.yml" {5,10}
tasks:
  build-unix:
    # ...
    options:
      os: ['linux', 'macos']

  build-windows:
    # ...
    options:
      os: 'windows'
```

#### `outputStyle`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#outputStyle" />

Controls how stdout/stderr is displayed when the task is run as a _transitive (non-primary) target_.
Primary targets always display their output and ignore this setting. By default, this setting is not
defined and defers to the action pipeline, but can be overridden with one of the following values:

- `buffer` - Buffers output and displays after the task has exited (either success or failure).
- `buffer-only-failure` - Like `buffer`, but only displays on failures.
- `hash` - Ignores output and only displays the generated [hash](../concepts/cache#hashing).
- `none` - Ignores output.
- `stream` - Streams output directly to the terminal. Will prefix each line of output with the
  target.

```yaml title="moon.yml" {5}
tasks:
  test:
    # ...
    options:
      outputStyle: 'stream'
```

#### `persistent`<VersionLabel version="1.6.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#persistent" />

Marks the task as persistent (continuously running). [Persistent tasks](../concepts/task#persistent)
are handled differently than non-persistent tasks in the action graph. When running a target, all
persistent tasks are _ran last_ and _in parallel_, after all their dependencies have completed.

This is extremely useful for running a server (or a watcher) in the background while other tasks are
running.

```yaml title="moon.yml" {5}
tasks:
  dev:
    # ...
    options:
      persistent: true
```

> We suggest using the [`preset`](#preset) setting instead, which enables this setting, amongst
> other useful settings.

#### `priority`<VersionLabel version="1.35.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#priority" />

The priority level determines the position of the task within the action pipeline queue. A task with
a higher priority will run sooner rather than later, while still respecting the topological order.
Supports the following levels:

- `critical`
- `high`
- `normal` (default)
- `low`

```yaml title="moon.yml" {5}
tasks:
  build:
    # ...
    options:
      priority: 'high'
```

#### `retryCount`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#retryCount" />

The number of attempts the task will retry execution before returning a failure. This is especially
useful for flaky tasks. Defaults to `0`.

```yaml title="moon.yml" {5}
tasks:
  test:
    # ...
    options:
      retryCount: 3
```

#### `runDepsInParallel`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#runDepsInParallel" />

Whether to run the task's direct [`deps`](#deps) in parallel or serial (in order). Defaults to
`true`.

When disabled, each dependency runs after the previous one completes. This ordering applies to a
dependency's entire dependency subtree, so transitive dependencies (dependencies of dependencies)
also run after the preceding direct dependency — not only the direct dependency itself.

```yaml title="moon.yml" {8}
tasks:
  start:
    # ...
    deps:
      - '~:clean'
      - '~:build'
    options:
      runDepsInParallel: false
```

:::caution

Because tasks run only once per pipeline, serializing a dependency's subtree also delays any task
within it that is shared with _other_ targets in the same run (like `moon ci`), which can reduce
parallelism. When multiple parents request conflicting orderings for a shared task, the ordering
that would introduce a cycle is skipped.

:::

#### `runInCI`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#runInCI" />

Whether to run the task automatically in a CI (continuous integration) environment when affected by
changed files using the [`moon ci`](../commands/ci) command. Supports the following values:

- `always` - Always run in CI, regardless if affected or not. <VersionLabel version="1.31.0" />
- `affected`, `true` (default) - Only run in CI if affected by changed files.
- `false` - Never run in CI.
- `only` - Only run in CI, and not locally, if affected by changed files.
  <VersionLabel version="1.41.0" />
- `skip` - Skip running in CI but run locally and allow task relationships to be valid.
  <VersionLabel version="1.41.0" />

```yaml title="moon.yml" {5}
tasks:
  build:
    # ...
    options:
      runInCI: false
```

#### `runInSyncPhase`<VersionLabel version="2.1.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#runInSyncPhase" />

Whether to run the task automatically during `moon sync`. Defaults to `false`.

```yaml title="moon.yml" {5}
tasks:
  generate-schema:
    # ...
    options:
      runInSyncPhase: true
```

#### `runFromWorkspaceRoot`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#runFromWorkspaceRoot" />

Whether to use the workspace root as the working directory when executing a task. Defaults to
`false` and runs from the task's project root.

```yaml title="moon.yml" {5}
tasks:
  typecheck:
    # ...
    options:
      runFromWorkspaceRoot: true
```

#### `shell`

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#shell" />

Whether to run the command within a shell or not. Defaults to `true` for system toolchain or
Windows, and `false` otherwise. The shell to run is determined by the [`unixShell`](#unixshell) and
[`windowsShell`](#windowsshell) options respectively.

```yaml title="moon.yml" {5}
tasks:
  native:
    command: 'echo $SHELL'
    options:
      shell: true
```

However, if you'd like to use a different shell, or customize the shell's arguments, or have
granular control, you can set `shell` to false and configure a fully qualified command.

```yaml title="moon.yml" {5}
tasks:
  native:
    command: '/bin/zsh -c "echo $SHELL"'
    options:
      shell: false
```

#### `timeout`<VersionLabel version="1.26.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#timeout" />

The maximum time in seconds that the task is allowed to run, before it is force cancelled. If not
defined, will run indefinitely.

```yaml title="moon.yml" {5}
tasks:
  build:
    # ...
    options:
      timeout: 120
```

#### `unixShell`<VersionLabel version="1.21.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#unixShell" />

Customize the shell to run with when on a Unix operating system. Accepts `bash`, `elvish`, `fish`,
`ion`, `murex`, `nu`, `pwsh`, `xonsh`, or `zsh`. If not defined, will derive the shell from the
`SHELL` environment variable, or defaults to `bash`.

```yaml title="moon.yml" {5}
tasks:
  native:
    command: 'echo $SHELL'
    options:
      unixShell: 'fish'
```

#### `windowsShell`<VersionLabel version="1.21.0" />

<HeadingApiLink to="/api/types/interface/TaskOptionsConfig#windowsShell" />

Customize the shell to run with when on a Windows operating system. Accepts `bash` (typically via
Git), `elvish`, `fish`, `murex`, `nu`, `pwsh`, or `xonsh`. If not defined, defaults to `pwsh`.

```yaml title="moon.yml" {5}
tasks:
  native:
    command: 'echo $SHELL'
    options:
      windowsShell: 'bash'
```

## `taskOptions`<VersionLabel version="2.4.0" />

<HeadingApiLink to="/api/types/interface/ProjectConfig#taskOptions" />

Defines default [task options](#options) that are applied to _all tasks_ within the current project,
which can be overridden per task. This is similar to the workspace-level
[`taskOptions`](./tasks#taskoptions) in [`.moon/tasks.*`](./tasks), but is scoped to a single
project and sits later in the [inheritance chain](../concepts/task-inheritance), so it takes
precedence over inherited defaults.

```yaml title="moon.yml" {1-5}
taskOptions:
  # Never cache tasks in this project
  cache: false
  # Always re-run flaky tasks
  retryCount: 2

tasks:
  build:
    # ...
    options:
      # Override the project default
      cache: true
```

## Overrides

Dictates how a project interacts with settings defined at the top-level.

## `toolchains`

<HeadingApiLink to="/api/types/interface/ProjectConfig#toolchains" />

### `default`<VersionLabel version="1.31.0" />

<HeadingApiLink to="/api/types/interface/ProjectToolchainConfig#default" />

The default [`toolchain`](#toolchain-1) for all task's within the current project. When a task's
`toolchain` has _not been_ explicitly configured, the toolchain will fallback to this configured
value, otherwise the toolchain will be detected from the project's environment.

```yaml title="moon.yml"
toolchains:
  default: 'node'
```

### `*`<VersionLabel version="2.0.0" />

Configures and overrides [workspace-level settings](./toolchain) for specific toolchains. The key is
the name of the toolchain, and the value is an object of settings to override.

```yaml title="moon.yml" {2-4}
toolchains:
  typescript:
    # Disable refs for this project
    syncProjectReferences: false
```

Alternatively, if you want to _disable_ a toolchain for a project, you can set the value to `false`
or `null`, which will prevent the toolchain from being auto-detected and used within the project.

```yaml title="moon.yml" {2,3}
toolchains:
  typescript: false
```

## `workspace`

<HeadingApiLink to="/api/types/interface/ProjectConfig#workspace" />

### `inheritedTasks`

<HeadingApiLink to="/api/types/interface/ProjectWorkspaceConfig#inheritedTasks" />

Provides a layer of control when inheriting tasks from [`.moon/tasks/**/*`](./tasks).

#### `exclude`

The optional `exclude` setting permits a project to exclude specific tasks from being inherited. It
accepts a list of strings, where each string is the name of a global task to exclude.

```yaml title="moon.yml" {4}
workspace:
  inheritedTasks:
    # Exclude the inherited `test` task for this project
    exclude: ['test']
```

> Exclusion is applied after inclusion and before renaming.

#### `include`

The optional `include` setting permits a project to _only_ include specific inherited tasks (works
like an allow/white list). It accepts a list of strings, where each string is the name of a global
task to include.

When this field is not defined, the project will inherit all tasks from the global project config.

```yaml title="moon.yml" {4,7-9}
workspace:
  inheritedTasks:
    # Include *no* tasks (works like a full exclude)
    include: []

    # Only include the `lint` and `test` tasks for this project
    include:
      - 'lint'
      - 'test'
```

> Inclusion is applied before exclusion and renaming.

#### `rename`

The optional `rename` setting permits a project to rename the inherited task within the current
project. It accepts a map of strings, where the key is the original name (found in the global
project config), and the value is the new name to use.

For example, say we have 2 tasks in the global project config called `buildPackage` and
`buildApplication`, but we only need 1, and since we're an application, we should omit and rename.

```yaml title="moon.yml" {4,5}
workspace:
  inheritedTasks:
    exclude: ['buildPackage']
    rename:
      buildApplication: 'build'
```

> Renaming occurs after inclusion and exclusion.
