# How abx-dl Handles Configuration Aliases Like USE_WGET and WGET_ENABLED

> Discover how abx-dl's config system resolves aliases like USE_WGET to WGET_ENABLED by scanning plugin JSON schemas for x-aliases definitions during read and write operations.

- Repository: [ArchiveBox/abx-dl](https://github.com/archivebox/abx-dl)
- Tags: internals
- Published: 2026-02-25

---

**The abx-dl configuration system resolves aliases like `USE_WGET` to their canonical keys such as `WGET_ENABLED` by scanning plugin JSON schemas for `x-aliases` definitions during both write and read operations.**

The `abx-dl` tool provides a flexible configuration layer that lets plugin authors expose canonical setting names while allowing users to set values using alternative, often more readable aliases. This bidirectional alias resolution ensures backward compatibility and improves usability without requiring changes to underlying plugin code. Understanding how this mapping works helps you debug configuration issues and leverage shorter or legacy key names interchangeably.

## How Alias Resolution Works in abx-dl

The alias handling mechanism operates in two distinct phases within [`abx_dl/config.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py): when persisting values to disk and when retrieving them from the environment.

### Resolving Aliases When Setting Values

When you execute `abx-dl config --set`, the `set_config()` function immediately calls `resolve_alias()` to normalize the key name. According to the source code in [[`abx_dl/config.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py) lines 111–128](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py#L111-L128), this function scans every loaded plugin’s JSON schema ([`config.json`](https://github.com/archivebox/abx-dl/blob/main/config.json)) for an `x-aliases` array containing the supplied key. If a match is found, `resolve_alias()` returns the canonical property name, and the value is written to `~/.config/abx/config.env` under that canonical key rather than the alias.

### Resolving Aliases When Reading Values

During retrieval, `get_config_value()` in [[`abx_dl/config.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py) lines 250–256](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py#L250-L256) first checks for an exact environment variable match. If the canonical key is not set, the function iterates over each property’s `x-aliases` list and returns the value from the first matching alias it finds. If no alias matches, the system falls back to a declared `x-fallback`, the schema default, or a global default value.

## Defining Aliases in Plugin Schema

Plugins declare their canonical settings and associated aliases in a [`config.json`](https://github.com/archivebox/abx-dl/blob/main/config.json) file using the JSON Schema extension property `x-aliases`. For example, the wget plugin defines `WGET_ENABLED` with `USE_WGET` as an accepted alternative:

```json
{
  "WGET_ENABLED": {
    "type": "boolean",
    "default": true,
    "x-aliases": ["USE_WGET"]
  }
}

```

This schema declaration allows users to set either `USE_WGET` or `WGET_ENABLED`, with the system treating both as references to the same underlying configuration value.

## Practical Usage Examples

You can use aliases and canonical keys interchangeably in the command line interface. Both commands below modify the same persistent configuration value:

```bash

# Disable wget using the alias

abx-dl config --set USE_WGET=false

# Verify the value using the canonical key

abx-dl config --get WGET_ENABLED

# Output: false

# Re-enable using the canonical name

abx-dl config --set WGET_ENABLED=true

# Read back using the alias

abx-dl config --get USE_WGET

# Output: true

```

Regardless of which name you use, `abx-dl` stores the value under the canonical key `WGET_ENABLED` in the persistent config file.

## Summary

- **Bidirectional resolution:** The `resolve_alias()` function handles normalization when writing, while `get_config_value()` checks aliases when reading.
- **Schema-driven:** Aliases are defined per-plugin in [`config.json`](https://github.com/archivebox/abx-dl/blob/main/config.json) using the `x-aliases` array property.
- **Persistent storage:** All values are stored under canonical keys in `~/.config/abx/config.env`, even when set via an alias.
- **Fallback chain:** If an alias is not set, the system checks `x-fallback`, schema defaults, and global defaults in sequence.

## Frequently Asked Questions

### Where does abx-dl store the canonical configuration keys?

The system persists all configuration values under their canonical names in `~/.config/abx/config.env`, regardless of whether you used an alias or the primary key when setting the value.

### Can a single configuration key have multiple aliases?

Yes, the `x-aliases` property accepts an array of strings, allowing plugins to define multiple alternative names for one setting (for example, `["USE_WGET", "ENABLE_WGET", "WGET_BIN_ENABLED"]`).

### What happens if both the alias and the canonical key are set in the environment?

According to the implementation in [`abx_dl/config.py`](https://github.com/archivebox/abx-dl/blob/main/abx_dl/config.py), `get_config_value()` checks for an exact match of the canonical key first, so the canonical key takes precedence over any aliases during value retrieval.

### Do all abx-dl plugins automatically support configuration aliases?

Any plugin that includes an `x-aliases` definition in its [`config.json`](https://github.com/archivebox/abx-dl/blob/main/config.json) schema automatically gains alias support, as the core configuration system in `abx-dl` handles the resolution logic universally for all loaded plugins.