# noaa-gfdl/fre-cli architecture

> Architecture diagram of the GitHub repository noaa-gfdl/fre-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noaa-gfdl/fre-cli
- Repository: https://github.com/noaa-gfdl/fre-cli

## Overview

fre-cli is a Click-based command-line interface for GFDL’s FRE workflow. Users invoke a tool and subtool; commands then discover and combine YAML configuration before performing a workflow action such as building a model, processing scientific data, or running analysis. The graph preserves documented and indexed subsystems, but many are unsampled, so their internal links are omitted rather than inferred. The README establishes the CLI purpose; source-index references and excerpts support the specific connections shown.

Main entry points: [`fre/make/create_makefile_script.py`](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_makefile_script.py) (Makefile generation), [`fre/make/create_docker_script.py`](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_docker_script.py) (Container builds), [`fre/make/create_checkout_script.py`](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_checkout_script.py) (Checkout scripts), [`fre/make/create_compile_script.py`](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_compile_script.py) (Compile scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Command groups<br/>[fre.py]"]
  node_lazy["Lazy dispatch<br/>[lazy_group.py]"]
end

subgraph group_config["Configuration"]
  node_list_yaml["YAML discovery"]
  node_combine_yaml["YAML composition"]
  node_yaml_helpers["YAML helpers<br/>[helpers.py]"]
end

subgraph group_build["Model build"]
  node_make_cli["Make commands<br/>[fremake.py]"]
  node_checkout_script["Checkout scripts"]
  node_checkout_impl["Source checkout<br/>[checkout.py]"]
  node_makefile_script["Makefile generation"]
  node_makefile_impl["Makefile writer<br/>[makefilefre.py]"]
  node_compile_script["Compile scripts"]
  node_docker_script["Container builds"]
  node_docker_impl["Docker builder<br/>[buildDocker.py]"]
  node_make_config["Build configuration<br/>[yamlfre.py]"]
  node_make_vars["Variable substitution<br/>[varsfre.py]"]
  node_make_targets["Build targets<br/>[targetfre.py]"]
end

subgraph group_science["Scientific workflows"]
  node_averages["Time averages"]
  node_python_avg["Python averager"]
  node_nctools_avg["NCTools averager"]
  node_app_tools["Scientific app tools"]
  node_postprocess["Postprocessing"]
end

subgraph group_operations["Workflow tools"]
  node_analysis["Analysis plugins<br/>[subtools.py]"]
  node_catalog["Catalog<br/>[frecatalog.py]"]
  node_cmor["CMOR tools<br/>[frecmor.py]"]
  node_listing["FRE listings"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_lazy
node_make_cli --> node_cli
node_cli -.-> node_averages
node_cli -->|"loads"| node_analysis
node_make_cli -->|"calls"| node_checkout_script
node_make_cli -->|"calls"| node_makefile_script
node_make_cli -->|"calls"| node_compile_script
node_make_cli -->|"calls"| node_docker_script
node_checkout_script -->|"uses"| node_checkout_impl
node_checkout_script -->|"uses"| node_make_config
node_checkout_script -->|"uses"| node_make_vars
node_makefile_script -->|"uses"| node_makefile_impl
node_makefile_script -->|"uses"| node_make_config
node_makefile_script -->|"uses"| node_make_vars
node_makefile_script -->|"uses"| node_make_targets
node_compile_script -->|"uses"| node_make_config
node_compile_script -->|"uses"| node_make_vars
node_compile_script -->|"uses"| node_make_targets
node_docker_script -->|"uses"| node_docker_impl
node_docker_script -->|"uses"| node_make_config
node_docker_script -->|"uses"| node_make_vars
node_docker_script -->|"uses"| node_make_targets
node_makefile_script -->|"queries"| node_list_yaml
node_makefile_script -->|"composes"| node_combine_yaml
node_checkout_script -->|"queries"| node_list_yaml
node_checkout_script -->|"composes"| node_combine_yaml
node_compile_script -->|"queries"| node_list_yaml
node_compile_script -->|"composes"| node_combine_yaml
node_docker_script -->|"queries"| node_list_yaml
node_docker_script -->|"composes"| node_combine_yaml
node_averages -->|"selects"| node_python_avg
node_averages -->|"selects"| node_nctools_avg
node_averages -.-> node_app_tools
node_list_yaml -.-> node_combine_yaml
node_analysis -.->|"runs plugins with"| node_catalog

click node_cli "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/fre.py"
click node_lazy "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/lazy_group.py"
click node_list_yaml "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/list_/list_yamls_script.py"
click node_combine_yaml "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/yamltools/combine_yamls_script.py"
click node_yaml_helpers "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/yamltools/helpers.py"
click node_make_cli "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/fremake.py"
click node_checkout_script "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_checkout_script.py"
click node_checkout_impl "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/checkout.py"
click node_makefile_script "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_makefile_script.py"
click node_makefile_impl "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/makefilefre.py"
click node_compile_script "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_compile_script.py"
click node_docker_script "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_docker_script.py"
click node_docker_impl "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/buildDocker.py"
click node_make_config "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/yamlfre.py"
click node_make_vars "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/varsfre.py"
click node_make_targets "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/targetfre.py"
click node_averages "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/generate_time_averages.py"
click node_python_avg "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/frepytoolsTimeAverager.py"
click node_nctools_avg "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/frenctoolsTimeAverager.py"
click node_app_tools "https://github.com/noaa-gfdl/fre-cli/tree/main/fre/app"
click node_postprocess "https://github.com/noaa-gfdl/fre-cli/tree/main/fre/pp"
click node_analysis "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/analysis/subtools.py"
click node_catalog "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/catalog/frecatalog.py"
click node_cmor "https://github.com/noaa-gfdl/fre-cli/blob/main/fre/cmor/frecmor.py"
click node_listing "https://github.com/noaa-gfdl/fre-cli/tree/main/fre/list_"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lazy,node_user toneBlue
class node_list_yaml,node_combine_yaml,node_yaml_helpers toneAmber
class node_make_cli,node_checkout_script,node_checkout_impl,node_makefile_script,node_makefile_impl,node_compile_script,node_docker_script,node_docker_impl,node_make_config,node_make_vars,node_make_targets toneMint
class node_averages,node_python_avg,node_nctools_avg,node_app_tools,node_postprocess toneRose
class node_analysis,node_catalog,node_cmor,node_listing toneIndigo
```

## Components

### CLI entry

- [Command groups](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/fre.py): `fre/fre.py`
- [Lazy dispatch](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/lazy_group.py): `fre/lazy_group.py`

### Configuration

- [YAML discovery](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/list_/list_yamls_script.py): `fre/list_/list_yamls_script.py`
- [YAML composition](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/yamltools/combine_yamls_script.py): `fre/yamltools/combine_yamls_script.py`
- [YAML helpers](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/yamltools/helpers.py): `fre/yamltools/helpers.py`

### Model build

- [Make commands](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/fremake.py): `fre/make/fremake.py`
- [Checkout scripts](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_checkout_script.py): `fre/make/create_checkout_script.py`
- [Source checkout](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/checkout.py): `fre/make/gfdlfremake/checkout.py`
- [Makefile generation](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_makefile_script.py): `fre/make/create_makefile_script.py`
- [Makefile writer](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/makefilefre.py): `fre/make/gfdlfremake/makefilefre.py`
- [Compile scripts](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_compile_script.py): `fre/make/create_compile_script.py`
- [Container builds](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/create_docker_script.py): `fre/make/create_docker_script.py`
- [Docker builder](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/buildDocker.py): `fre/make/gfdlfremake/buildDocker.py`
- [Build configuration](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/yamlfre.py): `fre/make/gfdlfremake/yamlfre.py`
- [Variable substitution](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/varsfre.py): `fre/make/gfdlfremake/varsfre.py`
- [Build targets](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/make/gfdlfremake/targetfre.py): `fre/make/gfdlfremake/targetfre.py`

### Scientific workflows

- [Time averages](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/generate_time_averages.py): `fre/app/generate_time_averages/generate_time_averages.py`
- [Python averager](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/frepytoolsTimeAverager.py): `fre/app/generate_time_averages/frepytoolsTimeAverager.py`
- [NCTools averager](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/app/generate_time_averages/frenctoolsTimeAverager.py): `fre/app/generate_time_averages/frenctoolsTimeAverager.py`
- [Scientific app tools](https://github.com/noaa-gfdl/fre-cli/tree/main/fre/app): `fre/app`
- [Postprocessing](https://github.com/noaa-gfdl/fre-cli/tree/main/fre/pp): `fre/pp`

### Workflow tools

- [Analysis plugins](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/analysis/subtools.py): `fre/analysis/subtools.py`
- [Catalog](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/catalog/frecatalog.py): `fre/catalog/frecatalog.py`
- [CMOR tools](https://github.com/noaa-gfdl/fre-cli/blob/main/fre/cmor/frecmor.py): `fre/cmor/frecmor.py`
- [FRE listings](https://github.com/noaa-gfdl/fre-cli/tree/main/fre/list_): `fre/list_`

### Other components

- **CLI user**

## Connections

- CLI user → Command groups: invokes (evidence: `README.md`)
- Command groups → Lazy dispatch: dispatches (evidence: `fre/fre.py`)
- Make commands → Command groups (evidence: `fre/fre.py`)
- Command groups → Time averages
- Command groups → Analysis plugins: loads (evidence: `fre/fre.py`)
- Make commands → Checkout scripts: calls (evidence: `fre/make/fremake.py`)
- Make commands → Makefile generation: calls (evidence: `fre/make/fremake.py`)
- Make commands → Compile scripts: calls (evidence: `fre/make/fremake.py`)
- Make commands → Container builds: calls (evidence: `fre/make/fremake.py`)
- Checkout scripts → Source checkout: uses (evidence: `fre/make/create_checkout_script.py`)
- Checkout scripts → Build configuration: uses (evidence: `fre/make/create_checkout_script.py`)
- Checkout scripts → Variable substitution: uses (evidence: `fre/make/create_checkout_script.py`)
- Makefile generation → Makefile writer: uses (evidence: `fre/make/create_makefile_script.py`)
- Makefile generation → Build configuration: uses (evidence: `fre/make/create_makefile_script.py`)
- Makefile generation → Variable substitution: uses (evidence: `fre/make/create_makefile_script.py`)
- Makefile generation → Build targets: uses (evidence: `fre/make/create_makefile_script.py`)
- Compile scripts → Build configuration: uses (evidence: `fre/make/create_compile_script.py`)
- Compile scripts → Variable substitution: uses (evidence: `fre/make/create_compile_script.py`)
- Compile scripts → Build targets: uses (evidence: `fre/make/create_compile_script.py`)
- Container builds → Docker builder: uses (evidence: `fre/make/create_docker_script.py`)
- Container builds → Build configuration: uses (evidence: `fre/make/create_docker_script.py`)
- Container builds → Variable substitution: uses (evidence: `fre/make/create_docker_script.py`)
- Container builds → Build targets: uses (evidence: `fre/make/create_docker_script.py`)
- Makefile generation → YAML discovery: queries (evidence: `fre/make/create_makefile_script.py`)
- Makefile generation → YAML composition: composes (evidence: `fre/make/create_makefile_script.py`)
- Checkout scripts → YAML discovery: queries (evidence: `fre/make/create_checkout_script.py`)
- Checkout scripts → YAML composition: composes (evidence: `fre/make/create_checkout_script.py`)
- Compile scripts → YAML discovery: queries (evidence: `fre/make/create_compile_script.py`)
- Compile scripts → YAML composition: composes (evidence: `fre/make/create_compile_script.py`)
- Container builds → YAML discovery: queries (evidence: `fre/make/create_docker_script.py`)
- Container builds → YAML composition: composes (evidence: `fre/make/create_docker_script.py`)
- Time averages → Python averager: selects (evidence: `fre/app/generate_time_averages/generate_time_averages.py`)
- Time averages → NCTools averager: selects (evidence: `fre/app/generate_time_averages/generate_time_averages.py`)
- Time averages → Scientific app tools (evidence: `fre/app/generate_time_averages/generate_time_averages.py`)
- YAML discovery → YAML composition
- Analysis plugins → Catalog: runs plugins with