README.md

FRE-CLI

FMS Runtime Environment (FRE) CLI developed using Python's Click package

• Sphinx Documentation

Background

fre-cli is a modern, user-friendly CLI that will allow users to call FRE commands using a fre tool subtool syntax. Leveraging Click, an easily installable Python package available via PyPI and/or Conda, fre-cli gives users intuitive and easy-to-understand access to many FRE tools and workflows from one packaged, centralized CLI.

Usage (Users)

(Method 1) User - with Lmod

• If you want to hit the ground running:
  • Cannot install local changes on top via pip
  • GFDL Workstation: module load fre/canopy
  • Gaea: module load fre/canopy

(Method 2) User - Conda Environment Activation

• If you want to hit the ground running, but have some flexibility in including other things without full development options available to you:

  • Can install local changes on top via pip
  • GFDL Workstation:

    module load miniforge
    conda activate /nbhome/fms/conda/envs/fre-cli
    

  • Gaea:

    module use /usw/conda/modulefiles
    module load miniforge
    conda activate /ncrc/home2/Flexible.Modeling.System/conda/envs/fre-cli
    

(Method 3) Developer - Conda Environment Building

• If you have Conda loaded and want to create your OWN environment for development, testing, etc.:

  • Can install local changes on top via pip
  • Steps:

    # Create new conda enironment
    conda create -n [environmentName]
    
    # Append necessary channels
    conda config --append channels noaa-gfdl
    conda config --append channels conda-forge
    
    # Run `conda install` on needed dependencies (`conda install click` will give you access to pip as well)
    # should install the [CLI package](https://anaconda.org/NOAA-GFDL/fre-cli) created from the [`meta.yaml`](https://github.com/NOAA-GFDL/fre-cli/blob/refactoring/meta.yaml)
    conda install noaa-gfdl::fre-cli         
    

  • All other dependencies used by the tools are installed along with this install (configured inside the meta.yaml), with the exception of local modules
  • setup.py file allows fre.py to be ran with fre as the entry point on the command line instead of python fre.py
  • For further notes on development and contributing to fre-cli see CONTRIBUTING.md

After one of the above, one can enter commands and follow --help messages for guidance. A brief rundown of commands to be provided are within each tool's folder as a README.md

Further Notes on Use

Following the instructions above, the user will be able to run fre from any directory, listing all command groups. These include e.g. run, make, and pp. The list of available subcommands for each group will be shown upon inclusion of the --help flag. The user will be alerted to any missing arguments required subcomands. Optional arguments will only shown with --help added to the subcommand. Note that argument flags are not positional, and can be specified in any order.

Checklist: Currently Implemented Tools

To be developed:

• fre app
• fre catalog
• fre check
• fre cmor
• fre list
• fre make
• fre pp
• fre run
• fre test
• fre yamltools