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

> Learn how the agent reach install command uses the --channels flag to selectively install platform backends map channel names to installer functions in agent_reach/cli.py automatically handling environment constraints.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `--channels` argument is added to the install subparser with a comma-separated list of supported platforms:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```bash
agent-reach install --channels=twitter,reddit

```

Install every supported channel:

```bash
agent-reach install --channels=all

```

Preview installation without making changes:

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

```

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

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

```

## Summary

- The `--channels` flag in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.