# How to Preview Installation Actions Using Dry-Run in Agent-Reach

> Use the dry-run flag with Agent-Reach install or uninstall commands to preview system changes, dependencies, and configuration without altering your system. Learn how to safely preview.

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

---

**Pass the `--dry-run` flag to the `install` or `uninstall` command to generate a side-effect-free preview of system dependencies, configuration changes, and optional channels without modifying your system.**

Agent-Reach ships a deterministic installer that supports dry-run mode for safe deployment planning. When you append `--dry-run` to installation commands, the CLI performs a complete dependency analysis and configuration check without executing any system modifications. This makes it trivial to audit required dependencies, preview optional channel installations, and validate cookie extraction requirements before committing to actual changes.

## How Dry-Run Mode Works in Agent-Reach

The dry-run workflow is implemented across several components in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), providing comprehensive preview coverage for every installation phase.

### CLI Argument Parsing

The `--dry-run` flag is registered in the argument parser for both install and uninstall subcommands. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 70-74, the flag is added via `p_install.add_argument("--dry-run", …)`, making it available as a boolean option that the dispatcher can check throughout the execution pipeline.

### Install Command Implementation

Inside the `_cmd_install` function (lines 88-94), the code immediately stores the flag value in `dry_run = args.dry_run` and prints a prominent banner when enabled. This early capture ensures that every subsequent installation step can branch between execution and preview modes without side effects.

### System Dependency Preview

The `_install_system_deps_dryrun()` function (lines 90-98) generates a concise checklist of system tools and their installation commands. When dry-run is active, instead of invoking package managers like `apt` or `brew`, the function outputs the exact commands that would execute for each missing dependency—such as `apt install gh` for the GitHub CLI or NodeSource setup scripts for Node.js.

### Optional Channel Handling

For selective installations using `--channels`, the dry-run logic intercepts the channel installation phase (lines 60-63). Rather than invoking concrete installers, the code prints the specific set of channels that would be configured, such as `twitter`, `reddit`, or `xiaohongshu`, allowing you to verify your channel selection before downloading any components.

### Cookie Import and Uninstall Support

When cookie-requiring channels are requested, dry-run mode indicates that cookie extraction would be attempted (lines 89-92) without accessing browser data stores. The `uninstall` command mirrors this pattern (lines 71-75), printing the specific directories and files that would be removed—such as skill directories in `~/.openclaw/skills/` or `~/.claude/skills/`—while preserving the actual filesystem state.

## Practical Examples

### Preview a Full Installation

Run a complete system audit to see what Agent-Reach would install on your machine:

```bash
agent-reach install --dry-run

```

**Expected output excerpt:**

```

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] Would install mcporter and configure Exa search

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

Dry run complete. No changes were made.

```

### Preview Selective Channel Installation

Verify specific channel configurations before installing:

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

```

**Expected output excerpt:**

```

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

[dry-run] System dependency check: …

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

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

Dry run complete. No changes were made.

```

### Preview Uninstallation Actions

Review what would be deleted during uninstallation while preserving configuration:

```bash
agent-reach uninstall --dry-run --keep-config

```

**Expected output excerpt:**

```

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

[dry-run] Would remove OpenClaw skill: /home/user/.openclaw/skills/agent-reach
[dry-run] Would remove Claude Code skill: /home/user/.claude/skills/agent-reach
[dry-run] Would remove Agent skill: /home/user/.agents/skills/agent-reach

Dry run complete. No changes were made.

```

## Summary

- **Zero side effects**: The `--dry-run` flag in Agent-Reach prevents all system modifications while providing complete visibility into the installation process.
- **Comprehensive previews**: The mode covers system dependencies (`_install_system_deps_dryrun`), optional channels, cookie extraction requirements, and uninstallation targets.
- **Safety validation**: Use dry-run to audit required permissions, dependency versions, and configuration paths in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) before executing destructive operations.
- **Consistent interface**: Both `install` and `uninstall` commands support the flag, ensuring predictable behavior across all Agent-Reach operations.

## Frequently Asked Questions

### What does `--dry-run` actually prevent?

The flag prevents all filesystem modifications, package installations, and configuration writes. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), when `dry_run` is `True`, the installer skips execution blocks for system package managers, channel installers, and skill directory creation, limiting output to console messages that describe what would happen.

### Can I use dry-run with selective channel installation?

Yes. When you combine `--dry-run` with `--channels=twitter,reddit` (or any comma-separated list), the CLI parses your selection and prints the specific channels that would be installed without downloading any channel data or configuring API endpoints. This validates your channel syntax and availability before committing network resources.

### Does dry-run check system dependencies?

Absolutely. The `_install_system_deps_dryrun()` function performs a live check for required tools like the GitHub CLI (`gh`) and Node.js, then reports the exact installation commands that would run for your platform. This occurs in real-time, so you can verify whether your system meets requirements before the actual installation begins.

### Is dry-run available for uninstall commands?

Yes, the `uninstall` subcommand supports `--dry-run` using the same pattern as the install workflow. When enabled, it prints the specific skill directories and configuration files that would be removed—such as paths under `~/.openclaw/skills/` and `~/.claude/skills/`—without deleting any data, allowing you to verify the scope of removal before proceeding.