How Agent Reach Install Command Manages Optional Channel Dependencies Using `--channels`

The agent-reach install command parses the --channels flag to validate, filter by environment, and dispatch platform-specific dependency installers.

Agent Reach is an open-source social media automation toolkit that supports multiple platforms through optional channel dependencies. The install command's --channels flag provides granular control over which external tools get installed, adapting automatically to desktop or server environments.

How the --channels Flag Works

The flag accepts a comma-separated list of platform identifiers. According to the agent_reach/cli.py source, valid values include twitter, xiaoyuzhou, xueqiu, xiaohongshu, reddit, facebook, instagram, bilibili, linkedin, or the special value all.

p_install.add_argument("--channels", default="",
                       help="Comma-separated optional channels to install "
                            "(twitter,xiaoyuzhou,xueqiu,xiaohongshu,"
                            "reddit,facebook,instagram,bilibili,linkedin,all)")

(source: agent_reach/cli.py L75-L78)

The Channel Installer Dispatch System

At the core of dependency management is the CHANNEL_INSTALLERS dictionary, mapping each supported channel to its specialized installer function.

CHANNEL_INSTALLERS = {
    "twitter":     _install_twitter_deps,
    "xiaoyuzhou":  _install_xiaoyuzhou_deps,
    "xiaohongshu": _install_xhs_deps,
    "reddit":      _install_reddit_deps,
    "facebook":    _install_opencli_deps,
    "instagram":   _install_opencli_deps,
    "bilibili":    _install_bili_deps,
    "opencli":     _install_opencli_deps,
    # xueqiu & linkedin have no installer step

}

(source: agent_reach/cli.py L21-L31)

Note that xueqiu and linkedin require no external dependencies, so they have no installer entries. Facebook, Instagram, and Reddit share the _install_opencli_deps function, which pulls in the Chromium-based OpenCLI tool.

Input Validation and Normalization

Before any installation occurs, the command normalizes user input and rejects invalid channels:

raw_channels = [
    channel.strip().lower()
    for channel in args.channels.split(",")
    if channel.strip()
]
unknown_channels = set(raw_channels) - supported_channels - {"all"}
if unknown_channels:
    # print error and exit

(source: agent_reach/cli.py L34-L44)

This ensures typos or unsupported platforms surface immediately with clear error messages.

The all Shortcut Expansion

Users can request every supported dependency with a single keyword:

if "all" in raw_channels:
    requested_channels = supported_channels
else:
    requested_channels = set(raw_channels)

(source: agent_reach/cli.py L49-L53)

The supported_channels set is derived from CHANNEL_INSTALLERS keys plus the no-installer channels (xueqiu, linkedin).

Environment-Aware Filtering for Server Deployments

A critical feature distinguishes desktop from server environments. Channels requiring real Chrome sessions—facebook, instagram, and opencli—are automatically excluded when Agent Reach detects a server environment:

if env == "server" and requested_channels:
    server_skipped_opencli_channels = requested_channels & OPENCLI_ONLY_CHANNELS
    requested_channels -= server_skipped_opencli_channels

(source: agent_reach/cli.py L84-L89)

This prevents installation failures on headless systems without display capabilities.

Installer Execution with Deduplication

When installation proceeds (not in dry-run or safe mode), the command invokes each installer exactly once using a tracking set:

if requested_channels and not dry_run and not safe_mode:
    ran_installers = set()
    for ch_name in sorted(requested_channels):
        installer = CHANNEL_INSTALLERS.get(ch_name)
        if installer and installer not in ran_installers:
            installer()
            ran_installers.add(installer)

(source: agent_reach/cli.py L24-L33)

This deduplication matters because facebook, instagram, and reddit all map to _install_opencli_deps, but the function should execute only once per invocation.

Dry-Run and Safe Mode for Deployment Planning

The install command supports two non-destructive modes for infrastructure and CI/CD workflows:

Mode	Flag	Behavior
Dry run	--dry-run	Prints channels that would be installed without executing installers
Safe mode	--safe	Skips all system modifications, only logs intended actions

if requested_channels and dry_run:
    print(f"[dry-run] Would install optional channels: {', '.join(sorted(requested_channels))}")

(source: agent_reach/cli.py L34-L37)

Usage Examples

# Install Twitter and Bilibili dependencies only

agent-reach install --channels=twitter,bilibili

# Install everything (auto-filters desktop-only channels on servers)

agent-reach install --channels=all

# Preview what would install without making changes

agent-reach install --channels=reddit,facebook --dry-run

# Safe mode for restricted environments

agent-reach install --channels=instagram --safe

Implementation Files Reference

File	Responsibility
agent_reach/cli.py	Argument parsing, channel flag handling, environment detection, installer dispatch
agent_reach/channels/*.py	Platform-specific implementations; installers fetch tools these modules depend on
agent_reach/config.py	Persistent configuration (proxy, cookies) written during installation

Summary

• --channels accepts comma-separated platform identifiers or all
• Validation rejects unknown channels with clear error messages
• Environment detection automatically excludes OpenCLI-dependent channels (facebook, instagram, reddit) on server deployments
• Installer deduplication prevents redundant executions when multiple channels share dependencies
• Dry-run and safe modes enable deployment planning without system changes

Frequently Asked Questions

How do I install dependencies for all platforms at once?

Pass all as the --channels value: agent-reach install --channels=all. The command expands this to every supported channel, then applies environment-specific filters automatically.

Why do Facebook and Instagram installations fail on my server?

These platforms require OpenCLI, which needs a real Chrome browser session. The install command detects server environments and skips OPENCLI_ONLY_CHANNELS to prevent failures on headless systems.

Can I see what would install without actually running installers?

Yes. Use the --dry-run flag to print the resolved channel list without invoking any installer functions. Combine with --channels=all to audit your full dependency surface.

What happens if I request a channel with no installer?

Channels like xueqiu and linkedin pass through validation successfully but invoke no installer function. They remain available in the resolved channel set for application-level use without external dependencies.

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