Configuration

This page details some of the options available for configuring your esgpull installation.

Configuration

On invocation, $ esgpull config will show the base configurations in the terminal.

$ esgpull config

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────── /home/me/.esgpull/config.toml ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
[paths]
data = "/home/me/.esgpull/data"
db = "/home/me/.esgpull/db"
log = "/home/me/.esgpull/log"
tmp = "/home/me/.esgpull/tmp"

[credentials]
filename = "credentials.toml"

[cli]
page_size = 20

[db]
filename = "esgpull.db"

[download]
chunk_size = 67108864
http_timeout = 20
max_concurrent = 5
disable_ssl = false

[api]
index_node = "esgf-node.ipsl.upmc.fr"
http_timeout = 20
max_concurrent = 5
page_limit = 50

[api.default_options]
distrib = "false"
latest = "true"
replica = "none"
retracted = "false"

[plugins]
enabled = "false"

To modify a config item from the command line, the dot-separated path to that item must be provided as the first argument along with the new value that item should get as the second argument:

$ esgpull config api.index_node esgf-data.dkrz.de

[api]
index_node = "esgf-data.dkrz.de"

Previous value: esgf-node.ipsl.upmc.fr

On first call, this will generate a config.toml file in the ~/.esgpull directory with only the modified values:

$ esgpull config api.index_node esgf-data.dkrz.de

[api]
index_node = "esgf-data.dkrz.de"

👍 New config file created at /home/srodriguez/.esgpull_test_config_generate/config.toml.

If a user wishes to simply generate the config.toml file without modifying any values, they simply must run the following:

$ esgpull config --generate

👍 Config generated at /home/me/.esgpull/config.toml

Complete existing config with defaults

The --generate flag also works when a configuration file already exists.

In this case, a prompt will ask for permission to fill the existing file with default values for all missing options:

$ esgpull config --generate

A config file already exists, fill it with missing defaults? [y/n] (n): y
👍 Config generated at /home/me/.esgpull/config.toml

Index Node Configuration

The api.index_node setting determines which ESGF index node esgpull will query for dataset metadata and search results.

esg-search Index Nodes

esgpull uses a single regional ESGF index node, backed by the esg-search API, the endpoint can be changed through configuration:

$ esgpull config api.index_node esgf-node.ipsl.upmc.fr

Other available index nodes include:

• esgf.ceda.ac.uk (UK)
• esgf-data.dkrz.de (Germany)
• esgf-node.ornl.gov/esgf-1-5-bridge (USA, Bridge API)
• find more at https://esgf.github.io/nodes.html

Bridge API

The ORNL Bridge API node provides a temporary wrapper mimicking the API surface of the legacy esg-search code. This Bridge API has replaced the regular ORNL endpoint.

To use the ORNL node, you must specify the Bridge API path:

$ esgpull config api.index_node esgf-node.ornl.gov/esgf-1-5-bridge

Bridge API Compatibility

The Bridge API has some limitations compared to standard ESGF index nodes:

• The retracted option is not supported and will be automatically removed from queries
• The fields parameter is not supported
• Facet queries may behave differently than on standard nodes

esgpull automatically detects when you're using a Bridge API endpoint (by checking for esgf-1-5-bridge in the URL) and adjusts query parameters accordingly to ensure compatibility.

Login (deprecated)

Login is not longer required and has been removed from esgpull. Existing auth folder in esgpull installation folder can be removed safely.

Plugins

Plugin functionality is disabled by default and can be enabled with:

$ esgpull config plugins.enabled true

Plugin-specific configurations are managed separately through the esgpull plugins config command and stored in a dedicated plugins.toml file. See the Plugins page for more information.