# Agent Reach Install --safe vs --dry-run: What's the Difference? > Understand the Agent Reach --safe vs --dry-run flags. Learn how --safe avoids destructive actions and --dry-run simulates installs for safer configuration. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-26 --- **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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) and [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash python -m agent_reach.cli install --safe ``` Perform a complete simulation to see exactly what would change: ```bash python -m agent_reach.cli install --dry-run ``` Execute the full installation with default behavior (writes files and installs packages): ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) - The installer logic consults these flags in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) and [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.