# How the Agent-Reach CLI Implements Safe Mode and Dry-Run for Previewing Installations

> Agent-Reach CLI uses safe mode and dry-run flags to preview installations. Learn how it prints instructions or simulates changes without executing system commands to ensure safe deployments.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-12

---

**The Agent-Reach CLI implements safe mode and dry-run capabilities through argparse flags (`--safe` and `--dry-run`) defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which route installation logic to specialized preview functions that either print manual instructions without executing system commands or simulate installations with "DRY RUN" banners while skipping actual system modifications.**

The Agent-Reach command-line interface provides two optional flags on the `install` and `uninstall` sub-commands to prevent unintended system changes. These flags allow users to preview exactly what would be installed before committing any changes. This article examines how the CLI implements safe mode and dry-run for previewing installations by analyzing the argument parsing and conditional execution logic in the source code.

## Flag Definition and Argument Parsing in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)

The implementation begins with argument parsing. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 71-74), the `argparse` module registers both optional flags:

- `--safe` activates **safe mode**, preventing automatic system modifications
- `--dry-run` shows a preview of every action without modifying the system

When users invoke the `install` sub-command, the `_cmd_install` handler (lines 71-78) extracts these flags into local variables `safe_mode` and `dry_run` (lines 77-79).

### User Feedback and Banner Display

Before any execution, the CLI provides immediate visual feedback. If either flag is present, the handler prints a banner (lines 89-95) indicating which mode is active—either "DRY RUN" or "SAFE MODE"—so users understand the CLI's current behavior.

## Dry-Run Preview Implementation

When the `--dry-run` flag is set, the CLI routes to `_install_system_deps_dryrun()` (lines 94-100). This function:

1. Prints a "DRY RUN" banner
2. Displays what commands would execute (e.g., `apt install gh` or `brew install gh`)
3. Reports "Dry run complete" without executing system commands

For optional channel installers, the code skips actual installation when `dry_run` is true (lines 68-71).

## Safe Mode Execution Flow

The `--safe` flag triggers `_install_system_deps_safe()` (lines 120-126). This implementation:

1. Checks for required binaries without installing them
2. Prints manual installation instructions for missing dependencies
3. Exits without executing system-modifying commands

Unlike dry-run, which simulates what the automated installer would do, safe mode explicitly provides manual steps for users who prefer to install dependencies themselves.

## Command Usage Examples

```bash

# Show exactly what would be installed without touching the system

agent-reach install --dry-run

# Run the installer in safe mode to check requirements and print manual steps

agent-reach install --safe

# Combine both flags (dry-run takes precedence for preview)

agent-reach install --safe --dry-run

# Preview an uninstall operation

agent-reach uninstall --dry-run

```

### Sample Dry-Run Output

```

DRY RUN — showing what would be done (no changes)

[dry-run] System dependency check:
  gh CLI: would install via: apt install gh / brew install gh
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs
...
Dry run complete. No changes were made.

```

### Sample Safe Mode 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
All system dependencies are installed!
...

```

## Summary

- The flags `--safe` and `--dry-run` are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 71-74) and consumed by the `_cmd_install` handler (lines 71-78)
- **Dry-run mode** calls `_install_system_deps_dryrun()` (lines 94-100) to preview commands without executing them
- **Safe mode** invokes `_install_system_deps_safe()` (lines 120-126) to check requirements and print manual installation instructions
- Both modes skip actual system modifications for optional channel installers when flags are detected (lines 68-71)
- The same pattern applies to the `uninstall` sub-command, allowing users to preview removals before execution

## Frequently Asked Questions

### What is the difference between `--safe` and `--dry-run` in Agent-Reach?

The `--dry-run` flag simulates the automated installation process, showing exactly what commands would execute without running them, while `--safe` checks system state and provides manual installation instructions for missing dependencies, never attempting automatic system changes.

### Where are the safe mode and dry-run flags defined in the codebase?

Both flags are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 71-74 using `argparse`, then processed by the `_cmd_install` handler at lines 71-78 which routes to specialized functions like `_install_system_deps_safe()` (lines 120-126) or `_install_system_deps_dryrun()` (lines 94-100).

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

Yes, you can combine both flags when running `agent-reach install`, though dry-run typically takes precedence for preview purposes, showing what would be done while respecting the safe mode constraint of no automatic modifications.

### Does the uninstall command support dry-run previews?

Yes, the `uninstall` sub-command implements the same `--dry-run` flag (lines 99-101) to report what would be removed without actually deleting any files or system components.