What Does the Agent Reach Install --dry-run Flag Do?

The --dry-run flag generates a complete preview of the installation process without executing any system changes, displaying exactly which dependencies would be installed, which channels would be added, and which cookies would be imported.

The Agent Reach open-source project provides a CLI tool for automating social media channel installations. When you want to verify what changes an installation would make before committing them, the --dry-run flag offers a safe, read-only simulation. This feature mirrors the actual installation flow defined in agent_reach/cli.py while suppressing all mutating operations.

How the --dry-run Flag Works in Agent Reach

The flag is implemented as a boolean toggle that redirects the installer from execution mode to preview mode.

CLI Argument Definition

In agent_reach/cli.py at lines 68-71, the argument is registered with the subparser:

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

Execution Flow in _cmd_install()

When the install command is invoked, the _cmd_install() function captures the flag value at line 62:

dry_run = args.dry_run

If enabled, the function immediately prints a banner at lines 73-76: "DRY RUN — showing what would be done (no changes)". The logic then branches to replace every mutating operation with a corresponding preview helper.

What Actions Are Previewed vs. Skipped

The dry-run mode substitutes destructive calls with diagnostic outputs that mirror the real execution path.

System Dependency Checks

Instead of installing GitHub CLI or Node.js, the code routes to _install_system_deps_dryrun() (lines 222-224). This helper enumerates system requirements and prints the intended installation method:

print("[dry-run] System dependency check:")
...
print(f"  {label}: would install via: {method}")

Optional Channel Installation

Lines 247-250 handle optional channels by printing a concise list of what would be installed rather than executing the installers. The output displays: [dry-run] Would install optional channels: twitter, reddit, bilibili.

Cookie Import Simulation

Browser cookie extraction is replaced with a notification at lines 276-279, printing [dry‑run] Would try to import cookies… instead of accessing browser data.

Practical Usage Examples

Run these commands to safely preview installations:

# Preview full installation without system changes

agent-reach install --dry-run

# Preview specific channels only

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

# Combine with safe mode for read-only validation

agent-reach install --dry-run --safe

Typical output mirrors the real flow while explicitly marking each step:

Agent Reach Installer
========================================
DRY RUN — showing what would be done (no changes)

Environment: Local computer (auto-detected)

[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 optional channels: twitter, reddit, bilibili
...
Dry run complete. No changes were made.

Summary

• The --dry-run flag in Agent Reach executes a simulated installation that prints every intended action without modifying the system.
• In agent_reach/cli.py, the flag triggers preview helpers like _install_system_deps_dryrun() instead of actual package managers.
• The mode previews system dependency installations, optional channel configurations, and browser cookie imports.
• No external installers, Docker pulls, or file writes occur during execution, making it safe for auditing production environments.

Frequently Asked Questions

Can I combine --dry-run with other installation flags?

Yes. The --dry-run flag functions correctly alongside options like --channels or --safe. When combined, the preview reflects exactly how those specific parameters would modify the installation scope without executing changes.

Does --dry-run perform any network requests or file writes?

No. According to the implementation in agent_reach/cli.py, the dry-run mode suppresses all mutating actions. It skips actual package installations, Docker operations, and cookie extractions, printing only what would occur during a live run.

Where is the --dry-run behavior tested?

The functionality is covered in tests/test_cli.py, which contains unit tests verifying that the flag correctly toggles the installer between preview mode and execution mode without causing side effects.

Will --dry-run detect my environment correctly?

Yes. The dry-run execution preserves all environment detection logic, including proxy configuration and operating system identification. It only bypasses the final mutating calls, ensuring the preview accurately reflects what a real installation would detect and configure.

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