soul-lint

An offline linter: it statically checks configs, Destiny, services, scenarios, and plugin manifests, executing nothing. Install it on the operator’s workstation or in CI — to catch errors before they are applied on hosts.

Why

Destiny, scenarios, and services are YAML with a typed schema and templating expressions. soul-lint validates their shape and contract locally, without reaching out to Keeper or touching hosts. The typical use is a pre-commit / CI gate in the service repository: a PR does not pass if an artifact is invalid.

Subcommands

soul-lint validate-config   <path> [--json]   # keeper.yml or soul.yml
soul-lint validate-destiny  <path> [--json]   # destiny.yml (the root Destiny manifest)
soul-lint validate-service  <path> [--json]   # service.yml (the root service manifest)
soul-lint validate-scenario <path> [--json]   # scenario/<name>/main.yml
soul-lint validate-manifest <path> [--json]   # the plugin's manifest.yaml
soul-lint plugin-init <namespace>/<name> [flags]   # scaffold a new SoulModule plugin

Subcommand	What it validates
validate-config	Keeper (keeper.yml) or agent (soul.yml) config
validate-destiny	the root Destiny manifest
validate-service	the root service manifest
validate-scenario	a scenario (scenario/<name>/main.yml)
validate-manifest	a plugin manifest (kind: soul_module / cloud_driver / ssh_provider)
plugin-init	generates the skeleton of a new SoulModule plugin

The --json flag switches the output to a machine-readable format (handy in CI).

Exit codes

Code	Meaning
0	valid, no errors
1	validation errors found
2	I/O error or an incorrect invocation (usage)

A CI gate relies on the exit code: a non-zero one fails the pipeline.

Use in CI

# example CI step: fail the pipeline if any artifact is invalid
soul-lint validate-service ./service.yml
soul-lint validate-scenario ./scenario/create/main.yml --json

Plugin scaffold

For custom-module authors, soul-lint plugin-init <namespace>/<name> generates a ready-made SoulModule plugin skeleton:

soul-lint plugin-init official/my-module --out ./soul-mod-my-module --author "Your Name"

Flags: --out DIR (output directory), --description TEXT, --author NAME, --force (overwrite an existing directory).

Installation

soul-lint is installed from the soul-stack-soul-lint package (CLI only, no daemon or config), a binary release, or a source build. See Install from packages and From binary releases.