How to Use Dry-Run Mode to Preview Installation Changes in Agent Reach

Run agent-reach install --dry-run to simulate the full installation pipeline without modifying your system, filesystem, or configuration files.

Agent Reach provides a dry-run mode for its deterministic, one-shot installer. This feature lets you preview every step of the installation process—system dependency checks, tool directory creation, optional channel installations, and configuration changes—before committing to any changes. The dry-run implementation lives entirely in agent_reach/cli.py and guarantees zero side effects on the host machine.

How to Enable Dry-Run Mode

The --dry-run flag is available on the install sub-command:

# Preview a default installation with auto-detected environment

agent-reach install --dry-run

# Preview installation with specific optional channels

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

# Combine dry-run with an explicit environment target

agent-reach install --env=server --dry-run

When detected, the installer prints a clear header and prefixes every simulated action with [dry-run] for transparency.

How Dry-Run Mode Works in the Source Code

The dry-run flow is orchestrated through four key stages in agent_reach/cli.py:

1. CLI Argument Definition

The flag is registered on the install sub-parser at lines 73–74:

# agent_reach/cli.py L73-L74

install_parser.add_argument("--dry-run", action="store_true",
                            help="Show what would be installed without making changes")

2. Flag Extraction in the Install Command

Early in _cmd_install, the flag value is captured (lines 16–18):

# agent_reach/cli.py L16-L18

def _cmd_install(args):
    dry_run = args.dry_run
    # ... further processing

3. Read-Only Configuration

When dry_run is enabled, the Config object is initialized with read_only=True (lines 54–55). This prevents any persistent configuration writes:

# agent_reach/cli.py L54-L55

config = Config(read_only=(dry_run or safe_mode))

4. Conditional Execution of Mutable Actions

Throughout _cmd_install, if dry_run: guards prevent actual system modifications:

Action	Dry-Run Behavior	Source Lines
Tools directory creation (~/.agent-reach/tools)	Skipped entirely	L59–L62
System dependencies	Routed to _install_system_deps_dryrun()	L300–L303
Optional channel installations	Listed as "would install" messages	L334–L337
Cookie import automation	Prints notice that no automatic import occurs	L60–L63

The system dependency check demonstrates this pattern clearly. In dry-run mode, the installer inspects the environment and reports what would happen rather than executing installers:

[dry-run] System dependency check:
  ✅ gh CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

Understanding Dry-Run Output

A typical dry-run session produces structured, scannable output:

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

Agent Reach Installer
========================================
Environment: Local computer (auto-detected)

[dry-run] System dependency check:
  ✅ gh CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

[dry-run] Would install mcporter and configure Exa search

[dry-run] Would install optional channels: reddit, twitter

[dry-run] Cookie import remains explicit; install will not read a browser

Each [dry-run] line corresponds to a code branch in agent_reach/cli.py where the actual implementation is bypassed in favor of a print statement.

When to Use Dry-Run Mode

Use --dry-run in these scenarios:

• Pre-installation planning — Verify system compatibility and review dependency requirements before running the real installer
• CI/CD pipelines — Validate installation scripts in test environments without side effects
• Documentation and training — Demonstrate Agent Reach installation behavior without modifying demo machines
• Debugging custom configurations — Preview how --channels, --env, or other flags alter the installation plan

Key Files for Dry-Run Implementation

File	Purpose
agent_reach/cli.py	Core implementation: argument parsing, flag handling, and all conditional dry-run logic
docs/install.md	User documentation explaining dry-run purpose and usage
README.md	Quick reference with dry-run command example

Summary

• Dry-run mode is invoked with agent-reach install --dry-run and produces zero system changes
• The implementation centers on agent_reach/cli.py, where dry_run boolean flags guard all mutable operations
• Read-only configuration (Config(read_only=True)) ensures no persistent settings are written
• All simulated actions are prefixed with [dry-run] and collected under a clear header for readability
• System dependencies, optional channels, directory creation, and cookie handling each have dedicated dry-run branches

Frequently Asked Questions

What exactly does dry-run mode prevent from happening?

Dry-run mode prevents: creation of the ~/.agent-reach/tools directory, execution of system package installers, actual installation of optional channels, automatic browser cookie imports, and any writes to configuration files. According to the source code in agent_reach/cli.py, every mutable action is wrapped in if not dry_run: logic.

Can I combine dry-run with other install flags?

Yes. The --dry-run flag composes with all other install options including --channels, --env, and --safe-mode. The args.dry_run value is extracted independently in _cmd_install and applied uniformly across all conditional branches.

Is dry-run mode safe to run on production systems?

Absolutely. The design explicitly guarantees no filesystem modifications. The Config object is forced into read-only state, and all installer subroutines either skip execution or route to dry-run variants that only print messages.

Where can I find more documentation about the install command?

The docs/install.md file contains user-facing documentation for dry-run usage. The README.md includes a quick reference table. For implementation details, examine the _cmd_install function and _install_system_deps_dryrun helper in agent_reach/cli.py.

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