Difference Between --safe Mode and --dry-run During Agent Reach Installation

Safe mode prevents automatic installation of system-level packages while still installing Python components, whereas dry-run only previews actions without making any changes to the system.

When installing the Panniantong/Agent-Reach toolkit, understanding the difference between --safe mode and --dry-run flags helps you control exactly how the installer modifies your environment. These two options serve distinct purposes—one restricts system-level modifications while the other simulates the entire process. This guide explains the technical distinction between these installation flags based on the actual source code implementation.

Understanding Safe Mode (--safe)

Purpose and System Impact

Safe mode is designed for security-conscious environments where you want to prevent the installer from automatically installing any system-level packages such as brew, apt, or yum. According to docs/install.md, this flag ensures the installer only performs Python-side setup, leaving you to manually install any required external tools. When you run with --safe, the command completes after setting up the Agent Reach library itself without invoking sudo or touching system package managers.

When to Use Safe Mode

Use this mode when working on locked-down workstations, corporate machines with strict policies, or CI environments where automatic system modifications are prohibited. The installer will check dependencies but skip any automatic installation of operating system packages, making it ideal for situations where you need a security-conscious installation that respects host system boundaries.

Understanding Dry-Run (--dry-run)

Purpose and System Impact

Dry-run operates as a simulation layer. Rather than executing installation steps, the installer prints a preview of every action it would perform without actually changing the system or installing anything. As implemented in agent_reach/cli.py, this flag allows you to audit the complete list of upstream tools and configuration changes before committing to them. The command finishes immediately after displaying the planned actions.

When to Use Dry-Run

Employ dry-run when you need to verify what the installer plans to do before making permanent changes. This is particularly useful for auditing dependencies, reviewing which external channels (such as --channels=twitter,weibo) will be configured, or confirming that the installer won't attempt unauthorized system modifications.

Side-by-Side Comparison

Safe Mode (--safe)

• Behavior: Executes the Python installation but blocks automatic system package installations.
• System Impact: Only Agent Reach Python libraries are installed; the host OS remains unchanged.
• Best For: Locked-down workstations, CI pipelines, or environments where sudo access is restricted.

Dry-Run (--dry-run)

• Behavior: Simulates every step the installer would take without executing them.
• System Impact: Zero changes—reports actions and terminates immediately.
• Best For: Pre-installation verification, dependency auditing, and reviewing installation steps before execution.

Implementation in the Source Code

The flag definitions reside in agent_reach/cli.py, where the argument parser distinguishes between these two modes. The docs/install.md file provides user-facing documentation, noting that safe mode "won't auto-install system packages" while dry-run offers a "preview what would be done." After installation completes, you can use agent_reach/doctor.py to verify which components were actually configured on your system.

Command-Line Examples

# Safe mode: Install Python components only, skip system packages

agent-reach install --env=auto --safe

# Dry-run: Preview all planned actions without executing

agent-reach install --env=auto --dry-run

# Combining with other flags (works with both modes)

agent-reach install --env=auto --safe --channels=twitter,weibo

Summary

• Safe mode performs the actual Python installation but prevents automatic system-level package management, making it ideal for restricted environments.
• Dry-run executes no installation steps whatsoever, providing only a preview of actions for verification purposes.
• Both flags can be combined with other options like --channels to scope the installation while respecting the chosen safety level.
• Configuration details are defined in agent_reach/cli.py and documented in docs/install.md.

Frequently Asked Questions

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

Yes, you can combine these flags. When used together, the installer will simulate the safe mode installation, showing you exactly which Python packages would be installed while confirming that no system packages would be touched.

Does safe mode skip all installations or just system packages?

Safe mode only skips automatic installation of system-level tools like brew, apt, or yum. It still installs the Agent Reach Python library and its Python dependencies, as clarified in the docs/install.md documentation.

Where are these flags implemented in the codebase?

The argument definitions and initial flag processing are located in agent_reach/cli.py. The actual behavior enforcement—whether to skip system package installation or simulate the entire process—is handled within the installation logic that references these CLI arguments.

How can I verify what was actually installed after using safe mode?

After running the installer, use the agent_reach/doctor.py utility to verify which components are present on your system. This tool checks the actual state of your installation against the expected configuration, helping you identify which system packages you still need to install manually.

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