> ## Documentation Index
> Fetch the complete documentation index at: https://sysg.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# validate

# 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.

```sh theme={null}
$ sysg validate -c sysg.yaml
```

```text theme={null}
  ✗ 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`:

```text theme={null}
  ✓ 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`)                       |
| `-`   | `--no-color` | Disable ANSI colors                                         |
| `-`   | `--plain`    | Agent-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

| Code | Meaning                                |
| ---- | -------------------------------------- |
| `0`  | Configuration is valid                 |
| `1`  | Configuration has one or more problems |

## JSON output

Use `--format json` for CI gates and tooling. Each diagnostic carries its
location, category, message, and remediation:

```sh theme={null}
$ sysg validate -c sysg.yaml --format json
```

```json theme={null}
{
  "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:

```sh theme={null}
$ sysg validate -c production.yaml --plain || exit 1
$ sysg start -c production.yaml --daemonize
```

## See also

* [Configuration](/how-it-works/configuration) - Full manifest reference
* [`start`](/how-it-works/commands/start) - Launch a validated manifest
* [`status`](/how-it-works/commands/status) - Check services once they're running