How Agent-Reach Optional Channel Installation Works with the `--channels` Flag

The agent-reach install command uses the --channels flag to selectively install platform-specific backends by mapping channel names to installer functions in agent_reach/cli.py, automatically handling environment constraints and deduplicating installations.

The Agent-Reach CLI provides fine-grained control over which social media and content platforms (channels) are supported through optional channel installation. By using the --channels flag during setup, users can specify exactly which platform backends to install, from Twitter and Reddit to Bilibili and Xiaohongshu. This mechanism, implemented in agent_reach/cli.py, handles environment detection, dependency mapping, and automatic cookie extraction for authentication.

CLI Flag Definition and Accepted Values

In agent_reach/cli.py, the --channels argument is added to the install subparser with a comma-separated list of supported platforms:

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

Channel-to-Installer Mapping

The optional channel installation system uses a CHANNEL_INSTALLERS dictionary to map each channel name to a specific installation helper 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,  # cross‑channel backend, desktop only

    # xueqiu: cookie‑only, no install step

    # linkedin: manual setup, no auto‑install

}

Two additional sets classify channels by their technical requirements:

• OPENCLI_ONLY_CHANNELS = {"opencli", "facebook", "instagram"} – These require a real desktop Chrome session and cannot run headlessly.
• COOKIE_CHANNELS = {"twitter", "xueqiu", "bilibili"} – These require browser cookies for authentication later in the install flow.

Input Parsing and Normalization

When processing the --channels flag, the input string is split, trimmed, and lowercased. The special token all triggers installation of every available channel:

requested_channels = set()
if args.channels:
    raw = [c.strip().lower() for c in args.channels.split(",") if c.strip()]
    if "all" in raw:
        requested_channels = set(CHANNEL_INSTALLERS.keys()) | {"xueqiu", "linkedin"}
    else:
        requested_channels = set(raw)

Environment-Aware Filtering

On server environments, the installer automatically excludes channels that depend on OpenCLI, as the desktop backend cannot run headlessly:

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

Executing Channel Installers

After system prerequisites are installed, the code iterates over the remaining requested_channels. A ran_installers set ensures each unique installer function executes only once, even if multiple channels share the same dependency installer:

if requested_channels and not dry_run and not safe_mode:
    print()
    print("Installing optional channels...")
    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)

Cookie Extraction for Authentication

For channels requiring browser-based authentication, the installer attempts to import cookies from Chrome or Firefox on local desktop environments:

needs_cookies = bool(requested_channels & COOKIE_CHANNELS)
if env == "local" and needs_cookies and not safe_mode and not dry_run:
    # invoke configure_from_browser(...)

This step is automatically skipped on servers or when using --safe or --dry-run flags.

Practical Usage Examples

Install only Twitter and Reddit:

agent-reach install --channels=twitter,reddit

Install every supported channel:

agent-reach install --channels=all

Preview installation without making changes:

agent-reach install --channels=twitter,bilibili --dry-run

Run in safe mode (instructions only, no system modifications):

agent-reach install --channels=facebook --safe

Summary

• The --channels flag in agent_reach/cli.py accepts comma-separated platform names or all to install specific social media backends.
• A CHANNEL_INSTALLERS dictionary maps each channel to its dependency installation function, with deduplication logic to prevent redundant installs.
• Environment detection automatically excludes OpenCLI-dependent channels (Facebook, Instagram) when running on servers without desktop Chrome.
• Cookie channels (Twitter, Xueqiu, Bilibili) trigger automatic browser cookie extraction on local desktop environments.
• The installation process respects --dry-run and --safe flags to preview or restrict system modifications.

Frequently Asked Questions

What happens if I specify --channels=all on a server?

The installer automatically filters out OpenCLI-dependent channels (Facebook, Instagram, and the OpenCLI backend) because they require a desktop Chrome session. Only headless-compatible channels and cookie-based channels remain in the installation set, as implemented in the environment-aware filtering logic of agent_reach/cli.py.

Why are some channels missing from the CHANNEL_INSTALLERS dictionary?

Channels like Xueqiu and LinkedIn are excluded because they require manual setup or authentication via cookies only, with no automatic dependency installation steps. These are added to the requested set when using all but skip the automated installer phase where CHANNEL_INSTALLERS is referenced.

How does the installer prevent duplicate installations?

The code maintains a ran_installers set that tracks which installer functions have already been executed. Since multiple channels (like Facebook and Instagram) share the same underlying _install_opencli_deps function, this ensures each dependency installer runs only once regardless of how many channels reference it.

Can I use the --channels flag with --dry-run or --safe?

Yes. When --dry-run is active, the installer prints the installation plan without executing channel installers. When --safe mode is enabled, the command outputs setup instructions rather than modifying system packages, though channel names are still parsed and validated against the supported list.

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