# How the `check-update` Command Verifies New Versions in Agent Reach

> Learn how the check-update command in Agent Reach queries PyPI to verify new versions. Get alerted to available upgrades without automatic installation.

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

---

**The `check-update` command queries the PyPI JSON API to compare your locally installed version against the latest published release, alerting you when upgrades are available without performing any automatic installation.**

The `check-update` command is a built-in diagnostic utility in the Agent Reach CLI that helps users determine whether they are running the most recent release of the Panniantong/Agent-Reach repository. When you execute this command, it performs a lightweight network check against the Python Package Index to verify new versions and report availability. This functionality is implemented entirely within the `agent_reach` package using standard library modules and the `packaging` utility for robust semantic version comparison.

## Where the Version Check Logic Resides

The mechanism that verifies new versions spans two core files:

- **[`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)** – Exposes the `__version__` string that represents the currently installed release of the package.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Contains the `check_update` function that orchestrates the PyPI query and comparison logic, wired to the `check-update` sub-command via the CLI argument parser.

## How the check-update Command Functions to Verify New Versions

When invoked, the command executes a precise five-step validation process according to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

1. **Retrieve the installed version.** The CLI imports `__version__` from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) to establish the baseline version string present in your environment.

2. **Query the PyPI registry.** Using `urllib.request`, the function sends an HTTP GET request to `https://pypi.org/pypi/agent-reach/json`. This endpoint returns a JSON payload containing metadata for all published releases of the package.

3. **Extract the latest release.** From the response JSON, the command reads the `info.version` field, which contains the newest version string available on PyPI.

4. **Compare semantic versions.** The implementation uses `packaging.version.Version` (with a fallback to `distutils.version.LooseVersion` in older code) to perform a robust comparison between the installed version and the remote version. This correctly handles pre-release tags like `1.2.0rc1` and beta versions according to PEP 440 standards.

5. **Report findings.** If the installed version is equal to or newer than the PyPI version, the CLI prints a confirmation message. If the PyPI version is newer, it displays a warning with the specific version number and suggests running `pip install -U agent-reach`.

## Implementation Details and Network Behavior

The `check-update` command relies on minimal dependencies to ensure portability. It utilizes **`urllib.request`** for the network call and **`json`** for parsing the API response. The version comparison logic leverages the **`packaging`** library to handle complex semantic versioning schemes, ensuring that version strings like `2.0.0` and `2.0.0b1` are ordered correctly.

Notably, this command operates in a **read-only mode**; it fetches metadata but never modifies your local installation or initiates upgrades automatically. The check is stateless and does not cache the PyPI response between invocations.

## Usage Examples

Invoke the version verifier directly from your terminal:

```bash
python -m agent_reach.cli check-update

```

When a newer version exists on PyPI, you will see output similar to:

```text
📦  Current version: 1.4.0
🚀  New version available: 1.5.0
Run: pip install -U agent-reach

```

If you are already on the latest release, the command confirms:

```text
✅  You are already on the latest version (1.5.0)

```

## Summary

- The `check-update` command functions by querying the PyPI JSON API at `https://pypi.org/pypi/agent-reach/json` to fetch the latest release metadata.
- It compares the installed version from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) against the remote version using `packaging.version.Version` for accurate semantic comparison.
- The implementation lives in the `check_update` function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), exposed as the `check-update` CLI sub-command.
- The command performs no automatic installation; it only informs users whether an update is available and suggests the appropriate `pip` upgrade command.
- Standard library modules (`urllib.request`, `json`) handle network requests and parsing, ensuring the feature works without additional third-party dependencies beyond `packaging`.

## Frequently Asked Questions

### Does the `check-update` command automatically install updates when it finds a new version?

No. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the command is strictly informational and read-only. It queries PyPI to verify new versions and reports availability, but you must manually execute `pip install -U agent-reach` to perform the actual upgrade.

### Which Python library handles the version comparison logic?

The implementation uses `packaging.version.Version` for semantic version comparison, with a fallback to `distutils.version.LooseVersion` in older contexts. This ensures accurate ordering of pre-releases, beta versions, and final releases according to PEP 440 standards.

### What specific PyPI endpoint does the command query to check for updates?

The function sends an HTTP GET request to `https://pypi.org/pypi/agent-reach/json`. This is the standard PyPI JSON API endpoint for the `agent-reach` package, which returns a JSON object containing the `info.version` field and other release metadata.

### How does the command determine which version is currently installed?

The CLI reads the `__version__` variable exported from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py). This value is defined at build time in the package source and reflects the exact version string of the installed Agent Reach distribution in your Python environment.