How the `--dry-run` Flag Works in Agent Reach Install Commands

The --dry-run flag in Agent Reach lets you preview exactly what the install and uninstall commands would modify on your system without executing any actual changes, displaying simulated actions with the [dry-run] prefix.

The Agent Reach CLI, available in the Panniantong/Agent-Reach repository, provides a simulation mode that helps users understand the impact of installation operations before they commit to system modifications. This safety feature is implemented consistently across the two primary commands that alter your environment.

Flag Definition and Parsing

Both the install and uninstall subcommands implement the --dry-run flag using Python's argparse with action="store_true", converting the flag into a Boolean value that the command handlers check early in their execution flow.

Install Command Configuration

In agent_reach/cli.py, the install sub-parser defines the flag at lines 73-75:

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

Uninstall Command Configuration

The uninstall sub-parser defines the same flag at lines 99-100 of agent_reach/cli.py, ensuring consistent behavior across destructive operations.

Dry-Run Logic in the Install Workflow

When you invoke agent-reach install --dry-run, the handler _cmd_install checks args.dry_run immediately at lines 89-95 and prints a header banner. The implementation uses branch-by-branch guarding where every mutating operation is wrapped in a conditional that either executes the real action or prints a descriptive simulation message.

System Dependency Simulation

Rather than installing system packages, the code at lines 46-50 routes through _install_system_deps_dryrun to display what package managers would be invoked:

[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

Network and Search Tools Setup

At lines 55-59, the installer simulates the mcporter installation and Exa search configuration, outputting: [dry-run] Would install mcporter and configure Exa search.

Optional Channel Installation

The optional channel installers at lines 78-82 generate messages listing which specific channels would be activated based on your --channels flag:

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

Browser Cookie Import

Lines 86-90 handle browser cookie extraction, displaying: [dry-run] Would try to import cookies from Chrome/Firefox without accessing your browser data.

Dry-Run Logic in the Uninstall Workflow

The uninstall command handler _cmd_uninstall performs a similar early check at lines 87-90. Every destructive operation is replaced with a descriptive print statement indicating what would be removed.

Configuration Directory Removal

Lines 97-100 simulate removal of the config directory, outputting: [dry-run] Would remove config directory: ~/.agent-reach.

Skill Directory Cleanup

At lines 122-124, the code displays what skill directories would be deleted without touching the filesystem.

MCPorter Entry Removal

Inside the MCP-entry loop at lines 44-45, the uninstaller lists which mcporter entries would be removed (e.g., exa, xiaohongshu) rather than modifying the mcporter configuration.

Testing and Output Verification

The test suite in tests/test_cli.py validates the dry-run behavior at line 183, asserting that output contains the expected [dry-run] markers. Additionally, the post-install verification in agent_reach/doctor.py is automatically skipped when dry_run=True, ensuring that no side effects occur—not even diagnostic checks that might generate logs or network requests.

Practical Usage Examples

Preview a standard installation without system changes:

$ agent-reach install --dry-run
DRY RUN — showing what would be done (no changes)

Agent Reach Installer
========================================
[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] Would install mcporter and configure Exa search

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

[dry-run] Would try to import cookies from Chrome/Firefox
...
Dry run complete. No changes were made.

Simulate an install with specific channels:

$ agent-reach install --dry-run --channels=twitter,reddit
...
[dry-run] Would install optional channels: reddit, twitter
...

Preview an uninstall operation:

$ agent-reach uninstall --dry-run
DRY RUN — showing what would be removed (no changes)

Agent Reach Uninstaller
========================================
[dry-run] Would remove config directory: /home/user/.agent-reach
[dry-run] Would remove OpenClaw skill: /home/user/.openclaw/skills/agent-reach
[dry-run] Would remove mcporter entry: exa
[dry-run] Would remove mcporter entry: xiaohongshu
...
Dry run complete. No changes were made.

Summary

• Early Detection: Both install and uninstall commands check args.dry_run at the start of their respective handlers (_cmd_install at lines 89-95 and _cmd_uninstall at lines 87-90 in agent_reach/cli.py).
• Comprehensive Simulation: The flag covers system dependencies, network tools, optional channels, browser cookies, configuration directories, and mcporter entries.
• Consistent Messaging: All dry-run outputs follow the [dry-run] Would ... pattern, making it easy to parse the intended actions.
• Zero Side Effects: When enabled, the flag ensures no files are written, packages installed, directories removed, or network requests made, including skipping the post-install doctor verification.

Frequently Asked Questions

Does the --dry-run flag work with all Agent Reach commands?

No, the --dry-run flag is currently implemented only for the install and uninstall commands in agent_reach/cli.py. These are the primary commands that modify your system state by installing dependencies, configuring channels, or removing configuration directories. Other commands like doctor or config do not expose this flag because they either perform read-only operations or the flag is not relevant to their function.

How does dry-run mode affect the post-installation health check?

When --dry-run is enabled, the doctor.py verification routine is automatically skipped entirely. According to the source code structure, the health check runs only after a real installation completes, ensuring that dry-run sessions do not generate log files, create temporary directories, or send network pings that would otherwise leave traces on your system.

Can I combine --dry-run with other flags like --channels?

Yes, you can combine --dry-run with any other valid command flags. For example, using agent-reach install --dry-run --channels=twitter,reddit will simulate the installation but only show output for the specified channels (twitter and reddit) rather than all available optional channels. This works because the flag is evaluated once at the start of the command but applies to every conditional branch that follows.

Is the dry-run output format stable for scripting purposes?

While the output format follows a consistent [dry-run] Would ... pattern that is verified in tests/test_cli.py at line 183, you should treat the human-readable text as informational rather than a stable API for parsing. The specific wording of what "would" be done may change between versions as new installation steps are added to cli.py, even though the [dry-run] prefix remains consistent.

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