# Validate configuration before running

`check-config` validates the configuration used by simple mode, cron and serve.
It uses their existing YAML/Mako loader, selector compiler and rule parser without
connecting to Docker or executing container actions. It creates no agent log,
runtime directory, lock or state file.

Requires monit-docker v0.0.61 or newer. Upgrade with
`python -m pip install --upgrade monit-docker`.

## Usage

Global configuration and selection options go **before** `check-config`:

```sh
monit-docker -c /etc/monit-docker/monit-docker.yml check-config
monit-docker -c /etc/monit-docker/monit-docker.yml --ctn-group web \
  check-config --cmd-if 'mem_percent > 90 ? restart' --output json
```

Add repeated `--cmd` or `--cmd-if` options to check the expressions you intend to
pass to `monit`, `cron` or `serve`. These options validate only; they do not run
commands. All configured command aliases, condition aliases and container groups
are checked even if the supplied expressions/selectors do not use them.

To validate the repository example, including its relative imports:

```sh
python -m monit_docker -c etc/monit-docker/monit-docker.yml.example check-config
```

The named file takes precedence over `MONIT_DOCKER_CONFIG`. If that file does not
exist, the command uses the inline environment configuration when set, matching
the runtime's precedence. If neither exists, validation fails explicitly.
An empty mapping (`{}`) is valid; an empty file, `null` or a list is not.

## What gets checked

- Top-level sections and entry shapes: `general`, `vars`, `clients`, `ctn-groups`,
  `dir-groups`, `conditions`, `commands` and `scenarios`; missing fields and unknown
  sections/entry fields.
- Existing import directives, relative file paths and Mako rendering. The same
  import scope and override behavior as the runtime is used.
- Client configuration mappings and basic TLS shape; explicit client names.
  An explicitly unknown `--client` always fails, even with `--client-from-env`.
- Every group match and regular expression, CLI selectors and selected group names.
- Every command/condition alias, supported Docker action, action argument shape,
  rule syntax, resource name, unit conversion and condition value conversion.
- Every named scenario, including its mode-specific options, resources, rules
  and references. Since 0.0.77, access resources also require an explicit directory
  access identity during offline validation, before a runner can start.

Validation stops at the first error. Locations identify the source/import file,
entry or supplied rule; YAML syntax errors also include line and column numbers.
Messages avoid dumping rendered configuration, command contents and credentials.
Fix the reported error and rerun to reveal any later errors.

Checks and monitoring execution now use the same strict validation, including
dormant entries. See [beta changes](beta-decisions.md).

See the [configuration and CLI contract](config-cli-contract.md) for precedence,
selection semantics and the remaining compatibility decisions before 1.0.

## Output and exit codes

Text is the default. `--output json` writes one result object to standard output:

```json
{"valid": true, "errors": [], "summary": {"clients": 1, "groups": 1, "commands": 2, "conditions": 1, "rules": 1}}
```

`summary` counts loaded entries and supplied rules. On failure it is empty and
`errors` contains the first diagnostic with `location` and `message` fields.
Exit codes are `0` for valid configuration, `110` for a configuration/rule error,
and `2` for invalid CLI arguments. This makes the command suitable for deployment
scripts and CI. Standard parser diagnostics may also appear on standard error.

## Limits

A valid result does not prove Docker is reachable, TLS credentials are readable,
a Docker SDK option is supported, a container exists, or an in-container command
will succeed. It also does not predict whether conditions will match live values.
Docker-specific connection settings and action keyword options are not exhaustively
validated against daemon/SDK versions. Use a monitored test run or the existing
[dry-run mode](cron.md) for checks requiring actual container observations.

Configuration and imported **Mako templates must be trusted**: templates execute
Python while being rendered, just as they do during normal startup. Offline here
means the validator itself does not call Docker or execute rule actions; it is
not a sandbox for untrusted templates.