Agent Reach Install Command: Using --dry-run and --safe Modes

The agent-reach install --dry-run --safe command previews system modifications without executing them, showing which dependencies would be installed and warning about missing requirements while leaving the system untouched.

Agent Reach is a Python-based CLI tool that gives AI agents one-click access to 13 major internet platforms including YouTube, Reddit, and Twitter. Before executing changes on your system, the install command supports --dry-run and --safe flags that simulate the installation process defined in agent_reach/cli.py, allowing you to review the CHANNEL_INSTALLERS mapping and system dependencies without risk.

How --dry-run and --safe Work in Agent Reach

When you append --dry-run to the install command, the CLI enters simulation mode. It traverses the same logic paths as a real installation—including environment detection and dependency resolution—but stops before executing any system commands.

The --safe flag complements this by ensuring additional validation checks run without side effects. Together, these flags trigger the following流程 in agent_reach/cli.py:

• Environment detection (_detect_environment, lines 77-92): Determines whether the system is a local desktop or headless server
• System dependency audit (_install_system_deps, lines 32-38): Previews installation of gh CLI, Node.js, and yt-dlp runtime configurations
• Channel mapping review (CHANNEL_INSTALLERS in _cmd_install, lines 96-106): Lists platform-specific tools like twitter-cli, OpenCLI/rdt-cli for Reddit, and bili-cli for Bilibili
• Configuration preview: References docs/install.md to display what would be configured without writing to ~/.agent-reach/config.yaml

Running a Safe Preview Installation

Execute the following to see exactly what Agent Reach would install on your system:

agent-reach install --dry-run --safe

The output will categorize pending actions:

• System tools: Whether gh, Node.js, or yt-dlp need installation
• Optional channels: Which platform-specific backends are selected based on the --channels flag
• Environment-specific steps: On desktop systems, it shows whether browser cookie import would be attempted via configure_from_browser
• Post-install verification: Indicates that doctor.check_all would run to verify channel health

Because --safe is active, the process exits with status 0 if all dependencies are available, or exits with warnings listing missing prerequisites without modifying your environment.

Installation Logic Behind the Flags

The installation sequence in agent_reach/cli.py follows a strict pipeline that the dry-run mode shadows:

1. Detection Phase: _detect_environment (lines 77-92) inspects the runtime to distinguish between desktop environments (where browser cookies can be harvested) and headless servers (requiring manual token configuration).

2. System Dependencies: _install_system_deps (lines 32-38) manages external binaries. In dry-run mode, it checks for the presence of gh, Node.js, and yt-dlp without invoking package managers.

3. Channel Installation: The CHANNEL_INSTALLERS dictionary in _cmd_install (lines 96-106) maps platforms to their respective installers. For example:

   • Twitter → twitter-cli
   • Reddit → OpenCLI/rdt-cli
   • YouTube → yt-dlp configuration
   • Bilibili → bili-cli

4. Validation: Normally, the installer calls doctor.check_all to verify each channel's check method (defined in agent_reach/channels/base.py). In dry-run mode, this reports what would be checked rather than executing the health probes.

Full Installation vs Dry-Run Comparison

Mode	Command	System Changes	Cookie Import	Doctor Check
Preview	install --dry-run --safe	None	Simulated only	Reported only
Full Auto	install --env=auto	Installs all deps	Executed on desktop	Live execution
Selective	install --channels=reddit,youtube	Limited to selection	Configurable	Live execution

When satisfied with the preview, remove the flags to execute the actual installation:

agent-reach install --env=auto

Verification After Real Installation

Once you proceed with a real installation (without --dry-run), validate the setup using the doctor command:

agent-reach doctor

This invokes the doctor.py engine to iterate over agent_reach.channels.__all__, calling each channel's check method to confirm that platforms like Twitter, Reddit, and YouTube are accessible through their configured backends.

Summary

• Use agent-reach install --dry-run --safe to preview the CHANNEL_INSTALLERS logic in agent_reach/cli.py without system modification
• The command executes environment detection (_detect_environment) and dependency auditing (_install_system_deps) in simulation mode
• Dry-run references docs/install.md to display configuration changes that would apply to ~/.agent-reach/config.yaml
• Always follow actual installations with agent-reach doctor to verify channel health through the doctor.py engine

Frequently Asked Questions

What is the difference between --dry-run and --safe in Agent Reach?

The --dry-run flag simulates the installation pipeline, showing which system tools and channels would be installed without executing them. The --safe flag adds validation layers that ensure no temporary files or partial configurations are written during the preview. Together, they provide a complete read-only assessment of the installation logic defined in agent_reach/cli.py.

Will --dry-run check if my browser cookies are available for import?

Yes. When running on a desktop environment (detected by _detect_environment in lines 77-92 of agent_reach/cli.py), the dry-run mode reports whether configure_from_browser would attempt to read Chrome or Firefox cookies. It does not access your browser data but confirms the capability exists in your environment.

Does the dry-run mode test connectivity to all 13 platforms?

No. The dry-run mode validates that the installation prerequisites for each channel exist (such as twitter-cli or yt-dlp), but it does not invoke the check methods in agent_reach/doctor.py that test live connectivity. To verify actual platform access, run agent-reach doctor after completing the real installation.

Can I combine --dry-run with specific channel selection?

Yes. You can combine --dry-run --safe with the --channels flag to preview a subset of installations. For example, agent-reach install --channels=reddit,youtube --dry-run --safe shows only the actions related to the Reddit and YouTube channels, referencing the CHANNEL_INSTALLERS mapping in agent_reach/cli.py lines 96-106.

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