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

The Agent-Reach CLI implements --safe and --dry-run as mutually independent boolean flags in 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:

# 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:

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:

# 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:

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

Dry-Run Only

Preview exactly what would happen during installation:

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

Combined Preview

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

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 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, 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}