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

> Learn how the Agent Reach install command uses the --channels flag to manage optional channel dependencies by validating, filtering, and dispatching installers.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) source, valid values include `twitter`, `xiaoyuzhou`, `xueqiu`, `xiaohongshu`, `reddit`, `facebook`, `instagram`, `bilibili`, `linkedin`, or the special value `all`.

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```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,
    # xueqiu & linkedin have no installer step

}

```

*(source: [agent_reach/cli.py L21-L31](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```

*(source: [agent_reach/cli.py L49-L53](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/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 |

```python
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](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L34-L37))*

## Usage Examples

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.