HydroMT Command Line Interface#

The HydroMT command line interface (CLI) is a command line tool that allows you to run HydroMT commands from the terminal. It is installed as part of the HydroMT package. To use the CLI, you need to have HydroMT installed in your Python environment. If you have not installed HydroMT yet, please refer to the Installation section.

To use the HydroMT CLI, open a terminal and type hydromt followed by the command you want to run. you can also run hydromt --help to get an overview of which commands are available. The following commands are available:

Base commands#

The base commands or options are here to get some information about HydroMT like the help, installed version and available models.

Models command#

The hydromt --models command prints the available generic models from HydroMT core and the installed plugins together with their versions. For example:

> hydromt --models

Model plugins:
    - model (hydromt 1.0.0)

Build command#

The hydromt build command is used to build models from scratch. It has two mandatory arguments:

  • MODEL: The name of the model to build. The available models can be printed using the hydromt --models command.

  • MODEL_ROOT: Absolute or relative path to the output folder of the model to build.

The hydromt build command has several options to specify the configuration file, the region, the data catalog, and other options. The most important ones are:

  • -i, --config: Relative or absolute path to the HydroMT configuration file so that HydroMT knows what to prepare for our model (data to use, processing options etc.).

  • -d, --data: Relative or absolute path to the local yaml data catalog file or name of a predefined data catalog. The data catalog is a yaml file that contains the paths to the data that will be used to build the model.

Here is an example of how to use the command:

> hydromt build wflow /path/to/model_root -i /path/to/wflow_build_config.yml  -d deltares_data  -v

You can find more information on the steps to build a model in the Building a model section. In this section, you will also find how to prepare a workflow file. To know more about the data catalog, you can refer to the Working with data in HydroMT section.

Finally you can check the :ref: hydromt build API for all the available options for the build command.

Update command#

The hydromt update command is used to update an existing model. It is quite similar to the build command and has two mandatory arguments:

  • MODEL: The name of the model to update. The available models can be printed using the hydromt --models command.

  • MODEL_ROOT: Absolute or relative path to the model to update.

The hydromt update command has several options to specify the configuration file, the the data catalog, and other options. The most important ones are:

  • -i, --config: Relative or absolute path to the HydroMT configuration file so that HydroMT knows what to update for our model (data to use, processing options etc.).

  • -d, --data: Relative or absolute path to the local yaml data catalog file or name of a predefined data catalog. The data catalog is a yaml file that contains the paths to the data that will be used to update the model.

  • -o, --model-out: Relative or absolute path to the output folder of the updated model. If not provided, the current model will be overwritten.

Here is an example of how to use the command:

> hydromt update wflow /path/to/model_to_update -o /path/to/updated_model -i /path/to/wflow_update_config.yml -d /path/to/data_catalog.yml -v

You can find more information on the steps to update a model in the Updating a model section. In this section, you will also find how to prepare a workflow file. To know more about the data catalog, you can refer to the Working with data in HydroMT section.

Finally you can check the :ref: hydromt update API <update_api> for all the available options for the update command.

Export command#

The hydromt export command is used to export sample data from a data catalog for example to export global data for a specific region and time extent. It is based on the hydromt.DataCatalog.export_data function. It has one mandatory argument:

  • EXPORT_DEST_PATH: Absolute or relative path to the output folder of the exported data.

The input data catalogs are specified using the -d, --data option as in the build or update commands.

There are two ways to specify the sources/extent of the data to export: either fully from the command line or by using a configuration file.

If you are using the command line, the main options are:

  • -d, --data: Relative or absolute path to the local yaml data catalog file or name of a predefined data catalog. The data catalog is a yaml file that contains the paths to the data that will be used to export the data.

  • s, –source: The data source to export. Only one can be specified from the command line.

  • -t, --time: Set the time extent for which to export the data. The time extent is specified as a list with the start and end date.

Here is an example of how to use the command:

> hydromt export /path/to/exported_data -d /path/to/data_catalog.yml -s "era5" -t "['2010-01-01', '2010-01-31']" -v

If you want to export several sources or for more options, you can also use a configuration file instead. In that case, the main options are:

  • -i, --config: Relative or absolute path to the export configuration file. The export configuration file is a yaml file that contains the sources, region, and time extent to export.

And the command line would look like:

> hydromt export /path/to/exported_data -i /path/to/export_config.yml -v

An example of the export file is:

export_data:
    data_libs:
        - /path/to/data_catalog.yml
    region:
        bbox: [4.68,53.19,4.69,53.20]
    time_range: ['2010-01-01', '2020-12-31']
    sources:
        - hydro_lakes
        - era5
    unit_conversion: False
    append: False
    meta:
        version: 0.1

You can find detailed document on the function in hydromt.DataCatalog.export_data. For the region, only the bbox and geom types are supported, see the :ref:` region <region>` section for more information.

Finally you can check the :ref: hydromt export API <export_api> for all the available options for the export command.

Check command#

The hydromt check command is used to validate the configuration file, the data catalog, and the region. It can be useful to validate files before running other command lines to avoid errors. Please note that it will only check the syntax of the files provided. The actual data or calculations referenced will not be checked, loaded or performed.

The command does not have any required arguments but several options that you can choose from:

  • -m, --model: The name of the model to validate. The available models can be printed using the hydromt --models command.

  • -i, --config: Relative or absolute path to the HydroMT configuration file to validate.

  • -d, --data: Relative or absolute path to the local yaml data catalog file or name of a predefined data catalog to validate.

If you only wish to validate a region or a data catalog files, they can be run separately. Because configuration files are dependant on the model to build/update, to check a configuration file, you need to specify the model.

Here are some examples of how to use the command:

> hydromt check -m wflow -i /path/to/wflow_config.yml -d /path/to/data_catalog.yml -v

> hydromt check -d /path/to/data_catalog.yml -v

> hydromt check -m wflow -i /path/to/wflow_config.yml -v

The validation is so far limited:

  • region: full validation is only supported for the bbox and geom types. For other type, it will only check if the type is supported but will not validate the region itself.

  • data catalog: only the format and options are validated but it does not try to load any of the data.

  • configuration file: it will check if the methods exists and if the correct arguments are called. No validation is done on the content and type of the arguments themselves.

Finally you can check the :ref: hydromt check API <check_api> for all the available options for the check command.

On this page
Edit on GitHub
Show Source