CLI Reference#

SYMFLUENCE provides a comprehensive command-line interface for managing hydrological modeling workflows. This reference documents all available commands, options, and usage patterns.

Overview#

The CLI follows a two-level hierarchical structure:

  • Level 1: Command categories (workflow, project, binary, config, job, example, agent, gui, tui, data, fews, list) plus the top-level doctor command

  • Level 2: Specific actions within each category

Basic usage:

symfluence <category> <command> [options]

Global Options#

These options are available to all commands:

Option

Description

--config PATH

Path to configuration file (default: ./config.yaml)

--debug

Enable debug output and stack traces

--visualise / --visualize

Enable visualization during execution

--dry-run

Show what would be executed without running

--profile

Enable I/O profiling

--profile-output PATH

Path for profiling report (default: profile_report.json)

--profile-stacks

Capture stack traces in profiling

--version

Display SYMFLUENCE version

Workflow Commands#

Manage and execute SYMFLUENCE workflows.

workflow run#

Execute the complete workflow from start to finish.

symfluence workflow run [--config CONFIG] [--force-rerun] [--continue-on-error]

Options:

  • --force-rerun: Force rerun of all steps (skip caching)

  • --continue-on-error: Continue executing steps on errors

Example:

symfluence workflow run --config my_config.yaml --force-rerun

workflow step#

Execute a single workflow step.

symfluence workflow step STEP_NAME [--config CONFIG] [--force-rerun]

Available Steps:

The canonical step names, in execution order, are:

  • setup_project - Initialize project structure and shapefiles

  • create_pour_point - Create pour point shapefile from coordinates

  • acquire_attributes - Download and process geospatial attributes

  • define_domain - Define hydrological domain boundaries

  • discretize_domain - Discretize domain into HRUs or other units

  • process_observed_data - Process observational data (streamflow, etc.)

  • acquire_forcings - Acquire meteorological forcing data

  • model_agnostic_preprocessing - Model-agnostic preprocessing

  • build_model_ready_store - Build model-ready forcing/attributes/observations store

  • model_specific_preprocessing - Model-specific input setup

  • run_model - Execute the hydrological model

  • postprocess_results - Postprocess and finalize results

  • calibrate_model - Run calibration / parameter optimization

  • run_benchmarking - Run benchmarking analysis

  • run_decision_analysis - Run decision analysis for model comparison

  • run_sensitivity_analysis - Run sensitivity analysis

This list (and the supported short aliases) can drift as the framework evolves; run symfluence workflow list-steps for the authoritative, up-to-date set.

Example:

symfluence workflow step calibrate_model --config config.yaml

workflow steps#

Execute multiple workflow steps in sequence.

symfluence workflow steps STEP1 STEP2 ... [--config CONFIG] [--force-rerun]

Example:

symfluence workflow steps acquire_forcings model_agnostic_preprocessing run_model

workflow status#

Show workflow execution status.

symfluence workflow status [--config CONFIG]

workflow validate#

Validate configuration file syntax.

symfluence workflow validate [--config CONFIG]

workflow list-steps#

List all available workflow steps.

symfluence workflow list-steps

workflow resume#

Resume workflow from a specific step.

symfluence workflow resume STEP_NAME [--config CONFIG] [--force-rerun]

Example:

symfluence workflow resume calibrate_model --config config.yaml

workflow clean#

Clean intermediate or output files.

symfluence workflow clean [--config CONFIG] [--level LEVEL] [--dry-run]

Options:

  • --level: Cleaning level (intermediate, outputs, all; default: intermediate)

  • --dry-run: Preview what would be cleaned

Example:

symfluence workflow clean --level all --dry-run

Project Commands#

Initialize projects and configure pour points.

project init#

Initialize a new SYMFLUENCE project.

symfluence project init [PRESET] [options]

