How to Run Agent-Reach in Safe Mode vs Dry-Run: A Complete Guide

Run agent-reach install --safe to audit system changes without installing dependencies, or use --dry-run to simulate the entire installation process without any side effects.

The Agent-Reach installer provides two distinct non-destructive execution paths for the agent-reach install command. These modes allow you to preview changes before committing them or audit dependencies when you lack system privileges. Understanding how to run agent-reach in safe mode vs dry-run ensures you can deploy the tool safely across different environments, from shared servers to CI pipelines.

Understanding Safe Mode vs Dry-Run

Both flags prevent unwanted system modifications, but they serve different purposes during the installation process.

What is Safe Mode?

Safe mode (--safe) skips automatic system-level changes while providing manual installation instructions. When enabled, the installer prints the current status of each dependency and outputs explicit commands for manual configuration rather than executing them automatically.

This mode is ideal when you want to audit what would be changed or when you lack privileges to modify the host system. Use it on shared servers, restricted CI pipelines, or when you prefer to review changes before they happen.

What is Dry-Run?

Dry-run (--dry-run) simulates the entire installation process without writing to disk, installing packages, or modifying the environment. It shows which steps would be taken, which optional channels would be added, and which cookies would be imported.

Use this mode when you want a quick "what-if" preview without any side effects, particularly for scripting or documentation purposes.

CLI Flag Definitions in agent_reach/cli.py

The command-line interface defines both options in agent_reach/cli.py using argparse (lines 71-74):

p_install.add_argument("--safe", action="store_true",
                       help="Safe mode: skip automatic system changes, show what's needed instead")
p_install.add_argument("--dry-run", action="store_true",
                       help="Show what would be done without making any changes")

These arguments are stored in args.safe and args.dry_run and are consulted throughout the installer logic. The flags are mutually independent—you can combine them (--safe --dry-run) to get a safe-mode preview that also avoids any side effects.

Safe Mode Implementation Details

When --safe is passed, the installer branches to dedicated helper functions that report status rather than mutate the system.

System Dependency Checks

At the start of installation, the flag triggers a status message (lines 92-95):

if safe_mode:
    print("SAFE MODE — skipping automatic system changes")

The system dependency handling then branches to _install_system_deps_safe() (lines 240-242):

elif safe_mode:
    _install_system_deps_safe()

This helper function (lines 443-470) walks through a static list of required tools and prints installation hints for missing dependencies:

def _install_system_deps_safe():
    """Safe mode: check what's installed, print instructions for what's missing."""
    for name, binaries, label, install_hint in deps:
        found = any(shutil.which(b) for b in binaries)
        if found:
            print(f"  ✅ {label} already installed")
        else:
            print(f"  -- {label} not found")
            missing.append((label, install_hint))

McPorter Configuration

An analogous safe path exists for the mcporter tool via _install_mcporter_safe() (lines 440-452). This function reports the tool's presence and prints a manual configuration command if needed, without automatically modifying system settings.

Dry-Run Implementation Details

The dry-run flag short-circuits each mutable step to prevent any system changes:

• System dependencies: _install_system_deps_dryrun() (lines 722-733) prints what would be checked or installed without invoking system commands.
• McPorter: _install_mcporter_dryrun() outputs a "would install" message.
• Optional channels: The installer skips actual channel installers when dry_run is true, printing a summary line instead (lines 267-270).
• Cookie import: When enabled, the code prints a placeholder message rather than reading the browser's cookie store (lines 296-298).

At completion (lines 389-391), the CLI outputs: "Dry run complete. No changes were made."

Practical Code Examples

Run Agent-Reach in safe mode to audit dependencies:

# Safe mode – only reports missing system dependencies

agent-reach install --safe

Expected output:

SAFE MODE — skipping automatic system changes

Checking system dependencies (safe mode — no auto-install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  -- To install: https://nodejs.org — or: apt install nodejs npm

Run a complete simulation with dry-run:

# Dry-run – full “what-will-happen” preview, no side-effects

agent-reach install --dry-run

Combine both flags for maximum safety:

# Combine both – safe-mode preview that never mutates the host

agent-reach install --safe --dry-run

Preview specific channel installations:

# Typical usage with optional channels (dry-run shows the channel list)

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

Summary

• Safe mode (--safe) audits system dependencies and prints manual installation instructions without automatically modifying the system, implemented in _install_system_deps_safe() in agent_reach/cli.py.
• Dry-run (--dry-run) simulates the entire installation process without writing to disk or executing system commands, using helpers like _install_system_deps_dryrun().
• Both flags can be combined to preview safe-mode instructions without any side effects.
• The flags are defined in agent_reach/cli.py lines 71-74 and stored in args.safe and args.dry_run for conditional logic throughout the installer.

Frequently Asked Questions

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

Yes. The flags are mutually independent and can be combined as agent-reach install --safe --dry-run. This combination provides a safe-mode preview that also avoids any side effects, showing you the manual installation instructions while ensuring zero system modifications.

What files handle the safe mode and dry-run logic in Agent-Reach?

The primary implementation resides in agent_reach/cli.py. Safe mode logic is handled by _install_system_deps_safe() and _install_mcporter_safe() around lines 443-470, while dry-run logic uses _install_system_deps_dryrun() and related helpers around lines 722-733.

When should I choose safe mode over dry-run?

Choose safe mode when you need to audit actual system dependencies and want specific manual installation instructions for your environment. Choose dry-run when you want a quick simulation of the entire process without detailed dependency checking, such as for scripting or documentation generation. Safe mode is preferred when you lack administrative privileges and need installation guidance.

Does dry-run check if dependencies are already installed?

Yes, but differently than safe mode. In agent_reach/cli.py, the _install_system_deps_dryrun() function prints what would be checked or installed, showing the installation method that would be used (e.g., "would install via: curl NodeSource setup | bash"), whereas safe mode actually checks for binaries and reports their real-time presence using shutil.which().

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