---
url: /firepit/schema.md
description: Firepit Configuration File Schema
---

# Schema

The JSON schema file is available [here](https://raw.githubusercontent.com/kota65535/firepit/main/schema.json).

Each property section is described as follows:

* **Type**: Type of the property. We use `Array<{item type}>` for arrays, `Map<{key type}, {value type}>` for objects.
* **Required**: Whether the property is required.
* **Default**: Default value of the property.
* **Options**: Available values of the property.
* **Template**: Whether the property is a template string. Only for `string` or types containing strings.
* **Description**: Description of the property.

## Project

### concurrency

* **Type:** integer
* **Required:** no
* **Default:** `Number of available CPU cores`
* **Description:** Task concurrency. Valid only in a root project config.

```yaml
concurrency: 4
```

### defaults

* **Type:** Array\<DefaultsConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Default settings applied to tasks matching a selector.

```yaml
defaults:
  - tasks: "^(build|test)"
    depends_on:
      - install
```

### depends\_on

* **Type:** Array\<DependsOnConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** **Deprecated**: Use [`defaults`](https://kota65535.github.io/firepit/schema.html#defaults)
  instead.

Dependency tasks for all the project tasks.

```yaml
depends_on:
  - :install
```

### env

* **Type:** Map\<string, string>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** **Deprecated**: Use [`defaults`](https://kota65535.github.io/firepit/schema.html#defaults)
  instead.

Environment variables for all the project tasks.

```yaml
env:
  TZ: Asia/Tokyo
```

### env\_files

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** **Deprecated**: Use [`defaults`](https://kota65535.github.io/firepit/schema.html#defaults)
  instead.

Dotenv files for all the project tasks. Their values are templates.
In case of duplicated environment variables, the latter one takes precedence.

```yaml
env_files:
  - .env
  - .env.local
```

### gantt\_file

* **Type:** string
* **Required:** no
* **Template:** no
* **Description:** Gantt chart output file path, relative to the root project. Valid only in a root project
  config.

```yaml
gantt_file: gantt.mmd
```

### includes

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** Additional config files to be included.

```yaml
includes:
  - common-vars.yml
  - common-tasks.yml
```

An included file can include others, with paths relative to the including file.

### log

* **Type:** LogConfig
* **Required:** no
* **Default:** `{"file":null,"level":"warn"}`
* **Description:** Log configuration. Valid only in a root project config.

```yaml
log:
  level: debug
  file: firepit.log
```

### projects

* **Type:** ProjectsConfig
* **Required:** no
* **Default:** `{}`
* **Description:** Child projects. Valid only in a root project config.

```yaml
projects:
  client: packages/client
  server: packages/server
```

A list can mix globs, paths, and project names to paths.
A glob or a path takes the directory name as the project name, and a glob matches only
directories with a config file.

```yaml
projects:
  - packages/*
  - tools/cli
  - www: apps/website
```

### shell

* **Type:** ShellConfig
* **Required:** no
* **Default:** `{"args":["-c"],"command":"bash"}`
* **Description:** **Deprecated**: Use [`defaults`](https://kota65535.github.io/firepit/schema.html#defaults)
  instead.

Shell configuration for all the project tasks.

```yaml
shell:
  command: "bash"
  args: ["-eux", "-c"]
```

### tasks

* **Type:** Map\<string, TaskConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** no
* **Description:** Task definitions.

### ui

* **Type:** UI
* **Required:** no
* **Default:** `cui`
* **Description:** UI configuration. Valid only in a root project config.

```yaml
ui: cui
```

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Template variables for all the project tasks.
  A variable declared without a value has no default, so it is required: running any task of
  the project without giving it a value by the `<name>=<value>` CLI argument is an error.

```yaml
vars:
  registry: docker.io/example
  image: "{{ registry }}/server"
```

### working\_dir

* **Type:** string
* **Required:** no
* **Default:** `.`
* **Template:** yes
* **Description:** **Deprecated**: Use [`defaults`](https://kota65535.github.io/firepit/schema.html#defaults)
  instead.

Working directory for all the project tasks.

```yaml
working_dir: src
```

## DefaultsConfig

### depends\_on

* **Type:** Array\<DependsOnConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Dependency tasks

### env

* **Type:** Map\<string, string>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Environment variables

### env\_files

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** Dotenv files. Their values are templates.

### inputs

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** no
* **Description:** Inputs file glob patterns

### outputs

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** no
* **Description:** Output file glob patterns

### service

* **Type:** ServiceConfig
* **Required:** no
* **Description:** Service configurations

### shell

* **Type:** ShellConfig
* **Required:** no
* **Description:** Shell configuration

### stop\_timeout

* **Type:** integer
* **Required:** no
* **Description:** Grace period in seconds given to the task process after `SIGINT` is sent, before it is
  forcibly killed with `SIGKILL`.

### tasks

* **Type:** TaskSelector
* **Required:** no
* **Description:** Task selector. A string is a regex pattern, an array is an explicit list of task names.
  If omitted, all tasks are matched.

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Template variables

### wait\_for

* **Type:** Array\<WaitForConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Tasks to run after, without depending on them

### working\_dir

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Working directory

## DependsOnConfig

* **Type:** string | DependsOnConfigStruct
* **Template:** yes

## DependsOnConfigStruct

### cascade

* **Type:** boolean
* **Required:** no
* **Default:** `true`
* **Description:** Whether the task restarts if this dependency task restarts.

### optional

* **Type:** boolean
* **Required:** no
* **Default:** `false`
* **Description:** Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

### task

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Dependency task name

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Variables to override the dependency task vars.

## DynamicVars

### cache

* **Type:** boolean
* **Required:** no
* **Default:** `false`
* **Description:** Whether the command output is reused by the other variables running the same command in the
  same working directory.
  A variable shared by several projects runs in each project directory, so sharing one run
  across them takes an explicit `working_dir`.
  Leave it off for a command that must run every time, ex: allocating a resource.

### command

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Command

### env

* **Type:** Map\<string, string>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Environment variables

### env\_files

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** Dotenv files. Their values are templates.

### shell

* **Type:** ShellConfig
* **Required:** no
* **Description:** Shell configuration

### type

* **Type:** VarType
* **Required:** no
* **Description:** Type of the variable, following JSON Schema.
  The command output is interpreted as this type; without it, the type is inferred from the
  output.

### working\_dir

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Working directory

## ExecProbeConfig

### command

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Command to check if the service is ready

### env

* **Type:** Map\<string, string>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Environment variables. Merged with the task `env`.

### env\_files

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** Dotenv files. Merged with the task `env_files`. Their values are templates.

### interval

* **Type:** integer
* **Required:** no
* **Default:** `5`
* **Description:** Interval in seconds.
  The command will run interval seconds after the task is started, and then again interval
  seconds after each previous check completes.

### retries

* **Type:** integer
* **Required:** no
* **Default:** `3`
* **Description:** Number of consecutive readiness-check failures allowed before giving up.

### shell

* **Type:** ShellConfig
* **Required:** no
* **Description:** Shell configuration

### start\_period

* **Type:** integer
* **Required:** no
* **Default:** `0`
* **Description:** Initialization period in seconds.
  Probe failure during that period will not be counted towards the maximum number of retries.

### timeout

* **Type:** integer
* **Required:** no
* **Default:** `5`
* **Description:** Timeout in seconds

### working\_dir

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Working directory

## FinalizedByConfig

* **Type:** string | FinalizedByConfigStruct
* **Template:** yes

## FinalizedByConfigStruct

### optional

* **Type:** boolean
* **Required:** no
* **Default:** `false`
* **Description:** Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

### task

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Finalizer task name

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Variables to override the finalizer task vars.

## HealthCheckConfig

* **Type:** LogProbeConfig | ExecProbeConfig

## LogConfig

### file

* **Type:** string
* **Required:** no
* **Template:** no
* **Description:** Log file path, relative to the root project.

### level

* **Type:** string
* **Required:** no
* **Default:** `warn`
* **Template:** no
* **Description:** Log level. Valid values: error, warn, info, debug, trace.
  `warn` and above report what a user needs to act on, `info` what Firepit is doing to each
  task, `debug` and below the internals.

## LogProbeConfig

### log

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Log regex pattern to determine the task service is ready

### timeout

* **Type:** integer
* **Required:** no
* **Default:** `20`
* **Description:** Timeout in seconds

## ProjectEntryConfig

* **Type:** string | Map\<string, string>
* **Template:** no

## ProjectsConfig

* **Type:** Map\<string, string> | Array\<ProjectEntryConfig>
* **Template:** no

## Restart

* **Type:** string
* **Options:** `always`, `on-failure`, `never`
* **Template:** no

## ServiceConfig

* **Type:** boolean | ServiceConfigStruct

## ServiceConfigStruct

### healthcheck

* **Type:** HealthCheckConfig
* **Required:** no
* **Description:** Readiness probe configuration

### restart

* **Type:** Restart
* **Required:** no
* **Default:** `never`
* **Description:** Restart policy

## ShellConfig

### args

* **Type:** Array\<string>
* **Required:** no
* **Default:** `["-c"]`
* **Template:** no
* **Description:** Arguments of the shell command.

### command

* **Type:** string
* **Required:** no
* **Default:** `bash`
* **Template:** no
* **Description:** Shell command.

## TaskConfig

### command

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Command to run

### depends\_on

* **Type:** Array\<DependsOnConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Dependency tasks

### description

* **Type:** string
* **Required:** no
* **Template:** no
* **Description:** Description

### env

* **Type:** Map\<string, string>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Environment variables. Merged with the project `env`.

### env\_files

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** yes
* **Description:** Dotenv files. Merged with the project `env_files`. Their values are templates.

### finalized\_by

* **Type:** Array\<FinalizedByConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Tasks to run after this task finishes, whether it succeeds or fails.
  They run only when this task is part of the run (as a target or a dependency), so running a
  finalizer on its own does not run the task it finalizes.
  Write an entry in object form to override the finalizer's `vars`, as with `depends_on`.

```yaml
finalized_by:
  - db-down
  - task: notify
    vars:
      channel: ci
```

### inputs

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** no
* **Description:** Inputs file glob patterns

### label

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Label to display instead of the task name.

### outputs

* **Type:** Array\<string>
* **Required:** no
* **Default:** `[]`
* **Template:** no
* **Description:** Output file glob patterns

### service

* **Type:** ServiceConfig
* **Required:** no
* **Description:** Service configurations

### shell

* **Type:** ShellConfig
* **Required:** no
* **Description:** Shell configuration

### stop\_timeout

* **Type:** integer
* **Required:** no
* **Description:** Grace period in seconds given to the task process after `SIGINT` is sent, before it is
  forcibly killed with `SIGKILL`.

```yaml
stop_timeout: 30
```

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Template variables.
  A task variable shadows the project variable of the same name, and the `<name>=<value>` CLI
  argument overrides both.
  Can be used at `label`, `command`, `working_dir`, `env`, `env_files`, `depends_on`,
  `depends_on.{task, vars}`, `wait_for`, `wait_for.{task, vars}`, `service.healthcheck.log`
  and `service.healthcheck.exec.{command, working_dir, env, env_files}`

A variable declared without a value has no default, so it is required: give it a value with
the CLI argument or the dependent task's `depends_on.vars`.

### wait\_for

* **Type:** Array\<WaitForConfig>
* **Required:** no
* **Default:** `[]`
* **Description:** Tasks to run after, without depending on them.

Unlike `depends_on`, the listed tasks are not added to the run.
They only order this task after them when they are going to run anyway.
Naming a task orders this one after every variant of it.
Write an entry in object form to wait only for the variants whose vars match the given ones.

```yaml
wait_for:
  - lint
  - task: migrate
    vars:
      database: app
```

### working\_dir

* **Type:** string
* **Required:** no
* **Template:** yes
* **Description:** Working directory

```yaml
working_dir: dist
```

## TaskSelector

* **Type:** string | Array\<string>
* **Template:** no
* **Description:** Task selector for `defaults`.
  A string value is treated as a regex pattern matched against the task name.
  An array value is treated as an explicit list of task names. If omitted, all tasks are matched.

```yaml
defaults:
  - tasks: "^build"        # regex
    env:
      NODE_ENV: production
  - tasks: [test, lint]    # explicit list
    depends_on:
      - install
  - env:                   # no tasks field = all tasks
      LOG_LEVEL: info
```

## TypedVars

### default

* **Type:** any
* **Required:** no
* **Description:** Default value. Without it the variable is required.

### type

* **Type:** VarType
* **Required:** yes
* **Description:** Type of the variable, following JSON Schema

## UI

* **Type:** string
* **Options:** `cui`, `tui`
* **Template:** no

## VarType

* **Type:** string
* **Options:** `string`, `number`, `integer`, `boolean`, `array`, `object`
* **Template:** no
* **Description:** Variable types, following JSON Schema

## VarsConfig

* **Type:** DynamicVars | TypedVars | string | number | boolean
* **Template:** no
* **Description:** Vars config

A variable is one of:

* a scalar value (`foo: bar`), whose type is inferred from the value
* a typed declaration (`foo: { type: array, default: [a, b] }`), see \[`TypedVars`]
* a dynamic variable (`foo: { command: ... }`), see \[`DynamicVars`]

Array and object values are only accepted as the `default` of a typed declaration, so that an
object is never ambiguous between a value and a declaration.

An object with `command` is dynamic (tried first, so `{ type, command }` is a typed dynamic
variable), otherwise an object with `type` is a typed declaration.

## WaitForConfig

* **Type:** string | WaitForConfigStruct
* **Template:** yes

## WaitForConfigStruct

### optional

* **Type:** boolean
* **Required:** no
* **Default:** `false`
* **Description:** Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

### task

* **Type:** string
* **Required:** yes
* **Template:** yes
* **Description:** Name of the task to wait for

### vars

* **Type:** Map\<string, VarsConfig>
* **Required:** no
* **Default:** `{}`
* **Template:** yes
* **Description:** Variables narrowing down which variants of the task to wait for.
  Only the variables given here are compared, so the variants may differ in the others.