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.

```shell
$ 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:

```shell
$ esgpull config api.index_node esgf-data.dkrz.de
```
```shell
[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:

```shell
$ esgpull config api.index_node esgf-data.dkrz.de
```
```shell
[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:

```shell
$ esgpull config --generate
```
```shell
👍 Config generated at /home/me/.esgpull/config.toml
```

!!! note "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:

    ```shell
    $ esgpull config --generate
    ```
    ```shell
    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:

```shell
$ 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:

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

!!! note "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:

```shell
$ 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](plugins) for more information.
