How abx-dl Handles Configuration Aliases Like USE_WGET and WGET_ENABLED

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: 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 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) 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 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 file using the JSON Schema extension property x-aliases. For example, the wget plugin defines WGET_ENABLED with USE_WGET as an accepted alternative:

{
  "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:

# 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 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, 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 schema automatically gains alias support, as the core configuration system in abx-dl handles the resolution logic universally for all loaded plugins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}