How the Agent-Reach Install Command Handles Optional Channel Dependencies with --channels

The install command parses the --channels flag as a comma-separated list, maps each channel name to a dedicated installer function in CHANNEL_INSTALLERS, and executes each installer exactly once while skipping OpenCLI-only channels on headless servers.

The Agent-Reach CLI provides a modular installation system that keeps core dependencies lightweight while allowing users to opt into specific platform integrations. When you run agent-reach install --channels, the _cmd_install function in agent_reach/cli.py orchestrates a targeted workflow that provisions only the requested optional channel back-ends.

Parsing and Normalizing the --channels Argument

Inside agent_reach/cli.py, the --channels option is defined at lines 75-78 as a comma-separated string (e.g., twitter,xiaohongshu).

The normalization logic at lines 13-18 splits the raw string, strips whitespace, and converts each entry to lowercase for case-insensitive matching. If the special value all appears, the CLI expands the set to include every key in the CHANNEL_INSTALLERS dictionary plus the cookie-only channels xueqiu and linkedin.

Mapping Channels to Installer Functions

The core orchestration relies on the CHANNEL_INSTALLERS dictionary constructed at lines 98-107. This static map associates each supported channel name with a dedicated installer function:

• _install_twitter_deps
• _install_xiaoyuzhou_deps
• _install_opencli_deps (for Reddit, Facebook, Instagram)

This design ensures that each platform's specific tool (such as twitter-cli or rdt-cli) is provisioned by isolated, reusable logic.

Environment-Specific Channel Filtering

Before execution, the CLI detects the runtime environment. At lines 30-35, server environments trigger the removal of OpenCLI-only channels (opencli, facebook, instagram) because these require a desktop Chrome session that is unavailable in headless environments.

Executing the Installation Workflow

The installation loop at lines 71-78 iterates over the sorted requested_channels set. For each channel, the CLI looks up the corresponding function in CHANNEL_INSTALLERS and executes it exactly once.

Each installer function (e.g., _install_twitter_deps at lines 102-122) follows a consistent pattern:

1. Check for existing tool presence using shutil.which
2. Attempt automatic installation via pipx or uv if the tool is missing
3. Fall back to manual instructions if automatic installation fails

Post-Install Cookie Import and Health Checks

After optional channels are installed, the CLI performs additional setup at lines 84-92. For channels requiring authentication (Twitter, Xueqiu, Bilibili), it auto-imports saved cookies from the configuration. Finally, it runs the doctor health check from agent_reach/doctor.py to verify that each channel is functional.

Practical Usage Examples

Install a Single Channel

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

agent-reach install --channels twitter,reddit

This installs both Twitter and Reddit dependencies. On local environments, it also installs OpenCLI (required by Reddit) via _install_opencli_deps.

Install All Optional Channels

agent-reach install --channels all

Expands to every entry in CHANNEL_INSTALLERS plus xueqiu and linkedin. OpenCLI-only channels are skipped on servers.

Dry-Run and Safe Mode

Preview changes without installing:

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

Print manual instructions without executing:

agent-reach install --safe --channels twitter

Summary

• The --channels flag accepts a comma-separated list that is normalized to lowercase at lines 13-18 of agent_reach/cli.py.
• A static CHANNEL_INSTALLERS map (lines 98-107) binds each channel name to a specific installer function.
• Server environments automatically exclude OpenCLI-only channels (opencli, facebook, instagram) at lines 30-35.
• Each installer executes once, attempting automatic installation via pipx or uv before falling back to manual instructions.
• Post-installation steps include cookie imports and health verification via agent_reach/doctor.py.

Frequently Asked Questions

What happens if I specify a channel that doesn't exist?

The CLI validates channel names against the CHANNEL_INSTALLERS keys. Invalid channels trigger an error before any installation begins, ensuring no partial or broken setups occur.

Can I install channels without automatic package managers?

Yes. Use the --safe flag to run in safe mode. This prints manual installation instructions for each missing tool without invoking pipx or uv, giving you full control over the installation process.

Why are some channels skipped on my server?

OpenCLI-based channels (Reddit, Facebook, Instagram) require a desktop Chrome browser. The CLI detects headless server environments at lines 30-35 and automatically excludes these channels to prevent installation failures.

How does the all keyword differ from listing channels individually?

The all keyword expands to every channel in CHANNEL_INSTALLERS plus the cookie-only channels (xueqiu, linkedin). It respects the same server-side exclusions (OpenCLI channels) and executes each installer exactly once, ensuring comprehensive coverage without duplication.

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