How to Install Optional Channel Dependencies in Agent-Reach Using the `--channels` Flag

The --channels flag triggers a deterministic workflow that parses comma-separated platform names, maps them to dedicated installer functions in agent_reach/cli.py, and executes environment-specific dependency resolution with automatic health verification.

Agent-Reach is an open-source automation framework that keeps its core installation lightweight while offering optional integrations for platforms like Twitter, Reddit, and LinkedIn. When you need specific platform backends, understanding how to use the --channels flag to install optional channel dependencies ensures you only provision what your deployment actually requires.

Parsing the --channels Input

The CLI entry point in agent_reach/cli.py defines the --channels option at lines 75-78. This argument expects a comma-separated list of channel names (e.g., twitter,xiaohongshu). The _cmd_install function receives this string and passes it through a normalization routine that splits, strips whitespace, and converts each token to lowercase at lines 13-18.

Mapping Channels to Installers

Inside _cmd_install, a static dictionary named CHANNEL_INSTALLERS (lines 98-107) maps each supported channel name to its corresponding installer function. This design isolates platform-specific logic into discrete units such as _install_twitter_deps or _install_xiaoyuzhou_deps, preventing dependency conflicts and enabling modular maintenance.

Resolving the all Keyword and Channel Sets

If you pass the special value all, the resolver expands the request to include every key in CHANNEL_INSTALLERS plus cookie-only channels like xueqiu and linkedin (lines 12-19). This expansion happens before environment filtering, ensuring comprehensive coverage while still allowing platform-specific exclusions in headless environments.

Environment-Specific Channel Filtering

For server or headless deployments, the installer applies additional logic at lines 30-35 to remove OpenCLI-only channels—specifically opencli, facebook, and instagram—from the requested set. These channels require a desktop Chrome session that is unavailable in server environments, so the CLI automatically excludes them to prevent installation failures.

Executing the Installer Pipeline

After core system dependencies are satisfied, the CLI iterates over the sorted requested_channels at lines 71-78. For each channel, it performs a dictionary lookup in CHANNEL_INSTALLERS and executes the matched function exactly once. This guarantees that even if all is specified or duplicates exist in the input, each installer runs a single time.

Inside the Installer Functions

Each installer follows a consistent pattern exemplified by _install_twitter_deps at lines 102-122. The function first checks for existing tool presence using shutil.which. If the binary is missing, it attempts automatic installation using pipx (preferred) or uv, falling back to printed manual instructions if package managers are unavailable. This approach avoids forced system-wide installations while keeping the process automated when possible.

Post-Installation Verification

Once optional channel dependencies are provisioned, the workflow continues at lines 84-92 with automatic cookie imports for authentication-dependent platforms (Twitter, Xueqiu, Bilibili). Finally, the CLI invokes the doctor module to run health checks, confirming that each installed channel responds correctly to can_handle and check operations before completing the installation.

Command Examples

Install a Single Channel

Install only the Twitter backend dependencies:

agent-reach install --channels twitter

This checks system dependencies, executes _install_twitter_deps to install twitter-cli via pipx or uv, and imports any saved Twitter cookies.

Install Multiple Channels

Provision both Twitter and Reddit support:

agent-reach install --channels twitter,reddit

The installer runs both _install_twitter_deps and detects the local environment to include _install_opencli_deps for Reddit, skipping execution if rdt-cli is already present.

Install All Available Channels

Deploy every optional integration:

agent-reach install --channels all

This expands to all entries in CHANNEL_INSTALLERS plus xueqiu and linkedin, executing each installer once while automatically excluding OpenCLI-only channels on servers.

Dry-Run Mode

Preview what would be installed without making changes:

agent-reach install --dry-run --channels twitter,reddit

Output:

[dry-run] Would install optional channels: reddit, twitter

Safe Mode

Display manual instructions without invoking package managers:

agent-reach install --safe --channels twitter

This reports system dependencies and prints manual installation commands for each missing tool without running automatic pipx or uv calls.

Summary

• The --channels flag accepts comma-separated platform names or the special value all to target specific optional channel dependencies
• CHANNEL_INSTALLERS in agent_reach/cli.py (lines 98-107) maps each channel to a dedicated installer function that runs exactly once per channel
• Server environments automatically exclude OpenCLI-only channels (facebook, instagram, opencli) at lines 30-35 due to desktop Chrome requirements
• Individual installers check for existing binaries with shutil.which and prefer pipx or uv for automatic resolution, falling back to manual instructions
• Post-installation includes cookie imports for authentication-dependent platforms and health verification via the doctor module

Frequently Asked Questions

What file contains the core logic for the --channels flag?

The implementation resides in agent_reach/cli.py, specifically within the _cmd_install function. Lines 75-78 define the argument parser, while lines 98-107 contain the CHANNEL_INSTALLERS dictionary that maps platform names to their specific installer functions like _install_twitter_deps.

Can I install all optional channels simultaneously?

Yes. Specifying --channels all triggers an expansion at lines 12-19 that includes every key in CHANNEL_INSTALLERS plus cookie-only channels such as xueqiu and linkedin. The installer executes each exactly once, automatically filtering out incompatible channels like facebook and instagram when running in server environments.

How does the installer handle tools that are already present?

Each installer function uses shutil.which to check for existing binaries before attempting installation. If the tool is found, the function returns immediately without modification, ensuring idempotent installations that respect existing system configurations.

Why are some channels excluded on servers?

Channels requiring OpenCLI—specifically facebook, instagram, and the opencli backend—depend on a desktop Chrome session for automation. Lines 30-35 in agent_reach/cli.py detect server environments and remove these channels from the installation queue to prevent runtime failures in headless deployments.

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