# Agent Reach Installation: The Difference Between `--safe` and `--dry-run` Modes > Confused about Agent Reach installation? Learn the difference between --safe and --dry-run modes. Safely validate or simulate installation without system changes. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-07-09 --- **During Agent Reach installation, the `--safe` flag executes only non-destructive validation checks while skipping system modifications, whereas `--dry-run` simulates the complete installation process without writing files or installing packages.** When running an Agent Reach installation from the Panniantong/Agent-Reach repository, the `agent-reach install` command provides two distinct preview modes that help you verify system compatibility before committing to changes. Understanding how these flags interact with the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) ensures you can validate dependencies and audit configuration steps without risking your existing Python environment. ## What `--safe` Does During Agent Reach Installation The `--safe` flag restricts the installer to **read-only operations** that are guaranteed not to alter your system. When activated, the installer skips any action that could modify existing system files, replace user data, or change the Python environment in a way that might break other projects. This mode executes validation logic found in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to confirm that required external tools—such as browsers and API clients—are present and accessible. However, it explicitly bypasses the configuration generation and persistence logic handled in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). Use this flag when you need to quickly verify that the installer can locate all dependencies without triggering the full setup process: ```bash python -m agent_reach.cli install --safe ``` ## What `--dry-run` Does During Agent Reach Installation The `--dry-run` flag performs a **complete simulation** of the installation workflow. Unlike `--safe`, which skips potentially destructive steps, `--dry-run` walks through every single step—including dependency checks, configuration generation, and optional integrations—but prints what *would* happen without writing files, installing packages, or changing environment variables. This mode consults the same logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to display exactly which configuration files would be created and what values they would contain. It is the ideal choice for debugging the installer script or generating reproducible documentation of planned changes: ```bash python -m agent_reach.cli install --dry-run ``` ## Key Implementation Details in the Source Code The behavior of these flags is implemented through conditional checks scattered across the codebase: - **In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: The argument parser defines both flags and forwards their values to the core installer routine. The CLI ensures these flags are mutually exclusive; you cannot combine them on the same command line. - **In [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: The diagnostic engine validates system prerequisites. When `args.safe` is True, it restricts validation to external tool detection without invoking package managers. - **In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Configuration generation is guarded by `if args.dry_run:` checks. When active, the code prints the intended file paths and content to stdout instead of calling filesystem write operations. - **In [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)**: The test suite confirms correct handling of these flags, ensuring they properly gate destructive operations during the Agent Reach installation process. ## When to Use Each Flag Choose your flag based on the level of verification you need: - **`--safe`**: Use when running on a machine with a stable Python environment where you only need to confirm that the installer can find all required dependencies. This is the faster option for a quick health check. - **`--dry-run`**: Use when auditing what the installer would change before actually running it, or when creating troubleshooting reports that require a complete log of every action the installer plans to perform. If neither flag is supplied, the installer runs in default mode, performing a full Agent Reach installation including package installation, configuration file creation, and environment setup. ## Summary - **`--safe`** runs only non-destructive checks in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) without modifying files or installing packages. - **`--dry-run`** simulates the entire workflow in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), showing what would be written without changing the system. - 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 default behavior (no flags) performs a complete installation with full system modifications. ## Frequently Asked Questions ### Can I use `--safe` and `--dry-run` together during Agent Reach installation? No, these flags are mutually exclusive. The argument parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) prevents you from combining them on the same command line, as they serve different purposes—one restricts scope while the other simulates the full process. ### What happens if I run `agent-reach install` without any flags? The installer executes a full installation according to the default logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). This includes installing Python packages, writing configuration files to disk, and modifying environment variables to complete the Agent Reach installation. ### Which flag should I use to check if my system meets requirements without changing anything? Use `--safe` when you only need to verify that external dependencies like browsers and API clients are present. This mode validates prerequisites without touching your Python environment or configuration files. ### Does `--dry-run` verify that file permissions are correct? Yes, the `--dry-run` mode walks through the complete installation logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which includes checking file paths and permissions that would be required for the actual installation, reporting any issues it encounters during the simulation.