Configuration
The checks that Checkers is going to run are defined in the checks
section of the configuration file. By default, Checkers looks for a file named checks.yaml
in the current directory. This page describes the schema and options of the configuration.
Basic Structure
# Optional: Maximum execution duration
timeout: 5s
# List of checks to run
checks:
# Simple command check
- name: Check Docker daemon is running
type: command
command: |
if command -v docker >/dev/null 2>&1; then
echo '{"status": "success", "output": "Docker daemon is running"}'
else
echo '{"status": "failure", "output": "Docker daemon is not running"}'
fi
# Check with parameters
- name: Check .env file exists
type: os.file_exists
parameters:
path: .env
This configuration:
- Sets an execution duration of 5 seconds
- Defines two different types of checks
Global Options
Option | Type | Default | Description |
---|---|---|---|
timeout | duration | 30s | Timeout for checks to execute |
checks | list | [] | List of checks to run |
The timeout value accepts Go duration format (e.g., “30s”, “1m”, “1h”). All checks exceeding the timeout will be cancelled and a timeout message will be shown.
Check Configuration
Each check in the checks
list requires the following fields:
Field | Type | Required | Description |
---|---|---|---|
name | string | Yes | Unique identifier for the check |
type | string | Yes | Type of check to perform (e.g., command, os.file_exists) |
command | string | No* | Shell command to execute |
parameters | map | No* | Additional parameters specific to check type |
items | list | No* | List of parameter sets for running multiple variations of the same check |
* Note: command
, parameters
, and items
are mutually exclusive. A check must have exactly one of these fields.
Multiple Items Configuration
The items
field allows you to run the same check with different parameters. Each item in the list represents a set of parameters for a separate instance of the check. This is particularly useful when you want to run the same type of check against multiple targets.
For example, to check multiple executable installations:
- name: "Check binary installations"
type: os.executable_exists
items:
- name: git
path: /usr/local/bin
- name: docker
This will be expanded into multiple checks, each checking a different executable. By default, check names will be automatically generated as {check-name}: {index}
.
You can customize the check names using Go template syntax to reference any parameter from your items. The template has access to all parameters defined in each item. For example:
- name: "Check binary: {{ .name }}"
type: os.executable_exists
items:
- name: git
path: /usr/local/bin
- name: docker
This will create two checks:
Check binary: git
(with parametersname: git
andpath: /usr/local/bin
)Check binary: docker
(with parametersname: docker
)
The template syntax follows Go’s text/template package rules:
- Use
{{ .key }}
to reference a parameter value, wherekey
is the parameter name - Parameter names are case-sensitive
- If a referenced parameter is missing, the check will fail validation
Each item in the list must contain all the parameters required by the check type. The validation will fail if any required parameters are missing.
Command Line Options
The following command-line flags are available:
checkers [flags]
Flags:
-c, --config string config file path (default "checks.yaml")
-f, --file string output file path. Format will be determined by file extension
-h, --help help for checkers
-o, --output string output format. One of: pretty, json, html (default "pretty")
-t, --timeout duration timeout for each check (default 30s)
-v, --verbose enable verbose logging
--version version for checkers
Output Formats
Checkers supports multiple output formats:
- Pretty (default): Human-readable colored output for terminal viewing
- JSON: Machine-readable JSON format for integration with other tools
- HTML: Rich HTML report with interactive features and styling
You can specify the output format in two ways:
- Using the
--output
or-o
flag:checkers --output html
- Using the
--file
or-f
flag with an appropriate file extension:checkers --file results.html # Uses HTML format checkers --file results.json # Uses JSON format checkers --file results.txt # Uses Pretty format
Supported file extensions:
.html
- HTML format.json
- JSON format.txt
,.log
,.out
- Pretty format
If you specify both --output
and --file
flags, the --output
flag takes precedence.
Timeout Configuration
The timeout can be configured in two ways:
- Command-line flag (
--timeout
or-t
) - Configuration file (
timeout
field)
The command-line flag takes precedence over the configuration file. If neither is specified, a default value of 30s is used.
For example:
# Uses 1m timeout
checkers --timeout 1m
# Uses timeout from checks.yaml, or 30s if not specified
checkers
Best Practices
- Group Related Checks: Organize your checks logically by grouping related items together
- Meaningful Names: Give your checks descriptive names that clearly indicate their purpose
- Timeouts: Set appropriate timeouts to avoid hanging
- Error Messages: Include helpful error messages to make troubleshooting easier
- Output Format Selection: Choose the appropriate output format based on your needs:
- Use
pretty
for interactive terminal usage - Use
json
for integration with other tools or parsing - Use
html
for creating shareable reports or documentation
- Use