# How the Agent Reach check-update Command Determines If a New Version Is Available

> Learn how the Agent Reach check-update command detects new versions by reading your local file, querying PyPI, and comparing releases with packaging.version.

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

---

**The `check-update` command reads the installed version from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py), queries the PyPI JSON API at `https://pypi.org/pypi/agent-reach/json`, and uses `packaging.version.Version` to compare the local version against the latest published release.**

The `check-update` command in Agent Reach provides users with immediate feedback on package updates without performing any installations. This CLI functionality, implemented in the open-source Agent Reach repository, helps developers stay current with the latest features and bug fixes. Understanding how the `check-update` command determines version availability reveals a lightweight, API-driven approach that relies solely on standard library modules and robust semantic versioning.

## How the check-update Command Works

The version detection process follows a deterministic four-step pipeline implemented in the CLI module.

### Step 1: Reading the Installed Version

The command first establishes the baseline version by importing `__version__` from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py). This value represents the currently installed package version in the user's environment.

```python

# In agent_reach/cli.py

from agent_reach import __version__

current_version = __version__

```

### Step 2: Querying the PyPI API

The implementation sends an HTTP GET request to the PyPI JSON API endpoint using `urllib.request` from the Python standard library. The endpoint `https://pypi.org/pypi/agent-reach/json` returns a comprehensive metadata payload for all published releases.

```python
import json
import urllib.request

def get_latest_version():
    url = "https://pypi.org/pypi/agent-reach/json"
    with urllib.request.urlopen(url) as response:
        data = json.loads(response.read().decode("utf-8"))
        return data["info"]["version"]

```

### Step 3: Parsing and Comparing Versions

Rather than performing naive string comparison, the command utilizes the `packaging.version.Version` class (falling back to `distutils.version.LooseVersion` in older implementations) to parse both version strings. This ensures accurate handling of pre-release tags, post-release segments, and developmental versions.

```python
from packaging.version import Version

def is_update_available(current, latest):
    return Version(latest) > Version(current)

```

### Step 4: Reporting Results to the User

The `check_update` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) formats the comparison result into user-facing messages. If the PyPI version exceeds the installed version, the CLI prints an upgrade prompt; otherwise, it confirms the user is up-to-date.

## Source Code Implementation

The version detection architecture depends on three key files in the repository:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** — Contains the `check_update` function that orchestrates the version check and handles the `check-update` sub-command wiring in the argument parser.
- **[`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)** — Exposes the `__version__` attribute used as the local version baseline.
- **[`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)** — Declares the package name `agent-reach`, which must match the PyPI endpoint queried by the CLI.
- **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)** — Houses unit tests that mock the PyPI HTTP response to verify the comparison logic without network dependencies.

## Practical Usage Examples

Execute the version check from the command line:

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

```

Typical output when a newer version exists:

```

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

```

Typical output when already up-to-date:

```

✅  You are already on the latest version (1.5.0)

```

## Summary

- The `check_update` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) implements the complete version check logic
- Local version is imported from `__version__` in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)
- The PyPI JSON API endpoint `https://pypi.org/pypi/agent-reach/json` provides the latest release data
- `packaging.version.Version` handles robust semantic version comparison including pre-releases
- The command performs read-only operations; it never modifies the installed package

## Frequently Asked Questions

### Does the check-update command automatically upgrade the package?

No, the command strictly checks availability and reports status. According to the Agent-Reach source code, the CLI never modifies installed packages. It merely prints a message suggesting `pip install -U agent-reach` when a newer version exists on PyPI.

### How does the command handle beta or release candidate versions?

The implementation uses `packaging.version.Version` to parse version strings, which properly recognizes development releases, alpha, beta, and release candidate tags (e.g., `1.2.0rc1`). This ensures that `1.2.0` is correctly identified as newer than `1.2.0rc1`, preventing false positive update prompts for pre-release installations.

### What happens if the PyPI API is unreachable?

Since the command relies on `urllib.request` to fetch `https://pypi.org/pypi/agent-reach/json`, any network failure or HTTP error would raise an exception. The current implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) does not catch these exceptions, meaning the CLI will display the Python traceback rather than a graceful error message.

### Where is the check-update command defined in the codebase?

The sub-command is defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and wired to the `check_update` function in the argument parser. This function imports the current version from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) and compares it against the `info.version` field returned by the PyPI JSON API.