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

> Explore Agent Reach install command --dry-run and --safe modes. Safely preview system changes and dependency installations without altering your system. Learn how to prevent installation issues today.

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

---

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

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

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

```bash
agent-reach doctor

```

This invokes the [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 96-106.