Configuration

Ignition supports an optional configuration file for ignition run. This avoids repeating the same run flags on every invocation.

Config file

Create ignition.config.ts in your project root:

import type { IgnitionConfig } from "@grovemotorco/ignition"

export default {
  inventory: "inventory.ts",
  trace: true,
  parallelism: 10,
  errorMode: "fail-at-end",
} satisfies IgnitionConfig

ignition run auto-discovers this file in the current working directory. Other commands still use their own explicit flags and arguments.

Use an explicit CLI --format ... flag when you need machine-readable output. Although IgnitionConfig still validates a format field internally, the current run command does not honor a config-level output-format default.

All options

Field	Type	Default	Description
`inventory`	`string`	—	Path to inventory file
`errorMode`	`"fail-fast" \| "fail-at-end" \| "ignore"`	`"fail-fast"`	Error handling strategy
`parallelism`	`number`	`5`	Max concurrent hosts
`hostTimeout`	`number`	`0`	Per-host timeout in ms (0 = unlimited)
`resourceTimeout`	`number`	`30000`	Per-resource timeout in ms
`retries`	`number`	`2`	Retry attempts for transient failures
`retryDelay`	`number`	`1000`	Initial retry backoff in ms
`multiplex`	`boolean`	`true`	SSH connection multiplexing
`hostKeyPolicy`	`"strict" \| "accept-new" \| "off"`	`"accept-new"`	SSH host key verification
`dashboardHost`	`string`	`"127.0.0.1"`	Dashboard server hostname for `run` events
`dashboardPort`	`number`	`9090`	Dashboard server port for `run` events
`logDir`	`string`	—	Directory for NDJSON log files
`trace`	`boolean`	`false`	Show SSH commands and detailed output
`cache`	`boolean`	`false`	Enable check result caching
`cacheTtl`	`number`	`600000`	Cache entry lifetime in ms
`cacheClear`	`boolean`	`false`	Clear cache before running
`vars`	`Record<string, unknown>`	—	Default variables

Precedence

CLI flags always override config file values:

CLI flag  >  config file  >  hardcoded default

For example, if your config sets parallelism: 10 and you pass --parallelism 3, Ignition uses 3.

Examples

Development config

import type { IgnitionConfig } from "@grovemotorco/ignition"

export default {
  inventory: "inventory.ts",
  trace: true,
  hostKeyPolicy: "accept-new",
  dashboardHost: "127.0.0.1",
  dashboardPort: 9090,
} satisfies IgnitionConfig

CI/CD config

import type { IgnitionConfig } from "@grovemotorco/ignition"

export default {
  inventory: "production.ts",
  errorMode: "fail-fast",
  parallelism: 20,
  logDir: "./logs",
  hostTimeout: 300000,
} satisfies IgnitionConfig

Validation

Ignition validates the config file on load. Invalid values produce clear error messages:

Invalid parallelism "-1" in ignition.config.ts. Must be a positive integer.
Invalid errorMode "bogus" in ignition.config.ts. Must be one of: fail-fast, fail-at-end, ignore

Safety note

The confirm flag is intentionally not configurable via the config file. It must be passed explicitly on the CLI to prevent accidental applies.

Configuration

On this page