Options:

  • --domain TEXT: Domain name

  • --model {SUMMA,FUSE,GR,HYPE,MESH,RHESSys,NGEN,LSTM}: Model selection

  • --start-date YYYY-MM-DD: Simulation start date

  • --end-date YYYY-MM-DD: Simulation end date

  • --forcing TEXT: Forcing dataset

  • --discretization TEXT: Discretization method

  • --definition-method TEXT: Domain definition method

  • --output-dir PATH: Output directory (default: ./)

  • --scaffold: Create full directory structure

  • --minimal: Create minimal configuration (10 required fields)

  • --comprehensive: Create comprehensive configuration (400+ options)

  • -i, --interactive: Run interactive configuration wizard

Examples:

# Interactive setup with scaffold
symfluence project init --interactive --scaffold

# With preset
symfluence project init fuse-provo --model FUSE --start-date 2020-01-01

# Minimal config
symfluence project init --domain MyDomain --minimal

project pour-point#

Set up pour point workflow.

symfluence project pour-point LAT/LON --domain-name NAME --definition METHOD [options]

Arguments:

  • coordinates: Pour point as “lat/lon” (e.g., 51.1722/-115.5717)

Required Options:

  • --domain-name NAME: Domain/watershed name

  • --definition METHOD: Definition method (lumped, point, subset, delineate)

Optional:

  • --bounding-box: Custom bounding box (LAT_MAX/LON_MIN/LAT_MIN/LON_MAX)

  • --experiment-id: Override experiment ID

  • --output-dir: Output directory

Example:

symfluence project pour-point 51.1722/-115.5717 --domain-name Bow --definition delineate

project list-presets#

List available initialization presets.

symfluence project list-presets

project show-preset#

Show details of a specific preset.

symfluence project show-preset PRESET_NAME

Binary Commands#

Install and manage external tools.

binary install#

Install external tools.

symfluence binary install [TOOL1 TOOL2 ...] [--force]

Available Tools:

  • summa - SUMMA hydrological model

  • mizuroute - mizuRoute routing model

  • fuse - FUSE hydrological model

  • hype - HYPE hydrological model

  • mesh - MESH model

  • taudem - TauDEM terrain analysis

  • gistool - GIS analysis tool

  • datatool - Data processing tool

  • rhessys - RHESSys ecosystem model

  • ngen - NextGen framework

  • ngiab - NextGen in a Box

  • sundials - SUNDIALS ODE solver

Example:

symfluence binary install summa mizuroute taudem --force

binary validate#

Validate installed binaries.

symfluence binary validate [--verbose]

binary doctor#

Run comprehensive system diagnostics.

symfluence binary doctor

binary info#

Display information about installed tools.

symfluence binary info

Config Commands#

Manage and validate configuration files.

config list-templates#

List available configuration templates.

symfluence config list-templates

config validate#

Validate configuration file.

symfluence config validate [--config CONFIG]

config validate-env#

Validate system environment.

symfluence config validate-env

config update#

Update / migrate a configuration file to the current schema.

symfluence config update CONFIG_FILE [--interactive]

config resolve#

Resolve a configuration through the full 5-layer hierarchy and print the effective values (useful for debugging defaults, env overrides, and aliases).

symfluence config resolve [--config CONFIG] [--flat] [--json] [--diff] [--section SECTION]

Options:

  • --flat: Print the flat (legacy) key form instead of nested

  • --json: Emit JSON

  • --diff: Show only values that differ from the defaults

  • --section SECTION: Restrict output to a single config section

Job Commands#

Submit workflows to HPC clusters via SLURM.

job submit#

Submit workflow as SLURM job.

symfluence job submit [options] [WORKFLOW_COMMAND ...]

Options:

  • --name NAME: SLURM job name

  • --time TIME: Time limit (HH:MM:SS; default: 48:00:00)

  • --nodes N: Number of nodes (default: 1)

  • --tasks N: Number of tasks (default: 1)

  • --memory MEM: Memory requirement (default: 50G)

  • --account ACCOUNT: Account to charge

  • --partition PARTITION: Partition/queue name

  • --modules MODULES: Module to restore (default: symfluence_modules)

  • --conda-env ENV: Conda environment (default: symfluence)

  • --wait: Monitor job until completion

  • --template PATH: Custom SLURM template

