# Agent Reach Install: Difference Between --safe Mode and --dry-run Explained

> Understand the difference between Agent Reach install --safe mode and --dry-run. Learn how --safe audits dependencies while --dry-run simulates the full installation without changes.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-18

---

**The `--safe` flag audits missing dependencies without making system changes, while `--dry-run` simulates the complete installation workflow and prints `[dry-run]` prefixes for every action it would execute.**

Agent Reach provides two mutually exclusive verification modes for its installation command that help you preview changes before committing them. Understanding the difference between `--safe` mode and `--dry-run` in the Agent Reach install command prevents unintended system modifications during setup. Both options are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and trigger specific helper functions that determine exactly how system dependencies, optional channels, and cookie extraction are handled.

## What --safe Mode Does in Agent Reach Install

The `--safe` flag activates a restricted audit mode that reports what would be required without executing installation commands. When you invoke `agent-reach install --safe`, the installer prints a "SAFE MODE" banner (lines 92-95 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) and invokes checking versions of system dependency helpers rather than their installation counterparts.

### System Dependency Checking

In safe mode, the installer calls `_install_system_deps_safe()` (line 50) and `_install_mcporter_safe()` (line 58) instead of the standard installation functions. These safe variants verify the presence of required packages like `ffmpeg` and `libmagic` but explicitly skip any calls to `apt`, `brew`, or pip install commands. According to the source code at lines 45-53, the branching logic checks `safe_mode` before `dry_run`, ensuring that safe mode takes precedence when specified.

### Disabled Operations

Safe mode explicitly disables optional channel installation and cookie import steps. At lines 69-71, the code verifies that both `dry_run` and `safe_mode` are false before executing optional channel installations. Similarly, cookie extraction from Chrome or Firefox is bypassed entirely in safe mode, as the installer treats this as an automatic system modification.

## What --dry-run Mode Does in Agent Reach Install

The `--dry-run` flag performs a comprehensive simulation where every actionable step is replaced by a prefixed `[dry-run]` message. Unlike safe mode, dry-run provides a complete preview of the installation plan including optional channels and configuration steps that would normally modify your environment.

### Full Simulation with Command Preview

When `dry_run` is true, the installer invokes `_install_system_deps_dryrun()` at line 47 and the corresponding mcporter dry-run helper at line 55. These functions emit console output showing exactly which commands would execute, such as package manager invocations or proxy configuration writes. The implementation at lines 177-179 shows both flags being read into local variables immediately after argument parsing: `safe_mode = args.safe` and `dry_run = args.dry_run`.

### Optional Channel Handling

Dry-run mode provides visibility into optional channel installations that safe mode suppresses entirely. At lines 80-82, when `dry_run` is active, the installer prints a summary line indicating which channels would be installed (e.g., twitter, reddit, bilibili) rather than skipping the step. This distinction is critical because safe mode gives no indication of what optional components are available, while dry-run enumerates them explicitly.

## Key Implementation Differences

The source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) implements these modes through distinct execution branches that determine which helper functions run and what output is displayed.

### Argument Parsing and Variable Assignment

Both flags are added to the install sub-parser at lines 71 and 73, with `--safe` defined at line 71 and `--dry-run` at line 73. The argument parser ensures these options are available globally to the installation flow, and lines 177-179 extract these values for use in the conditional logic that follows.

### Branching Logic in the Installer

The three-branch conditional structure at lines 45-61 governs system dependency installation:

- **Dry-run path**: Calls `_install_system_deps_dryrun()` (line 47)
- **Safe mode path**: Calls `_install_system_deps_safe()` (line 50)  
- **Default path**: Calls `_install_system_deps()` (line 52)

The same pattern applies to mcporter installation at lines 55-61. For cookie extraction, lines 84-86 show that the actual import only occurs in local environments when neither flag is set, while lines 88-90 handle the dry-run placeholder message.

## Practical Usage Examples

Use these commands to leverage the distinct behaviors of each mode:

```bash

# Safe mode - only reports missing packages, never installs

agent-reach install --safe

```

```bash

# Dry-run mode - shows complete plan including optional channels

agent-reach install --dry-run --channels=twitter,reddit,bilibili

```

Running the dry-run command produces output similar to:

```

[dry-run] Would install optional channels: twitter, reddit, bilibili
[dry-run] Would try to import cookies from Chrome/Firefox
[dry-run] Would execute: apt-get install ffmpeg libmagic1

```

In contrast, safe mode output looks like:

```

SAFE MODE — skipping automatic system changes

System dependency check:
  [safe] Would install ffmpeg, libmagic, etc.

```

## Summary

- **`--safe` mode** invokes `_install_system_deps_safe()` and `_install_mcporter_safe()` to audit dependencies without executing package managers, and completely skips optional channel and cookie import steps.
- **`--dry-run` mode** invokes `_install_system_deps_dryrun()` and prints `[dry-run]` prefixes for every potential action, including optional channel installations and cookie extraction attempts that safe mode suppresses.
- Both flags are parsed at lines 71 and 73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and stored in variables at lines 177-179, but they trigger mutually exclusive code paths in the installation logic.
- Use `--safe` for quick dependency audits when you want to know what is missing without seeing installation commands, and use `--dry-run` when you need to preview the exact commands that would execute in a full installation.

## Frequently Asked Questions

### Can I use --safe and --dry-run together in Agent Reach install?

No, these flags are mutually exclusive in practice. While the argument parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 71-73) allows both to be set, the conditional logic at lines 45-53 checks `dry_run` before `safe_mode`, meaning dry-run takes precedence. If you specify both, you will see dry-run behavior with `[dry-run]` prefixes rather than safe mode output.

### Does --safe mode check optional channels?

No, safe mode completely bypasses optional channel installation checks. According to lines 69-71 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the optional channel installation block only executes when both `dry_run` and `safe_mode` are false. This means `--safe` provides no visibility into which channels would be installed, unlike `--dry-run` which enumerates them at lines 80-82.

### Which mode should I use for CI/CD pipelines?

Use `--dry-run` for CI/CD validation because it provides a complete simulation of the installation workflow including command previews. The dry-run mode exercises the full code path through `_install_system_deps_dryrun()` and reports all potential changes, allowing you to verify that the installer logic works correctly without modifying the build environment. Safe mode skips too many steps (like optional channels) to serve as a comprehensive CI check.

### What happens to cookie extraction in these modes?

Cookie extraction is disabled in both modes, but with different feedback. In safe mode, the step is silently skipped because the code at lines 84-86 requires both flags to be false. In dry-run mode, lines 88-90 print a placeholder message like `[dry-run] Would try to import cookies from Chrome/Firefox`, giving you visibility into what would happen during a real installation.