# What Does the Agent Reach Install --dry-run Flag Do?

> Explore the Agent Reach install --dry-run flag to preview all installation steps, dependency additions, and cookie imports without making system changes.

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

---

**The `--dry-run` flag generates a complete preview of the installation process without executing any system changes, displaying exactly which dependencies would be installed, which channels would be added, and which cookies would be imported.**

The **Agent Reach** open-source project provides a CLI tool for automating social media channel installations. When you want to verify what changes an installation would make before committing them, the **`--dry-run`** flag offers a safe, read-only simulation. This feature mirrors the actual installation flow defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) while suppressing all mutating operations.

## How the --dry-run Flag Works in Agent Reach

The flag is implemented as a boolean toggle that redirects the installer from execution mode to preview mode.

### CLI Argument Definition

In **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** at lines 68-71, the argument is registered with the subparser:

```python
p_install.add_argument("--dry-run", action="store_true",
                        help="Show what would be done without making any changes")

```

### Execution Flow in _cmd_install()

When the `install` command is invoked, the **`_cmd_install()`** function captures the flag value at line 62:

```python
dry_run = args.dry_run

```

If enabled, the function immediately prints a banner at lines 73-76: "DRY RUN — showing what would be done (no changes)". The logic then branches to replace every mutating operation with a corresponding preview helper.

## What Actions Are Previewed vs. Skipped

The dry-run mode substitutes destructive calls with diagnostic outputs that mirror the real execution path.

### System Dependency Checks

Instead of installing **GitHub CLI** or **Node.js**, the code routes to **`_install_system_deps_dryrun()`** (lines 222-224). This helper enumerates system requirements and prints the intended installation method:

```python
print("[dry-run] System dependency check:")
...
print(f"  {label}: would install via: {method}")

```

### Optional Channel Installation

Lines 247-250 handle optional channels by printing a concise list of what *would* be installed rather than executing the installers. The output displays: `[dry-run] Would install optional channels: twitter, reddit, bilibili`.

### Cookie Import Simulation

Browser cookie extraction is replaced with a notification at lines 276-279, printing `[dry‑run] Would try to import cookies…` instead of accessing browser data.

## Practical Usage Examples

Run these commands to safely preview installations:

```bash

# Preview full installation without system changes

agent-reach install --dry-run

# Preview specific channels only

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

# Combine with safe mode for read-only validation

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

```

Typical output mirrors the real flow while explicitly marking each step:

```

Agent Reach Installer
========================================
DRY RUN — showing what would be done (no changes)

Environment: Local computer (auto-detected)

[dry-run] System dependency check:
  gh CLI: would install via: apt install gh / brew install gh
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

[dry-run] Would install optional channels: twitter, reddit, bilibili
...
Dry run complete. No changes were made.

```

## Summary

- The **`--dry-run`** flag in Agent Reach executes a **simulated installation** that prints every intended action without modifying the system.
- In **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**, the flag triggers preview helpers like **`_install_system_deps_dryrun()`** instead of actual package managers.
- The mode previews **system dependency** installations, **optional channel** configurations, and **browser cookie** imports.
- No external installers, Docker pulls, or file writes occur during execution, making it safe for auditing production environments.

## Frequently Asked Questions

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

Yes. The `--dry-run` flag functions correctly alongside options like `--channels` or `--safe`. When combined, the preview reflects exactly how those specific parameters would modify the installation scope without executing changes.

### Does --dry-run perform any network requests or file writes?

No. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the dry-run mode suppresses all mutating actions. It skips actual package installations, Docker operations, and cookie extractions, printing only what would occur during a live run.

### Where is the --dry-run behavior tested?

The functionality is covered in **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)**, which contains unit tests verifying that the flag correctly toggles the installer between preview mode and execution mode without causing side effects.

### Will --dry-run detect my environment correctly?

Yes. The dry-run execution preserves all environment detection logic, including proxy configuration and operating system identification. It only bypasses the final mutating calls, ensuring the preview accurately reflects what a real installation would detect and configure.