Examples:

# Simple submission
symfluence job submit workflow run --config config.yaml

# With resources
symfluence job submit --time 72:00:00 --nodes 4 --tasks 16 \
  --account myaccount workflow run --config config.yaml

# With monitoring
symfluence job submit --wait workflow run --config config.yaml

Example Commands#

Launch and manage example notebooks.

example launch#

Launch an example notebook.

symfluence example launch EXAMPLE_ID [--lab] [--notebook]

Options:

  • --lab: Launch in JupyterLab (default)

  • --notebook: Launch in classic Jupyter Notebook

example list#

List available example notebooks.

symfluence example list

Agent Commands#

Hand off to an installed coding-agent CLI (Claude Code, Codex, Gemini, …) primed with the SYMFLUENCE skills. SYMFLUENCE does not ship its own language model — it detects an installed agent CLI, exposes the SYMFLUENCE skills to it, and replaces itself with that agent. See AI Agent Guide for the full walkthrough.

agent launch#

Launch the agent. With no prompt it starts an interactive session; with a prompt it runs once and exits (handy in scripts).

# Interactive session (run from your project directory)
symfluence agent launch

# One-shot prompt
symfluence agent launch "add an MSWEP forcing data handler"

# Forward extra flags to the underlying CLI after --
symfluence agent launch -- --model claude-sonnet-4-6

CLI selection and skill exposure are controlled by environment variables (SYMFLUENCE_AGENT_CLI, SYMFLUENCE_NO_SKILLS); see AI Agent Guide.

Deprecated aliases#

symfluence agent start and symfluence agent run PROMPT are deprecated aliases for agent launch (interactive and one-shot respectively) and will be removed in a future release. Their --config / --verbose flags are deprecated and ignored.

GUI Commands#

Launch the Panel-based web GUI for interactive workflow management.

gui launch#

Start the SYMFLUENCE web interface.

symfluence gui launch [--port PORT] [--no-browser] [--demo NAME] [--config CONFIG]

Options:

  • --port PORT: Server port (default: 5006)

  • --no-browser: Do not auto-open a browser tab

  • --demo NAME: Load a built-in demo (e.g., “bow” for Bow at Banff)

Example:

# Launch with default settings
symfluence gui launch

# Launch on custom port without opening browser
symfluence gui launch --port 8080 --no-browser

# Launch with a demo configuration
symfluence gui launch --demo bow

TUI Commands#

Launch the interactive terminal user interface.

tui launch#

Start the SYMFLUENCE interactive terminal UI.

symfluence tui launch [--demo NAME] [--config CONFIG]

Options:

  • --demo NAME: Load a built-in demo (e.g., “bow” for Bow at Banff)

Data Commands#

Download datasets independently without a full project setup.

data download#

Download a specific dataset.

symfluence data download DATASET [options]

Arguments:

  • DATASET: Dataset name (e.g., modis_lai, era5, grace)

Options:

  • --bbox LAT_MAX/LON_MIN/LAT_MIN/LON_MAX: Bounding box (required unless --config is provided)

  • --shapefile PATH: Shapefile to derive bounding box from (alternative to --bbox)

  • --start YYYY-MM-DD: Start date (required unless --config is provided)

  • --end YYYY-MM-DD: End date (required unless --config is provided)

  • --output PATH: Output directory (default: ./data/<dataset>)

  • --domain NAME: Domain name for file naming (default: standalone)

  • --force: Force re-download of existing data

  • --extra KEY=VALUE: Extra configuration keys (repeatable)

Examples:

# Download with explicit bounding box and dates
symfluence data download era5 --bbox 52/-116/50/-114 --start 2020-01-01 --end 2020-12-31

# Download using a shapefile for the bounding box
symfluence data download modis_lai --shapefile my_basin.shp --start 2020-01-01 --end 2020-12-31

# Download using settings from a config file
symfluence data download era5 --config my_config.yaml

data list#

List all available datasets.

symfluence data list

data info#

Show details about a specific dataset.

symfluence data info DATASET

