Agent Reach Installation: The Difference Between `--safe` and `--dry-run` Modes

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 and 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 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.

Use this flag when you need to quickly verify that the installer can locate all dependencies without triggering the full setup process:

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 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:

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: 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: 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: 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: 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 without modifying files or installing packages.
• --dry-run simulates the entire workflow in 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.
• 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 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 and 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, which includes checking file paths and permissions that would be required for the actual installation, reporting any issues it encounters during the simulation.

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