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

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

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:

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:

# 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 (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 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 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.

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