# Agent-Reach Install --safe vs --dry-run: Key Differences Explained

> Understand the key differences between agent-reach install --safe and --dry-run flags. Learn how each option performs installation checks and simulates processes without system modification.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-17

---

**The `--safe` flag runs only non-destructive validation checks while skipping file modifications, whereas `--dry-run` simulates the entire installation process without making any changes to your system.**

The `agent-reach install` command in the Panniantong/Agent-Reach repository provides two distinct safety mechanisms for environment setup. Understanding the **agent-reach install --safe and --dry-run difference** is crucial for managing risk when configuring the Agent-Reach environment on production systems or CI/CD pipelines. Both flags alter how the installer interacts with your filesystem and Python environment, but they serve fundamentally different purposes.

## What the --safe Flag Does

The `--safe` flag restricts the installer to steps that are guaranteed to be non-destructive. According to the source code 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), when this flag is active, 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 performs dependency checks and validates that required external tools—such as browsers and API clients—are present without actually installing packages or writing configuration files.

**When to use `--safe`:**
- Running on machines with stable Python environments where you want to verify prerequisites
- Quick validation that the installer can locate all required external tools without system alteration

## What the --dry-run Flag Does

The `--dry-run` flag performs a complete simulation of the installation process. As implemented in the codebase, this mode walks through every step including dependency checks, configuration generation, and optional integrations, printing what *would* happen without writing files, installing packages, or changing environment variables.

This creates a reproducible audit trail of planned actions, making it ideal for debugging the installer script itself or generating documentation.

**When to use `--dry-run`:**
- Auditing what the installer would change before actually executing it
- Creating troubleshooting reports that show the exact actions the installer plans to perform

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

**Scope of Execution**
- **`--safe`**: Partial execution limited to non-destructive validation checks
- **`--dry-run`**: Full execution simulation showing all steps including file writes and package installations

**System Impact**
- **`--safe`**: Performs read-only checks but skips modifications that would touch the filesystem or Python environment
- **`--dry-run`**: Reports all intended modifications—including configuration file creation and package installation—without applying them

**Mutual Exclusivity**
The flags cannot be combined. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the argument parser enforces that you cannot use both flags simultaneously, as they represent incompatible execution modes.

## Implementation Details in the Source Code

The CLI entry point in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** defines both options and forwards their values to the core installer routine. Throughout **[`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)**, conditional guards like `if args.safe:` and `if args.dry_run:` protect filesystem operations and external package manager invocations.

These checks ensure that:
- File write operations are bypassed when either flag is set
- Package installation commands are only executed in default mode
- Configuration generation logic runs but does not persist when `--dry-run` is active

The test suite in **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)** confirms the correct handling of these mutually exclusive flags and validates that the conditional guards properly prevent system modifications.

## Practical Usage Examples

Run only safe validation checks without modifying your system:

```bash
python -m agent_reach.cli install --safe

```

Simulate the complete installation to see what would change:

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

```

Execute the full installation with default behavior (includes package installation and configuration file creation):

```bash
python -m agent_reach.cli install

```

## Summary

- **`--safe`** executes only non-destructive validation checks, skipping file writes and package installations while verifying external dependencies exist.
- **`--dry-run`** simulates the complete installation workflow, showing every planned action including configuration files that would be created without making actual system changes.
- Both flags are mutually exclusive, parsed in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), and implemented via conditional guards 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).
- Use `--safe` for quick environment verification and `--dry-run` for comprehensive installation audits before deployment.

## Frequently Asked Questions

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

No. The 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 using both simultaneously, as they serve fundamentally different purposes—`--safe` limits execution scope while `--dry-run` simulates the full scope without side effects.

### Will --safe install any Python packages?

No. The `--safe` flag explicitly skips actions that would modify the Python environment, including package installation. It only validates that required dependencies and external tools are already present on the system, making it ideal for checking prerequisites without altering your environment.

### Does --dry-run create configuration files?

No. While `--dry-run` walks through the configuration generation logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and prints what files would be created, it never persists data to disk. It reports the intended file paths and contents without writing them, allowing you to preview the configuration structure before committing changes.

### Which flag should I use in a CI/CD pipeline?

Use `--dry-run` first to audit the complete installation steps and verify the planned configuration changes. Then use `--safe` to confirm the environment contains all required dependencies without risking dependency conflicts. Only run the default mode without flags in isolated build environments where you accept full system modifications.