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

> Learn how the Agent Reach --dry-run flag previews install and uninstall command changes without executing them. See simulated actions with the [dry-run] prefix before making modifications.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**, the install sub-parser defines the flag at lines 73-75:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```text
[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:

```text
[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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
$ 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:

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

```

Preview an uninstall operation:

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py), even though the `[dry-run]` prefix remains consistent.