# How to Use Dry-Run Mode to Preview Installation Changes in Agent Reach

> Preview Agent Reach installation changes with dry-run mode. Safely simulate the installation pipeline without altering your system or files.

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

---

**Run `agent-reach install --dry-run` to simulate the full installation pipeline without modifying your system, filesystem, or configuration files.**

Agent Reach provides a **dry-run mode** for its deterministic, one-shot installer. This feature lets you preview every step of the installation process—system dependency checks, tool directory creation, optional channel installations, and configuration changes—before committing to any changes. The dry-run implementation lives entirely in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and guarantees zero side effects on the host machine.

## How to Enable Dry-Run Mode

The `--dry-run` flag is available on the `install` sub-command:

```bash

# Preview a default installation with auto-detected environment

agent-reach install --dry-run

# Preview installation with specific optional channels

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

# Combine dry-run with an explicit environment target

agent-reach install --env=server --dry-run

```

When detected, the installer prints a clear header and prefixes every simulated action with `[dry-run]` for transparency.

## How Dry-Run Mode Works in the Source Code

The dry-run flow is orchestrated through four key stages in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

### 1. CLI Argument Definition

The flag is registered on the install sub-parser at lines 73–74:

```python

# agent_reach/cli.py L73-L74

install_parser.add_argument("--dry-run", action="store_true",
                            help="Show what would be installed without making changes")

```

### 2. Flag Extraction in the Install Command

Early in `_cmd_install`, the flag value is captured (lines 16–18):

```python

# agent_reach/cli.py L16-L18

def _cmd_install(args):
    dry_run = args.dry_run
    # ... further processing

```

### 3. Read-Only Configuration

When `dry_run` is enabled, the `Config` object is initialized with `read_only=True` (lines 54–55). This prevents any persistent configuration writes:

```python

# agent_reach/cli.py L54-L55

config = Config(read_only=(dry_run or safe_mode))

```

### 4. Conditional Execution of Mutable Actions

Throughout `_cmd_install`, `if dry_run:` guards prevent actual system modifications:

| Action | Dry-Run Behavior | Source Lines |
|--------|-----------------|--------------|
| Tools directory creation (`~/.agent-reach/tools`) | Skipped entirely | L59–L62 |
| System dependencies | Routed to `_install_system_deps_dryrun()` | L300–L303 |
| Optional channel installations | Listed as "would install" messages | L334–L337 |
| Cookie import automation | Prints notice that no automatic import occurs | L60–L63 |

The system dependency check demonstrates this pattern clearly. In dry-run mode, the installer inspects the environment and reports what *would* happen rather than executing installers:

```

[dry-run] System dependency check:
  ✅ gh CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

```

## Understanding Dry-Run Output

A typical dry-run session produces structured, scannable output:

```

DRY RUN — showing what would be done (no changes)

Agent Reach Installer
========================================
Environment: Local computer (auto-detected)

[dry-run] System dependency check:
  ✅ gh CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

[dry-run] Would install mcporter and configure Exa search

[dry-run] Would install optional channels: reddit, twitter

[dry-run] Cookie import remains explicit; install will not read a browser

```

Each `[dry-run]` line corresponds to a code branch in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) where the actual implementation is bypassed in favor of a print statement.

## When to Use Dry-Run Mode

Use `--dry-run` in these scenarios:

- **Pre-installation planning** — Verify system compatibility and review dependency requirements before running the real installer
- **CI/CD pipelines** — Validate installation scripts in test environments without side effects
- **Documentation and training** — Demonstrate Agent Reach installation behavior without modifying demo machines
- **Debugging custom configurations** — Preview how `--channels`, `--env`, or other flags alter the installation plan

## Key Files for Dry-Run Implementation

| File | Purpose |
|------|---------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Core implementation: argument parsing, flag handling, and all conditional dry-run logic |
| [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) | User documentation explaining dry-run purpose and usage |
| [`README.md`](https://github.com/Panniantong/Agent-Reach/blob/main/README.md) | Quick reference with dry-run command example |

## Summary

- **Dry-run mode** is invoked with `agent-reach install --dry-run` and produces zero system changes
- The implementation centers on [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where `dry_run` boolean flags guard all mutable operations
- **Read-only configuration** (`Config(read_only=True)`) ensures no persistent settings are written
- All simulated actions are prefixed with `[dry-run]` and collected under a clear header for readability
- System dependencies, optional channels, directory creation, and cookie handling each have dedicated dry-run branches

## Frequently Asked Questions

### What exactly does dry-run mode prevent from happening?

Dry-run mode prevents: creation of the `~/.agent-reach/tools` directory, execution of system package installers, actual installation of optional channels, automatic browser cookie imports, and any writes to configuration files. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), every mutable action is wrapped in `if not dry_run:` logic.

### Can I combine dry-run with other install flags?

Yes. The `--dry-run` flag composes with all other `install` options including `--channels`, `--env`, and `--safe-mode`. The `args.dry_run` value is extracted independently in `_cmd_install` and applied uniformly across all conditional branches.

### Is dry-run mode safe to run on production systems?

Absolutely. The design explicitly guarantees no filesystem modifications. The `Config` object is forced into read-only state, and all installer subroutines either skip execution or route to dry-run variants that only print messages.

### Where can I find more documentation about the install command?

The [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) file contains user-facing documentation for dry-run usage. The [`README.md`](https://github.com/Panniantong/Agent-Reach/blob/main/README.md) includes a quick reference table. For implementation details, examine the `_cmd_install` function and `_install_system_deps_dryrun` helper in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).