# Difference Between --safe and --dry-run Installation Modes in Agent Reach

> Understand the difference between Agent Reach --safe and --dry-run installation modes. --safe audits without changes, --dry-run simulates and shows commands.

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

---

**The `--safe` flag performs a read-only audit of system requirements without modifying your environment, while `--dry-run` simulates the complete installation workflow and outputs every command it would execute prefixed with `[dry-run]`.**

Agent Reach's command-line installer supports two distinct simulation options that help you validate setup requirements before committing changes to your system. Understanding the difference between `--safe` and `--dry-run` installation modes prevents accidental modifications when auditing dependencies or testing configuration changes. This guide examines the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to explain exactly how each mode behaves.

## What --safe Mode Does

The `--safe` flag activates a **read-only audit** that only reports what actions would be required without executing them.

When you invoke `agent-reach install --safe`, the installer:

- Prints a prominent "SAFE MODE" banner immediately after argument parsing (lines 92–95)
- Invokes `_install_system_deps_safe()` instead of the standard system dependency installer (line 50)
- Calls `_install_mcporter_safe()` for the mcporter component (line 57)
- **Skips** automatic system modifications such as `apt`, `brew`, or `pip install` commands
- **Disables** optional channel installation and cookie import steps entirely

Use this mode when you need a quick inventory of missing packages or configuration steps but cannot risk any changes to the host system.

## What --dry-run Mode Does

The `--dry-run` flag performs a **full simulation** that mimics every step of the installation without making actual changes.

When running `agent-reach install --dry-run`, the behavior differs in several key ways:

- Every actionable step is replaced by a `[dry-run]` prefixed message
- No filesystem, network, or package modifications occur
- The installer still executes checking versions of helpers (`_install_system_deps_dryrun()` at line 47 and the corresponding mcporter variant)
- **Optional channels** that would be installed are printed as summary lines instead of executed (lines 80–82)
- **Cookie extraction** from Chrome/Firefox shows a placeholder message rather than accessing browser data (lines 88–90)

Use this mode when you need a complete preview of the installer's behavior, including which optional channels and cookie imports would be processed, without affecting the environment.

## Implementation Details in agent_reach/cli.py

The distinction between these modes is enforced through a three-branch conditional logic starting at line 45 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### Argument Parsing and Variable Assignment

Both flags are added to the `install` sub-parser at lines 71 and 73, then read into local variables at lines 177–179:

```python
safe_mode = args.safe
dry_run = args.dry_run

```

### System Dependency Handling

The installer selects which helper function to call based on flag priority:

- `dry_run` is True → Executes `_install_system_deps_dryrun()` (line 47)
- `safe_mode` is True → Executes `_install_system_deps_safe()` (line 50)  
- Neither flag → Executes the standard `_install_system_deps()` (line 52)

The same branching logic applies to mcporter installation at lines 55–61.

### Optional Steps Control

Optional channel installation only proceeds when **both** `dry_run` and `safe_mode` are false (lines 69–71). If `dry_run` is active, the installer prints what channels would be installed instead.

Cookie extraction is similarly gated: it only runs for local environments when cookies are needed and neither flag is set (lines 84–86). Under `--dry-run`, a placeholder message indicates where cookies would be imported from (lines 88–90).

## Practical Examples

Use these commands to see the behavioral differences:

```bash

# Safe mode - only reports missing system packages, does not install

agent-reach install --safe

# Dry-run mode - shows complete plan including optional channels

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

```

Sample output for `--safe`:

```

SAFE MODE — skipping automatic system changes

System dependency check:
  [safe] Would install ffmpeg, libmagic, etc.

```

Sample output for `--dry-run`:

```

[dry-run] Would install optional channels: twitter, reddit, bilibili
[dry-run] Would try to import cookies from Chrome/Firefox
[dry-run] Would execute: apt-get install ffmpeg libmagic1

```

## Summary

- **`--safe`** runs checking versions of helpers and reports missing dependencies without touching the system, skipping optional features entirely.
- **`--dry-run`** simulates the full installation flow, prints every command it would execute with `[dry-run]` prefixes, and previews optional channel and cookie handling.
- Both modes are mutually exclusive in practice because they trigger different code paths in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 45–61).
- Use `--safe` for quick audits and `--dry-run` for complete installation previews before running the actual installer.

## Frequently Asked Questions

### Can I use --safe and --dry-run together?

No, while the argument parser allows both flags to be passed, the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) gives precedence to `dry_run` in the conditional checks (lines 45–53). If both are present, the `--dry-run` behavior takes precedence, though using them together is not recommended as they serve different purposes.

### Which mode should I use for CI/CD pipelines?

Use **`--dry-run`** for CI/CD validation because it verifies the complete installation logic including optional channels and configuration steps. `--safe` only checks system dependencies and skips the optional channel logic entirely (lines 69–71), which may miss configuration errors in your deployment pipeline.

### Does --dry-run verify system dependencies or just skip them?

`--dry-run` does not skip dependency verification—it runs `_install_system_deps_dryrun()` (line 47), which performs checks similar to `--safe` but formats output with `[dry-run]` prefixes. The key difference is that `--dry-run` continues to simulate subsequent installation steps (channels, cookies) that `--safe` omits entirely.

### Will --safe mode check optional channels?

No, optional channel installation is completely bypassed when `--safe` is active. Lines 69–71 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) explicitly require both `dry_run` and `safe_mode` to be false before executing channel installation logic. Only `--dry-run` provides visibility into which channels would be installed while preventing actual changes.