Skip to main content

​
validate

Check a configuration file before you run it. validate parses the manifest, resolves the dependency graph, and — when something is wrong — tells you the exact line, why it’s an error, and how to fix it. 
$ sysg validate -c sysg.yaml

  ✗ invalid  sysg.yaml · 1 problem

  1. missing-version  line 1:1
     missing field `version`

     1 │ services:
         ^

     why  Every manifest must declare its schema version at the top level.
     fix  Add `version: "1"` as the first key in the file.
     docs https://sysg.dev/how-it-works/configuration
A clean file reports success and exits 0: 
  ✓ valid  sysg.yaml
  This manifest parses and resolves cleanly.

​
Options

ShortLongDescription
-c--configPath to the configuration file (defaults to systemg.yaml)
---formatEmit machine-readable output (json)
---no-colorDisable ANSI colors
---plainAgent-friendly output (also disables color)

​
What it checks

  • Schema — a supported version, a services map, and a command per service.
  • Syntax — YAML that parses, with a caret pointing at the offending token.
  • Health checks — every deployment.health_check has a url or a command.
  • Dependencies — depends_on references exist and form no cycle.
  • Project id — a valid, non-empty project.id.
  • Environment — ${VAR} interpolations resolve from the environment or env file.

​
Exit codes

CodeMeaning
0Configuration is valid
1Configuration has one or more problems

​
JSON output

Use --format json for CI gates and tooling. Each diagnostic carries its location, category, message, and remediation: 
$ sysg validate -c sysg.yaml --format json

{
  "config": "sysg.yaml",
  "valid": false,
  "diagnostics": [
    {
      "line": 1,
      "column": 1,
      "kind": "missing-version",
      "message": "missing field `version`",
      "why": "Every manifest must declare its schema version at the top level.",
      "suggestion": "Add `version: \"1\"` as the first key in the file.",
      "doc": "https://sysg.dev/how-it-works/configuration"
    }
  ]
}

​
Example

Gate a deploy on a valid manifest: 
$ sysg validate -c production.yaml --plain || exit 1
$ sysg start -c production.yaml --daemonize

​
See also

  • Configuration - Full manifest reference
  • start - Launch a validated manifest
  • status - Check services once they’re running