Agent Reach Install --safe vs --dry-run: What's the Difference?

The --safe flag skips destructive operations during Agent Reach installation, while --dry-run simulates the entire process without writing any files or installing packages.

When installing the Agent Reach framework from the Panniantong/Agent-Reach repository, you can control how the installer interacts with your system using two distinct safety flags. Understanding the difference between --safe and --dry-run ensures you can validate dependencies, audit changes, and protect existing environments before committing to a full installation.

What the --safe Flag Does in Agent Reach

The --safe flag configures the installer to execute only non-destructive steps. When this flag is present, the installer skips any action that could modify existing system files, replace user data, or alter the Python environment in ways that might break other projects.

This mode is implemented in agent_reach/doctor.py and agent_reach/config.py, where conditional checks like if args.safe: guard against filesystem operations. The installer will verify that required external tools (such as browsers and API clients) are present and accessible, but it will not write configuration files or install packages.

Use --safe when:

• Running on a machine with a stable Python environment you want to protect
• Quickly verifying that all required dependencies are available without altering your system

What the --dry-run Flag Does in Agent Reach

The --dry-run flag performs a complete simulation of the installation process. Unlike --safe, which skips destructive steps entirely, --dry-run walks through every single step—including dependency checks, configuration generation, and optional integrations—but never actually writes files, installs packages, or modifies environment variables.

This mode is ideal for debugging the installer script itself or generating a reproducible log of planned actions. When --dry-run is active, the code paths in agent_reach/config.py execute the logic to determine what would happen, then print the results without persisting changes.

Use --dry-run when:

• Auditing what the installer would change before actually running it
• Creating documentation or troubleshooting reports that require the exact sequence of planned actions

Key Differences Between --safe and --dry-run

While both flags protect your system from unwanted changes, they serve different purposes:

Scope of execution

• --safe runs a subset of the installation (only validation steps)
• --dry-run runs the complete installation logic but suppresses all write operations

Output behavior

• --safe stops when it encounters a destructive operation
• --dry-run continues through all steps, logging what would have happened

Mutual exclusivity

• These flags are mutually exclusive; you cannot combine them on the same command line

Implementation Details in the Source Code

The flag handling is implemented across several key files in the repository:

agent_reach/cli.py contains the argument parsing logic that defines both --safe and --dry-run options and forwards their values to the core installer routine.

agent_reach/doctor.py houses the diagnostic engine that validates system prerequisites. This file checks the flag states to determine whether to execute validation-only logic or proceed with modifications.

agent_reach/config.py handles configuration generation and persistence. Guards throughout this file check if args.safe: or if args.dry_run: before writing to the filesystem or invoking external package managers.

Usage Examples

Run the installer in safe mode to check dependencies without risk:

python -m agent_reach.cli install --safe

Perform a complete simulation to see exactly what would change:

python -m agent_reach.cli install --dry-run

Execute the full installation with default behavior (writes files and installs packages):

python -m agent_reach.cli install

Summary

• --safe limits the installer to read-only validation steps, skipping any destructive operations
• --dry-run executes the complete installation logic but prints actions instead of performing them
• Both flags are mutually exclusive and parsed in agent_reach/cli.py
• The installer logic consults these flags in agent_reach/doctor.py and agent_reach/config.py to guard filesystem operations

Frequently Asked Questions

Can I use --safe and --dry-run together during Agent Reach installation?

No, these flags are mutually exclusive. According to the Panniantong/Agent-Reach source code in agent_reach/cli.py, the argument parser prevents combining both flags on the same command line. Choose --safe when you want to verify dependencies quickly, or --dry-run when you need to see the complete installation plan.

Which flag should I use to test if Agent Reach will work on my system?

Use --safe first to verify that all required external tools and dependencies are present without risking changes to your Python environment. If the safe check passes and you want to see the full installation plan before committing, run again with --dry-run to review every file that would be written and every package that would be installed.

Does --dry-run actually download packages during Agent Reach installation?

No, --dry-run never invokes external package managers or writes files. While it walks through the complete installation logic in agent_reach/config.py and reports what would happen, the mode explicitly prevents any network requests or filesystem modifications, making it safe to run in restricted environments.

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