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

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 and 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, 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 defines both options and forwards their values to the core installer routine. Throughout agent_reach/doctor.py and 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 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:

python -m agent_reach.cli install --safe

Simulate the complete installation to see what would change:

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

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

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, and implemented via conditional guards in agent_reach/doctor.py and 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 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 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.

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