Agent Reach Install: Difference Between --safe Mode and --dry-run Explained

The --safe flag audits missing dependencies without making system changes, while --dry-run simulates the complete installation workflow and prints [dry-run] prefixes for every action it would execute.

Agent Reach provides two mutually exclusive verification modes for its installation command that help you preview changes before committing them. Understanding the difference between --safe mode and --dry-run in the Agent Reach install command prevents unintended system modifications during setup. Both options are defined in agent_reach/cli.py and trigger specific helper functions that determine exactly how system dependencies, optional channels, and cookie extraction are handled.

What --safe Mode Does in Agent Reach Install

The --safe flag activates a restricted audit mode that reports what would be required without executing installation commands. When you invoke agent-reach install --safe, the installer prints a "SAFE MODE" banner (lines 92-95 in agent_reach/cli.py) and invokes checking versions of system dependency helpers rather than their installation counterparts.

System Dependency Checking

In safe mode, the installer calls _install_system_deps_safe() (line 50) and _install_mcporter_safe() (line 58) instead of the standard installation functions. These safe variants verify the presence of required packages like ffmpeg and libmagic but explicitly skip any calls to apt, brew, or pip install commands. According to the source code at lines 45-53, the branching logic checks safe_mode before dry_run, ensuring that safe mode takes precedence when specified.

Disabled Operations

Safe mode explicitly disables optional channel installation and cookie import steps. At lines 69-71, the code verifies that both dry_run and safe_mode are false before executing optional channel installations. Similarly, cookie extraction from Chrome or Firefox is bypassed entirely in safe mode, as the installer treats this as an automatic system modification.

What --dry-run Mode Does in Agent Reach Install

The --dry-run flag performs a comprehensive simulation where every actionable step is replaced by a prefixed [dry-run] message. Unlike safe mode, dry-run provides a complete preview of the installation plan including optional channels and configuration steps that would normally modify your environment.

Full Simulation with Command Preview

When dry_run is true, the installer invokes _install_system_deps_dryrun() at line 47 and the corresponding mcporter dry-run helper at line 55. These functions emit console output showing exactly which commands would execute, such as package manager invocations or proxy configuration writes. The implementation at lines 177-179 shows both flags being read into local variables immediately after argument parsing: safe_mode = args.safe and dry_run = args.dry_run.

Optional Channel Handling

Dry-run mode provides visibility into optional channel installations that safe mode suppresses entirely. At lines 80-82, when dry_run is active, the installer prints a summary line indicating which channels would be installed (e.g., twitter, reddit, bilibili) rather than skipping the step. This distinction is critical because safe mode gives no indication of what optional components are available, while dry-run enumerates them explicitly.

Key Implementation Differences

The source code in agent_reach/cli.py implements these modes through distinct execution branches that determine which helper functions run and what output is displayed.

Argument Parsing and Variable Assignment

Both flags are added to the install sub-parser at lines 71 and 73, with --safe defined at line 71 and --dry-run at line 73. The argument parser ensures these options are available globally to the installation flow, and lines 177-179 extract these values for use in the conditional logic that follows.

Branching Logic in the Installer

The three-branch conditional structure at lines 45-61 governs system dependency installation:

• Dry-run path: Calls _install_system_deps_dryrun() (line 47)
• Safe mode path: Calls _install_system_deps_safe() (line 50)
• Default path: Calls _install_system_deps() (line 52)

The same pattern applies to mcporter installation at lines 55-61. For cookie extraction, lines 84-86 show that the actual import only occurs in local environments when neither flag is set, while lines 88-90 handle the dry-run placeholder message.

Practical Usage Examples

Use these commands to leverage the distinct behaviors of each mode:

# Safe mode - only reports missing packages, never installs

agent-reach install --safe

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

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

Running the dry-run command produces output similar to:

[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

In contrast, safe mode output looks like:

SAFE MODE — skipping automatic system changes

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

Summary

• --safe mode invokes _install_system_deps_safe() and _install_mcporter_safe() to audit dependencies without executing package managers, and completely skips optional channel and cookie import steps.
• --dry-run mode invokes _install_system_deps_dryrun() and prints [dry-run] prefixes for every potential action, including optional channel installations and cookie extraction attempts that safe mode suppresses.
• Both flags are parsed at lines 71 and 73 of agent_reach/cli.py and stored in variables at lines 177-179, but they trigger mutually exclusive code paths in the installation logic.
• Use --safe for quick dependency audits when you want to know what is missing without seeing installation commands, and use --dry-run when you need to preview the exact commands that would execute in a full installation.

Frequently Asked Questions

Can I use --safe and --dry-run together in Agent Reach install?

No, these flags are mutually exclusive in practice. While the argument parser in agent_reach/cli.py (lines 71-73) allows both to be set, the conditional logic at lines 45-53 checks dry_run before safe_mode, meaning dry-run takes precedence. If you specify both, you will see dry-run behavior with [dry-run] prefixes rather than safe mode output.

Does --safe mode check optional channels?

No, safe mode completely bypasses optional channel installation checks. According to lines 69-71 of agent_reach/cli.py, the optional channel installation block only executes when both dry_run and safe_mode are false. This means --safe provides no visibility into which channels would be installed, unlike --dry-run which enumerates them at lines 80-82.

Which mode should I use for CI/CD pipelines?

Use --dry-run for CI/CD validation because it provides a complete simulation of the installation workflow including command previews. The dry-run mode exercises the full code path through _install_system_deps_dryrun() and reports all potential changes, allowing you to verify that the installer logic works correctly without modifying the build environment. Safe mode skips too many steps (like optional channels) to serve as a comprehensive CI check.

What happens to cookie extraction in these modes?

Cookie extraction is disabled in both modes, but with different feedback. In safe mode, the step is silently skipped because the code at lines 84-86 requires both flags to be false. In dry-run mode, lines 88-90 print a placeholder message like [dry-run] Would try to import cookies from Chrome/Firefox, giving you visibility into what would happen during a real installation.

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