Commands

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: "2"` 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

Short	Long	Description
`-c`	`--config`	Path to the configuration file (defaults to `systemg.yaml`)
`-`	`--format`	Emit machine-readable output (`json` or `xml`)
`-v`	`--verbose`	Print operation progress
`-`	`--no-color`	Disable ANSI colors
`-`	`--sys`	Validate against the system runtime (see below). Unlike every other command, validate with `--sys` does not require root
`-`	`--drop-privileges`	Accepted globally but ignored; validate does not spawn services
`-`	`--plain`	Agent-friendly output (also disables color)
`-`	`--log-level`	Set logging verbosity for this invocation (`trace` through `off`, or 5-0)

What it checks

Schema — version 2, services in each declared project or loose bundle, 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 — every named project has a valid, non-empty id.
Environment — ${VAR} interpolations resolve from the environment or env file.
Mode enforceability — whether the mode you validated against could actually start this manifest (see below).

Info

Validation is mode-aware. sysg validate judges the manifest against user mode: root-only keys (user, group, capabilities, limits.cgroup, isolation, non-empty supplementary_groups) produce an error finding (SG0705) — the file is well-formed (valid: true) but not startable in that mode (startable: false, exit 1). sysg validate --sys judges against system (kernel) mode, where those keys pass; accounts missing on the validating host surface as warnings (your deploy target may differ), and Linux-only keys on a non-Linux host remain errors. --sys here needs no root — validating reads, it never exercises privilege.

Exit codes

Code	Meaning
`0`	Configuration is valid and startable in the validated mode
`1`	Configuration has problems, or is not startable in the validated mode

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: \"2\"` 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