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

The Agent-Reach CLI implements safe mode and dry-run capabilities through argparse flags (--safe and --dry-run) defined in 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

The implementation begins with argument parsing. In 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

# 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 (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 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.

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