Agent Reach CLI Safe Mode vs Dry-Run vs Normal Installation: Functional Differences Explained

Safe mode skips automatic installation of system-level packages while completing Python-side setup, dry-run generates a preview of all planned actions without modifying the system, and normal installation executes the complete workflow including system dependencies.

The Agent Reach CLI provides three distinct operational modes when executing the install command, each designed for different deployment scenarios and security requirements. Understanding the functional differences between --safe, --dry-run, and normal installation modes ensures you select the appropriate strategy for your environment, whether you are deploying in a locked-down CI pipeline or auditing dependencies before execution.

What Is Normal Installation?

Normal installation represents the default behavior of the Agent Reach installer when invoked without modification flags. This mode attempts to automatically resolve and install all required dependencies, including system-level packages such as brew, apt, or yum utilities, alongside the Python library components.

When running agent-reach install --env=auto without additional flags, the CLI executes the full installation sequence defined in agent_reach/cli.py, automatically invoking package managers with appropriate permissions to ensure the environment is completely configured.

Understanding Safe Mode (--safe)

Safe mode restricts the installer to Python-only operations, explicitly preventing any automatic installation of system-level packages or invocation of host package managers.

When you append --safe to your installation command, the CLI performs the following actions:

• Installs the Agent Reach Python library and its Python dependencies
• Skips all system package manager calls (brew, apt, yum, etc.)
• Leaves external tool installation to the user

This mode is implemented in agent_reach/cli.py where the --safe flag intercepts system installation routines before they execute. According to the documentation in docs/install.md, this mode is specifically designed for security-conscious deployments where the installer must not touch system files or invoke sudo privileges.

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

Use this mode on locked-down workstations, restricted CI environments, or when your security policy prohibits automated system modifications.

Understanding Dry-Run Mode (--dry-run)

Dry-run mode operates as a simulation engine, processing the installation logic to generate a complete preview of every action the installer would perform without actually modifying the file system or installing any packages.

Key characteristics of dry-run mode include:

• Outputs a detailed list of all planned installation steps
• Makes zero changes to the host system
• Allows auditing of upstream tools and dependencies before execution

As documented in docs/install.md, dry-run serves as a verification mechanism to review the list of upstream tools that will be fetched and system changes that would occur. The implementation in agent_reach/cli.py executes the installation logic in a read-only context, logging intentions rather than performing mutations.

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

This mode is essential when you need to audit installer behavior, verify dependency lists, or document expected system changes before approving an installation in regulated environments.

Key Functional Differences

Normal Installation executes the complete workflow, automatically resolving system dependencies through package managers and installing Python components, making actual changes to your system configuration.

Safe Mode (--safe) performs the Python library installation but explicitly bypasses all system-level package manager invocations, requiring manual installation of external tools like brew or apt packages afterward.

Dry-Run Mode (--dry-run) performs no installation at all—neither Python nor system—instead outputting a comprehensive preview of what the installer would do if executed normally, useful for pre-installation auditing.

Implementation Details and Source Files

The behavior of these installation modes is defined across three critical files in the Panniantong/Agent-Reach repository:

• agent_reach/cli.py — Defines the CLI argument parsing for --safe and --dry-run flags and orchestrates the installer workflow based on the selected mode
• docs/install.md — Documents the user-facing descriptions and intended use cases for each mode, noting that safe mode "won't auto-install system packages" and dry-run provides a "preview what would be done"
• agent_reach/doctor.py — Provides post-installation verification capabilities to confirm which components were actually installed, useful for validating safe mode installations where manual steps may be incomplete

Practical Usage Examples

Combine these flags with environment specifications to control installation scope:

# Safe mode with specific channels - installs Python components only

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

# Dry-run to preview what would be installed for specific channels

agent-reach install --env=auto --dry-run --channels=twitter,weibo

# Normal installation - full automated setup

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

After installation, particularly when using --safe mode, verify your environment using the doctor utility:

agent-reach doctor

This command checks agent_reach/doctor.py to confirm which components from the preview are actually present and functional.

Summary

• Normal installation executes complete automated setup including system packages and Python libraries
• Safe mode (--safe) restricts operations to Python-side setup only, blocking system package managers for security-conscious environments
• Dry-run (--dry-run) simulates the entire installation process to generate previews without system modifications
• All three modes are implemented in agent_reach/cli.py and documented in docs/install.md
• Use agent_reach/doctor.py via the doctor command to verify installation completeness after using restricted modes

Frequently Asked Questions

What happens if I combine --safe and --dry-run flags in the same command?

When combining --safe and --dry-run, the dry-run behavior takes precedence, generating a preview that reflects the safe mode restrictions. The output will show which system package installations would be skipped due to the safe flag, allowing you to audit exactly what manual steps you would need to perform after a real safe-mode installation.

Can I use safe mode in production CI/CD pipelines?

Yes, safe mode is specifically designed for CI environments where privilege escalation is prohibited. According to the source code in agent_reach/cli.py, the --safe flag ensures the installer never invokes sudo or touches system files, making it suitable for containerized build environments where only Python package installation is permitted.

How do I verify what was actually installed after running safe mode?

Use the agent-reach doctor command, which executes the verification logic in agent_reach/doctor.py. This utility checks the actual state of your environment against the expected components, identifying which system-level tools you still need to manually install after a safe-mode deployment.

Does dry-run show the same output format as the actual installation logs?

Dry-run outputs a structured preview of intended actions rather than real-time installation logs. While the content reflects the steps defined in the installer logic, it presents them as a planned sequence without execution timestamps or progress indicators, focusing on the "what" rather than the "how" of the installation process.

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