How to Use the abx-dl --plugins Option to Select Specific Plugins for Downloads

Use the -p or --plugins flag followed by a comma-separated list of plugin names (e.g., --plugins=wget,ytdlp,git) to limit abx-dl to specific ArchiveBox plugins instead of running all discovered ones.

The abx-dl command-line tool from the archivebox/abx-dl repository enables you to download content using modular ArchiveBox plugins. By default, the tool executes every discovered plugin, but you can use the abx-dl --plugins option to select specific plugins for a download, improving efficiency and customizing output behavior.

How the abx-dl --plugins Option Works Internally

Plugin Discovery in cli.py

When the CLI initializes, it discovers every plugin under abx_dl/plugins and stores them in ctx.obj['plugins'] according to the source code in abx_dl/cli.py (lines 58-60). This discovery happens before any command execution, ensuring all available plugins are known upfront.

Parsing the Comma-Separated Input

The dl command defines the option --plugins (short form -p) as a comma-separated string parameter in abx_dl/cli.py (lines 64-66). This design allows you to pass multiple plugin names in a single argument rather than repeating flags.

Selection and Filtering Logic

Inside the dl function, the input string is split on commas, stripped of whitespace, and stored as a selected list (lines 84-90 in abx_dl/cli.py). This list passes to the executor in abx_dl/executor.py, which forwards it to the filter_plugins function in abx_dl/plugins.py (lines 77-88). The filter_plugins function returns only plugins whose names match the supplied list, effectively limiting the download to your specified subset.

Practical Usage Examples for Selecting Plugins

Default Behavior (All Plugins)

When you omit the flag, all discovered plugins run automatically:

abx-dl "https://example.com"

Select Specific Plugins with --plugins

Pass a comma-separated list of plugin names (no spaces required, though whitespace is stripped):

abx-dl --plugins=wget,ytdlp,git "https://example.com"

Use the short form for brevity:

abx-dl -p wget,ytdlp,git "https://example.com"

The flag accepts any plugin name present in the abx_dl/plugins directory, such as wget, ytdlp, or git.

Using the Flag in Python Scripts

You can invoke the tool via subprocess while dynamically constructing the plugin list:

import subprocess

url = "https://example.com"
plugins = "wget,ytdlp"
subprocess.run(["abx-dl", f"--plugins={plugins}", url], check=True)

Combining with Other CLI Options

The --plugins flag works alongside other arguments like --output and --timeout:

abx-dl -p wget,ytdlp \
        --output=/tmp/archive \
        --timeout=120 \
        "https://example.com"

Key Source Files and Implementation Details

Understanding the following files helps when debugging or extending the --plugins functionality:

• abx_dl/cli.py – Defines the --plugins option, parses the comma-separated list in the dl command, and passes the selected plugins to the download generator (lines 62-90).
• abx_dl/plugins.py – Contains the discover_plugins function for initial loading, the filter_plugins function (lines 77-88) that implements the selection logic, and the Plugin data class that represents individual plugins.
• abx_dl/executor.py – Runs the actual download workflow; receives the filtered plugin set from cli.py and executes each plugin's hooks according to the filtered sequence.

Summary

• Use --plugins or -p followed by comma-separated names to limit which plugins run during a download.
• Omitting the flag runs all discovered plugins automatically.
• The filtering occurs in filter_plugins within abx_dl/plugins.py after the CLI parses and splits the input string in abx_dl/cli.py.
• Plugin names must match those discovered in the abx_dl/plugins directory at runtime.
• The implementation automatically handles whitespace around commas when parsing the list.

Frequently Asked Questions

What happens if I don't specify the --plugins flag?

If you omit the --plugins option, all discovered plugins are used for the download. The tool automatically discovers every plugin under abx_dl/plugins during CLI initialization (lines 58-60 in abx_dl/cli.py) and executes them without filtering.

Can I use spaces in the comma-separated plugin list?

Yes, the implementation in abx_dl/cli.py automatically strips whitespace from each plugin name after splitting the comma-separated string (lines 84-90). Both --plugins=wget, ytdlp and --plugins=wget,ytdlp are valid and resolve to the same plugin selection.

How do I find which plugin names are available?

Available plugin names correspond to the subdirectories or modules within the abx_dl/plugins directory. The CLI discovers these at runtime via the discover_plugins function and stores them in the Click context object during initialization (lines 58-60 in abx_dl/cli.py).

Can I exclude specific plugins instead of including them?

The current implementation only supports an inclusion list via --plugins. To exclude specific plugins, you must specify all desired plugins explicitly, omitting the ones you wish to exclude. There is no built-in --exclude-plugins flag in the current version.

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