# How the `agent-reach install --safe` Flag Works for Non-Destructive Audits

> Learn how agent-reach install --safe performs non-destructive audits. Discover system dependencies and mcporter backend checks without modifying your system. Get manual installation instructions.

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

---

**The `--safe` flag triggers a non-destructive audit mode that checks for required system dependencies and the mcporter backend without installing anything, printing manual installation instructions instead of modifying your system.**

The `agent-reach install` command in the Panniantong/Agent-Reach repository provides a `--safe` option for users who need to verify requirements without granting the installer system modification privileges. When activated, this mode bypasses all automatic package installations and instead performs read-only checks using `shutil.which` to report missing binaries. This approach is ideal for corporate environments, CI pipelines, or any system where you prefer to manage dependencies manually.

## CLI Flag Definition and Parsing

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `--safe` argument is defined at lines 71-73. When the `_cmd_install` function executes, it captures this value at lines 177-178 into a `safe_mode` variable that controls the branching logic for the remainder of the installation process.

Rather than invoking the standard installation helpers, the CLI substitutes alternative "safe" functions that perform verification only.

## Safe Mode vs. Normal Installation Logic

The installer replaces three key operations with safe equivalents when `--safe` is passed:

### System Dependency Handling

Normal mode calls `_install_system_deps()`, which attempts to automatically install missing tools like GitHub CLI (`gh`) and Node.js using subprocess commands. 

In `--safe` mode, the code invokes `_install_system_deps_safe()` (lines 665-692). This function iterates through the required binaries and uses `shutil.which` to verify their presence on the system PATH. Missing tools are collected and displayed with manual installation instructions, but **no subprocess calls are executed** to install anything.

### Exa Search Backend (mcporter)

When installing the Exa search backend, normal execution runs `_install_mcporter()` to automatically set up the `mcporter` tool via npm.

The safe mode alternative, `_install_mcporter_safe()` (lines 962-970), simply checks whether the `mcporter` executable exists. If found, it confirms the installation; otherwise, it prints the manual installation command (`npm install -g mcporter`) without modifying the system.

### Optional Channel Installers

The installer typically runs channel-specific installers (for Twitter, Reddit, etc.) when the `--channels` flag is provided. Under `--safe` mode, these installers are skipped entirely to prevent any automatic package modifications beyond the core dependency checks.

## Combining with `--dry-run`

You can combine `--safe` with `--dry-run` for additional visibility. When both flags are present, the CLI prints a "DRY RUN" banner before executing the safe-mode checks, though the safe-mode behavior remains unchanged—no system modifications occur in either case.

## Usage Example

```bash

# Audit system requirements without installing anything

agent-reach install --safe

```

Expected output:

```

SAFE MODE — skipping automatic system changes

Checking system dependencies (safe mode — no auto‑install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  To install missing dependencies manually:
    Node.js: https://nodejs.org — or: apt install nodejs npm
Checking mcporter (safe mode)...
  mcporter not found
  To install manually: npm install -g mcporter

```

To preview with dry-run messaging:

```bash
agent-reach install --safe --dry-run

```

## Summary

- The `agent-reach install --safe` command switches from automatic installation to read-only verification
- System dependencies are checked via `shutil.which` in `_install_system_deps_safe()` (lines 665-692) rather than installed
- The mcporter backend is verified but not installed via `_install_mcporter_safe()` (lines 962-970)
- All optional channel installers are bypassed when `--safe` is active
- The mode can be combined with `--dry-run` for preview purposes without system changes

## Frequently Asked Questions

### Does `--safe` install any packages automatically?

No. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode uses `shutil.which` to verify binary presence and prints manual instructions. No subprocess calls are made to install packages, and optional channel installers are completely skipped.

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

Yes. These flags operate independently according to the implementation at lines 177-178. When combined, the CLI prints dry-run messaging before executing the safe-mode checks, but neither flag allows the installer to modify your system.

### What specific tools does safe mode check for?

The `_install_system_deps_safe()` function specifically checks for the GitHub CLI (`gh`) and Node.js (`node`) binaries. The `_install_mcporter_safe()` function checks for the `mcporter` executable required for Exa search functionality, as implemented at lines 962-970.

### Where is the safe mode logic implemented?

All safe mode functionality resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). The flag is parsed at lines 71-73, assigned at lines 177-178, and implemented in the `_install_system_deps_safe()` and `_install_mcporter_safe()` functions at lines 665-692 and 962-970 respectively.