# How Agent-Reach CLI Implements Safe Mode vs Dry-Run Installation Modes

> Understand Agent-Reach CLI safe mode versus dry-run installation. Learn how flags prevent system modifications and display preview messages for secure installations.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-16

---

**The Agent-Reach CLI implements `--safe` and `--dry-run` as mutually independent boolean flags in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where safe mode runs prerequisite checks via dedicated helper functions like `_install_system_deps_safe()` without system modifications, while dry-run mode prints preview messages such as "[dry-run] Would install..." without executing any mutating operations.**

The Agent-Reach command-line interface provides distinct safety mechanisms for installation workflows through two specialized flags defined in the Panniantong/Agent-Reach repository. Understanding how these modes interact helps operators validate deployment procedures without risking unintended system changes. This article examines the exact implementation of safe mode and dry-run installation modes at the source code level.

## Understanding Safe Mode and Dry-Run Flags

### Safe Mode (--safe)

Safe mode performs all prerequisite validations and dependency checks but explicitly prevents any modifications to the system. When activated, the CLI skips package installations, file writes, and network calls entirely.

### Dry-Run Mode (--dry-run)

Dry-run mode generates a complete preview of every action the installer would execute, including the validation checks performed in safe mode. Unlike safe mode, dry-run focuses on outputting intent messages rather than performing actual validation logic or system modifications.

## Implementation Details in agent_reach/cli.py

### Argument Parsing and Storage

The flags are registered in the argument parser at lines 71 and 73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```python

# Line 71

p_install.add_argument("--safe", action="store_true", ...)

# Line 73  

p_install.add_argument("--dry-run", action="store_true", ...)

```

The parsed values are extracted at line 177:

```python
safe_mode = args.safe

```

### Safe Mode Execution Flow

Throughout the installation flow, mutating operations are guarded by `if not safe_mode:` conditions. For example, optional channel installation at line 269 and cookie imports at line 285 are both skipped when safe mode is active:

```python

# Line 269

if requested_channels and not dry_run and not safe_mode:
    # installation logic

# Line 285  

if env == "local" and needs_cookies and not safe_mode and not dry_run:
    # cookie import logic

```

The implementation routes to specialized safe variants of helper functions. At line 865, `_install_system_deps_safe()` prints diagnostic warnings like "Checking system dependencies (safe mode — no auto-install)" and returns without invoking package managers. Similarly, `_install_mcporter_safe()` at line 962 handles the mcporter component without side effects.

### Dry-Run Preview System

The dry-run flag triggers early conditional branches that print formatted preview messages. The code wraps all destructive calls in `if not dry_run:` checks, ensuring the execution path never reaches actual installation logic.

Examples from the source include:
- Line 281: `[dry-run] Would install optional channels ...`
- Line 239: `[dry-run] Would save network proxy`

These messages appear before the corresponding `if not dry_run:` guards that prevent the actual operations.

### Combining Both Flags

When used together (`--safe --dry-run`), the CLI executes both diagnostic paths independently. The safe-mode checks run first, followed by dry-run preview messages, with both guard types preventing any system modifications. The flags are checked separately, allowing each to independently suppress its corresponding actions.

## Practical Usage Examples

### Safe Mode Only

Run dependency checks without any system modifications:

```bash
agent-reach install --env=auto --safe

```

### Dry-Run Only

Preview exactly what would happen during installation:

```bash
agent-reach install --env=auto --dry-run

```

### Combined Preview

Execute both safe-mode validations and dry-run previews simultaneously:

```bash
agent-reach install --env=auto --safe --dry-run

```

## Summary

- **Safe mode** (`--safe`) uses dedicated helper functions like `_install_system_deps_safe()` (line 865) and `_install_mcporter_safe()` (line 962) to perform checks without side effects
- **Dry-run mode** (`--dry-run`) prints "[dry-run] Would..." preview messages and guards all mutating calls with `if not dry_run:` conditions
- Both flags are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 71 and 73 using `action="store_true"`
- The flags operate independently and can be combined for comprehensive pre-installation validation
- Actual installation logic is guarded by compound conditions checking both flags: `if not safe_mode and not dry_run:`

## Frequently Asked Questions

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

Yes. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), these flags are mutually independent. When combined, the CLI prints safe-mode diagnostic checks and dry-run preview messages, but never performs system modifications because both guard conditions evaluate to false.

### What is the difference between safe mode and dry-run?

Safe mode executes validation logic through specialized functions like `_install_system_deps_safe()` but skips actual installations, while dry-run mode prints exactly what would happen without executing the underlying validation or installation logic. Safe mode focuses on checking prerequisites; dry-run focuses on showing intent.

### Where are the --safe and --dry-run arguments defined?

The argument definitions are located at lines 71 and 73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), using `p_install.add_argument()` with `action="store_true"` for both flags. The parsed values are stored in variables like `safe_mode = args.safe` at line 177.

### Does safe mode make network calls?

No. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode explicitly avoids network calls, package installations, and file writes. The `_install_system_deps_safe()` function returns after printing diagnostic messages without triggering package managers or external requests.