Skip to main content

​
Usage

devgraph validate [paths...] [options]

​
Arguments

ArgumentDescriptionDefault
pathsFiles or globs containing devgraph-* blocks**/*.md

​
Options

OptionDescriptionDefault
--jsonOutput validation result as JSON-
--config <path>Path to config file.devgraph/config.yaml
--report <path>Write JSON report to file-

​
Description

Validates devgraph-* blocks without generating build outputs. Validation focuses on the authoritative service layer that feeds the hybrid graph. Runs three types of validation:
  1. Schema validation: YAML syntax, required fields, valid references
  2. Consistency checks: Missing dependencies, duplicates, orphans, cycles
  3. Architecture rules: Custom rules defined in your config file
Useful for CI/CD pipelines or pre-commit hooks.

​
Examples

Validate a docs tree: 
devgraph validate docs/**/*.md
Validate all Markdown files: 
devgraph validate "**/*.md"

​
Exit Codes

CodeDescription
0All blocks valid
1Validation errors found
2Tooling error (config not found, etc.)

​
What it validates

​
Schema Validation

  • YAML syntax in all devgraph-* blocks
  • Required fields (name, type for services)
  • Service references in devgraph-api and devgraph-env blocks
  • Line numbers included in error messages for easier debugging

​
Consistency Checks

  • Missing dependencies: Services reference non-existent dependencies
  • Duplicate services: Multiple blocks define the same service name
  • Orphan blocks: API/env blocks reference non-existent services
  • Dependency cycles: Circular dependency detection

​
Architecture Rules

Define rules in .devgraph/config.yaml: 
rules:
  - type: denyDependency
    from: frontend-*
    to: database
    message: 'Frontend services should not depend on database directly'

​
CI Integration

# In your CI pipeline
devgraph validate --json --report .devgraph/validation-report.json

# Check exit code
if [ $? -eq 1 ]; then
  echo "Validation failed"
  exit 1
fi