# How to Install Agent Reach CLI: Complete Setup Guide from Source

> Install Agent Reach CLI from source with our complete guide. Clone the repository, install the package via pip, and run the doctor command for setup validation. Get Agent Reach up and running quickly.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: getting-started
- Published: 2026-07-24

---

**Install Agent Reach CLI by cloning the Panniantong/Agent-Reach repository, installing the package in editable mode with `pip install -e .`, and running the built-in doctor command to validate system prerequisites.**

Agent Reach is a Python-based command-line interface that bundles "glue" tools for accessing multiple internet platforms through a unified channel architecture. To install the CLI from the Panniantong/Agent-Reach source repository, you will clone the code, install the package in development mode, and configure platform-specific credentials. This guide covers the complete installation process using the official [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) procedure and the diagnostic tools defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).

## Prerequisites

Before installing Agent Reach CLI, ensure your system meets the following requirements:

- **Python 3.10 or higher** – The codebase requires modern Python features as specified in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Git** – Required to clone the repository from GitHub.
- **pip** – Python's package installer for handling dependencies.

## Step-by-Step Installation

### Clone the Repository

First, download the source code from GitHub to your local machine. This gives you access to the full package including [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and the doctor module.

```bash
git clone https://github.com/Panniantong/Agent-Reach.git
cd Agent-Reach

```

### Create a Virtual Environment (Recommended)

Isolate the Agent Reach dependencies from your global Python installation to avoid conflicts.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

### Install in Editable Mode

Install the package using the editable (`-e`) flag. This registers the CLI entry point while keeping source files linked for instant updates without reinstallation.

```bash
pip install -e .

```

This command processes the package configuration and makes the `agent_reach` module available as a runnable CLI.

### Verify the CLI Installation

Confirm that the CLI is properly registered by displaying the top-level help menu defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```bash
python -m agent_reach.cli --help

```

This should output available subcommands including `doctor`, `install`, `read`, and `search`.

### Run the Doctor Command

Execute the built-in diagnostics to verify system prerequisites. The doctor module ([`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) checks for required tools like `ffmpeg`, validates network connectivity, and confirms Python version compatibility.

```bash
python -m agent_reach.cli doctor

```

### Configure Environment Variables

Auto-configure the environment using the install command with the `--env=auto` flag. This detects your operating system, installs optional dependencies, and generates a default `.env` file with placeholders for API keys and cookies.

```bash
python -m agent_reach.cli install --env=auto

```

After auto-configuration, edit the generated `.env` file to add your actual credentials for platforms like Twitter and XHS. Refer to [`docs/cookie-export.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/cookie-export.md) for the correct cookie format required by the channel implementations in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).

## Testing Your Installation

Verify end-to-end functionality by executing a read operation on a supported platform. This confirms that the CLI, configuration loader ([`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)), and channel contracts are working correctly.

```bash
python -m agent_reach.cli read https://twitter.com/username/status/12345

```

If the command returns platform data without errors, your Agent Reach CLI installation is fully operational.

## Summary

- **Clone** the Panniantong/Agent-Reach repository to access source files including [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).
- **Install** using `pip install -e .` for editable mode, allowing instant updates when modifying channel code.
- **Validate** installation with `python -m agent_reach.cli doctor` to check system prerequisites and network connectivity.
- **Configure** platform credentials via `python -m agent_reach.cli install --env=auto` and edit the generated `.env` file.
- **Test** functionality using the read command to confirm channel access works end-to-end.

## Frequently Asked Questions

### What Python version is required for Agent Reach CLI?

Agent Reach CLI requires **Python 3.10 or higher**. The doctor module in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) explicitly validates this version during the diagnostic phase to ensure compatibility with modern async features and type hints used throughout the codebase.

### Why should I use editable mode (`-e`) when installing?

Using `pip install -e .` installs the package in **development mode**, which links the installed package directly to your source files. This means any changes you make to the channel implementations in `agent_reach/channels/` or configuration logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) take effect immediately without requiring reinstall.

### How do I add credentials for platforms like Twitter or XHS?

After running `python -m agent_reach.cli install --env=auto`, the CLI generates a `.env` file in your project root. Open this file and paste the required API keys or session cookies for each platform. Consult [`docs/cookie-export.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/cookie-export.md) for the specific cookie format expected by the `BaseChannel` class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).

### What does the doctor command check?

The `doctor` command performs comprehensive system validation defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). It verifies your Python version, checks for optional system binaries like `ffmpeg` (required for video extraction), tests network connectivity to supported platforms, and validates that your configuration files contain valid syntax.