# Agent Reach CLI Safe Mode vs Dry-Run vs Normal Installation: Functional Differences Explained > Understand Agent Reach CLI modes: Safe mode skips system packages, dry run previews actions without changes, and normal installation completes the full workflow. Choose the right install option. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: deep-dive - Published: 2026-06-08 --- **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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) where the `--safe` flag intercepts system installation routines before they execute. According to the documentation in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md), this mode is specifically designed for security-conscious deployments where the installer must not touch system files or invoke `sudo` privileges. ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) executes the installation logic in a read-only context, logging intentions rather than performing mutations. ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash # 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: ```bash agent-reach doctor ``` This command checks [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) - Use [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.