Schema Management CLI

Tip

  1. Need help? Please let us know in the SUEWS Community.

  2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

  3. Please cite SUEWS with proper information from our Zenodo page.

Schema Management CLI#

The suews schema command provides a comprehensive command-line interface for managing SUEWS YAML configuration schemas. This unified tool addresses the needs for schema version checking, migration, and schema export.

Note

This CLI consolidates functionality from GitHub issues #612 and #613, providing a single entry point for all schema-related operations that will integrate with the future suews-wizard (#544).

Installation#

The suews schema command is automatically installed with SuPy:

pip install supy

Once installed, the command is available system-wide.

Available Commands#

The suews schema CLI provides the following subcommands:

suews schema --help              # Show help and available commands
suews schema info                 # Display schema version information
suews schema version              # Check or update schema versions
suews schema migrate              # Migrate between schema versions
suews schema export               # Export JSON Schema

Configuration validation is handled by suews validate.

Command Reference#

info#

Display information about available schema versions and the current version.

suews schema info

This command shows:

  • Current schema version

  • Available schema versions with descriptions

  • Quick reference for other CLI commands

version#

Check or update schema versions in configuration files.

Basic usage:

# Check schema version
suews schema version config.yml

# Check multiple files
suews schema version configs/*.yml

Update schema versions:

# Update to current version
suews schema version config.yml --update

# Update to specific version
suews schema version config.yml --update --target-version 2026.4

# Update without backup (not recommended)
suews schema version config.yml --update --no-backup

Options:

  • --update, -u: Update schema version in files

  • --target-version: Target version for update (default: current)

  • --backup, -b: Create backup before updating (default: true)

migrate#

Migrate configuration files between schema versions.

Basic usage:

# Migrate to current version
suews schema migrate old_config.yml

# Migrate to specific version
suews schema migrate config.yml --target-version 2026.4

Batch migration:

# Migrate multiple files to output directory
suews schema migrate configs/*.yml --output-dir migrated/

# Dry run to preview changes
suews schema migrate config.yml --dry-run

Options:

  • --target-version: Target schema version (default: current)

  • --output-dir, -o: Output directory for migrated files

  • --backup, -b: Keep original files (default: true)

  • --dry-run, -n: Show what would be done without doing it

export#

Export the JSON Schema for SUEWS configurations.

Basic usage:

# Export to file
suews schema export -o schema.json

# Export specific version
suews schema export --version 2026.4 -o schema-2026.4.json

# Export as YAML
suews schema export --format yaml -o schema.yaml

Options:

  • --output, -o: Output file for schema

  • --version: Schema version to export (default: current)

  • --format: Output format (json, yaml)

Global Options#

All commands support these global options:

  • --verbose, -v: Enable verbose output for debugging

  • --quiet, -q: Suppress non-essential output

Examples#

Example 1: Check and update schema versions

# Check current versions
suews schema version configs/*.yml

# Update all to current version
suews schema version configs/*.yml --update

Example 2: CI/CD validation

# Validate all configs in CI pipeline
suews validate -p C --dry-run configs/*.yml

# Output validation results as JSON for processing
suews validate -p C --dry-run configs/*.yml --format json > validation.json

Example 3: Migration workflow

# Check what needs migration
suews schema version old_configs/*.yml

# Dry run migration
suews schema migrate old_configs/*.yml --dry-run

# Perform migration
suews schema migrate old_configs/*.yml --output-dir updated_configs/

# Validate migrated files
suews validate -p C --dry-run updated_configs/*.yml

Example 4: Schema documentation

# Export current schema for documentation
suews schema export -o docs/schema.json

# Generate human-readable YAML version
suews schema export --format yaml -o docs/schema.yaml

Integration with Other Tools#

Using with Python#

The schema CLI can be called from Python scripts:

import subprocess
import json

# Validate configuration
result = subprocess.run(
    ['suews', 'validate', '-p', 'C', '--dry-run', 'config.yml', '--format', 'json'],
    capture_output=True, text=True
)
validation = json.loads(result.stdout)

# Check schema version
result = subprocess.run(
    ['suews', 'schema', 'version', 'config.yml', '--quiet'],
    capture_output=True, text=True
)

Using in CI/CD#

GitHub Actions example:

- name: Validate SUEWS configs
  run: |
    suews validate -p C --dry-run configs/*.yml

- name: Check schema versions
  run: |
    suews schema version configs/*.yml

Pre-commit hook example:

repos:
  - repo: local
    hooks:
      - id: validate-suews-config
        name: Validate SUEWS configs
       entry: suews validate
       language: system
       files: '\.yml$'
       pass_filenames: true
       args: ['-p', 'C', '--dry-run']

Future Integration with suews-wizard#

The suews schema CLI is designed to integrate seamlessly with the upcoming suews-wizard (issue #544):

  • The wizard will use the validation logic to ensure created configurations are valid

  • Migration utilities can be called from within the wizard for upgrading existing configs

  • Schema version checking will be embedded in the wizard workflow

  • The export functionality will provide schema documentation within the wizard

CLI Best Practices#

  1. Always specify schema version: Include schema_version in your YAML files

  2. Validate before running: Use suews validate before running simulations

  3. Keep backups: Always backup configurations before migration

  4. Use CI/CD validation: Integrate validation into your automated workflows

  5. Document versions: Keep track of which schema version your configs use

CLI Troubleshooting#

Issue: Command not found

Ensure SuPy is installed:

pip install supy

Issue: Validation fails but config works

Check if you’re validating against the correct schema version:

suews schema version config.yml
suews validate -p C --dry-run --schema-version <correct_version> config.yml

Issue: Migration fails

Try step-by-step migration if jumping multiple versions:

# Instead of 2025.12 -> 2026.4 directly
suews schema migrate config.yml --target-version 2026.1
suews schema migrate config.migrated.yml --target-version 2026.4

See Also#