Example:

symfluence data info era5

List Commands#

Introspect the live registry and config schema to discover what is available right now (models, datasets, optimizers, config keys, etc.). Because the catalog is read from the registry, it never goes stale.

list#

# Show every catalog and its count
symfluence list

# List the entries for one kind
symfluence list KIND

Kinds: models, forcings, observations, optimizers, targets, metrics, presets, templates, steps, config-keys.

Examples:

symfluence list models
symfluence list forcings
symfluence list config-keys

Doctor Command#

Run comprehensive system diagnostics (environment, path resolution, and binary checks). This is a top-level command (distinct from binary doctor, which is scoped to installed binaries).

symfluence doctor

FEWS Commands#

Delft-FEWS General Adapter operations — run pre/post processing and launch openFEWS with SYMFLUENCE adapter support.

fews pre#

Run the FEWS pre-adapter (import forcing, generate config).

symfluence fews pre --run-info run_info.xml [--format {pi-xml,netcdf-cf}] [--id-map PATH] [--config CONFIG]

fews post#

Run the FEWS post-adapter (export results, write diagnostics).

symfluence fews post --run-info run_info.xml [--format {pi-xml,netcdf-cf}] [--id-map PATH] [--config CONFIG]

fews run#

Run the full FEWS adapter cycle (pre -> model -> post).

symfluence fews run --run-info run_info.xml [--format {pi-xml,netcdf-cf}] [--id-map PATH] [--config CONFIG]

fews launch#

Launch openFEWS with SYMFLUENCE adapter support.

symfluence fews launch [--port PORT] [--no-browser] [--config CONFIG]

Options (pre/post/run):

  • --run-info PATH: Path to run_info.xml (required)

  • --format {pi-xml,netcdf-cf}: Data exchange format (default: netcdf-cf)

  • --id-map PATH: Variable ID mapping YAML file

Exit Codes#

All commands return standardized exit codes:

Code

Name

Meaning

0

SUCCESS

Command completed successfully

1

GENERAL_ERROR

General error

2

USAGE_ERROR

Invalid arguments/usage

3

CONFIG_ERROR

Configuration file issues

4

VALIDATION_ERROR

Input validation failed

5

FILE_NOT_FOUND

Required file missing

6

DIRECTORY_NOT_FOUND

Required directory missing

7

BINARY_ERROR

External binary not found

8

BINARY_BUILD_ERROR

Failed to build binary

9

NETWORK_ERROR

Network/download failure

10

PERMISSION_ERROR

Permission denied

11

TIMEOUT_ERROR

Operation timed out

12

DEPENDENCY_ERROR

Missing dependency

13

MODEL_ERROR

Model execution error

14

WORKFLOW_ERROR

Workflow execution error

15

DATA_ERROR

Data processing error

20

JOB_SUBMIT_ERROR

SLURM submission failed

21

JOB_EXECUTION_ERROR

Job execution failed

130

USER_INTERRUPT

User pressed Ctrl+C

143

SIGTERM

Process terminated

Common Usage Patterns#

Quick Project Setup#

# Interactive setup
symfluence project init --interactive --scaffold

# Or with preset
symfluence project init fuse-provo --scaffold

Complete Workflow#

# Validate first
symfluence workflow validate --config config.yaml

# Run everything
symfluence workflow run --config config.yaml

Selective Steps#

# Single step
symfluence workflow step calibrate_model --config config.yaml

# Multiple steps
symfluence workflow steps acquire_forcings run_model

# Resume from step
symfluence workflow resume calibrate_model --config config.yaml

HPC Submission#

# Save environment
module save symfluence_modules

# Submit with monitoring
symfluence job submit --time 72:00:00 --nodes 4 --wait \
  workflow run --config config.yaml

Debugging#

# Enable profiling
symfluence workflow run --config config.yaml --profile --profile-stacks

# Debug mode
symfluence workflow run --config config.yaml --debug

Getting Help#

# General help
symfluence --help

# Category help
symfluence workflow --help

# Command help
symfluence workflow run --help