Command-Line Tools

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.

6.4. Command-Line Tools#

SUEWS provides command-line tools for common operations without requiring Python scripting.

6.4.1. Available Commands#

6.4.1.1. suews-run#

Execute SUEWS simulations from the command line with YAML or namelist configuration files.

YAML Configuration (Recommended)

# Run with YAML configuration file
suews-run config.yml

# Or specify full path
suews-run /path/to/config.yml

# Use default config.yml in current directory
suews-run

Namelist Configuration (Deprecated)

Legacy namelist format is still supported but deprecated:

# Legacy format with deprecation warning
suews-run -p RunControl.nml

Migration from Namelist to YAML

To migrate from the deprecated namelist format to modern YAML:

# Step 1: Convert namelist to YAML
suews-convert -i RunControl.nml -o config.yml

# Step 2: Run with YAML configuration
suews-run config.yml

Format Auto-Detection

The tool automatically detects the configuration format based on file extension:

  • .yml, .yaml → YAML format (modern, recommended)

  • .nml → Namelist format (legacy, shows deprecation warning)

For detailed usage and examples, see the Getting Started guide.

6.4.1.2. suews-convert#

Convert between SUEWS input formats and versions.

suews-convert -i input_dir -o output.yml

Documentation:

6.4.1.3. suews-validate#

Validate SUEWS YAML configuration files against the schema.

suews-validate config.yml

6.4.1.4. suews-schema#

Display and export SUEWS configuration schema for validation and tooling.

suews-schema --help

6.4.1.5. suews knowledge#

Query the packaged source-evidence knowledge pack. The pack is generated from the Git checkout used to build the installed SuPy wheel and carries citations back to the exact repository paths and line spans.

suews knowledge manifest --format json
suews knowledge query "How is runoff routed?" --format json

See Knowledge Pack for the pack format and source policy.