# Agent Reach check-update Command: How It Detects New Versions

> Discover how the Agent Reach check update command detects new versions by querying PyPI. Learn to ensure your Agent Reach installation is always current with this simple command.

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

---

**The `check-update` command queries PyPI to compare your locally installed version against the latest published release, exiting with code 0 if current or code 1 if an update is available.**

The **Agent Reach** CLI includes a built-in `check-update` command that lets users quickly verify whether they are running the latest version of the package. This functionality, implemented in the `Panniantong/Agent-Reach` repository, automates version detection by reading local package metadata and fetching release data from PyPI. Understanding this mechanism helps you integrate automatic update checks into deployment scripts or CI pipelines.

## How the check-update Command Works

When you execute `agent-reach check-update`, the CLI performs a four-step validation process to determine if a newer version exists on PyPI. This flow is orchestrated by the private helper function `_cmd_check_update` inside [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

The command performs these operations in sequence:

1. Retrieves the current version from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) via the `__version__` constant
2. Fetches the latest release data from `https://pypi.org/pypi/agent-reach/json` using `urllib.request`
3. Parses both versions using `packaging.version.Version` for semantic comparison
4. Prints a colored status message via the `rich` library and returns an appropriate exit code

## Step-by-Step Implementation Details

### Reading the Current Version

The command first imports the local version identifier defined in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py). This `__version__` string serves as the ground truth for the installed package state.

```python

# In agent_reach/__init__.py

__version__ = "1.5.0"

```

The CLI module imports this constant at runtime to establish the baseline for comparison.

### Querying PyPI for the Latest Release

The `_cmd_check_update` function sends an HTTP GET request to the PyPI JSON API endpoint. The implementation uses the standard library `urllib.request` module to fetch metadata without external HTTP dependencies.

```python

# From agent_reach/cli.py (lines 1690-1698)

import urllib.request
import json

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

```

This JSON payload contains a nested `info.version` field representing the most recent release published to PyPI.

### Semantic Version Comparison

Rather than performing simple string comparison, the function uses the `packaging` library's `Version` class to ensure proper semantic versioning logic. This correctly handles pre-release tags, post-releases, and development versions.

```python

# From agent_reach/cli.py (lines 1700-1705)

from packaging.version import Version

current = Version(__version__)
latest = Version(latest_version)

if latest > current:
    # Update available logic

    pass

```

Using `packaging.version.Version` ensures that version `1.6.0` is correctly identified as newer than `1.5.9`, avoiding common string comparison pitfalls.

### CLI Output and Exit Codes

The function leverages the `rich` library to render colored output in the terminal. When a newer version exists, it displays a red warning message with installation instructions. If the versions match, it confirms the status in green.

The implementation returns specific exit codes to support programmatic usage:

- **Exit code 0**: You are on the latest version
- **Exit code 1**: A newer version is available

```python

# From agent_reach/cli.py (lines 1706-1715)

from rich import print

if latest > current:
    print(f"[bold red]A newer version ({latest}) is available![/]")
    print("Install with: pip install -U agent-reach")
    return 1
else:
    print(f"[bold green]You are on the latest version ({current})[/]")
    return 0

```

## Usage Examples

Check your current version status interactively:

```bash
$ agent-reach check-update
✅ You are on the latest version (1.5.0)

```

When an update exists, the command provides actionable feedback:

```bash
$ agent-reach check-update
⚠️  A newer version (1.6.0) is available! Install with:
     pip install -U agent-reach

```

You can script around the exit code to trigger automated updates:

```bash
#!/usr/bin/env bash
if ! agent-reach check-update; then
    pip install -U agent-reach
fi

```

## Key Source Files and Functions

The version detection logic spans several files in the `Panniantong/Agent-Reach` repository:

| File | Purpose |
|------|---------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Contains the `_cmd_check_update` function that implements the HTTP request, version comparison, and output formatting |
| [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) | Declares the `__version__` constant read by the CLI |
| [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) | Stores the canonical version used during packaging and publishing |
| [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) | Houses unit tests that mock PyPI responses to verify correct behavior |

## Testing the Version Detection Logic

The test suite validates the `check-update` command through the `test_check_update_reports_classified_error` test case in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py). This test:

- **Monkey-patches** `urllib.request` to simulate both successful PyPI responses and network failures
- **Invokes** `_cmd_check_update` directly to verify the function returns the correct exit code
- **Asserts** that the colored output matches expected strings for both update-available and up-to-date scenarios

This ensures the version comparison logic remains robust even when PyPI is unreachable or returns malformed data.

## Summary

- The **Agent Reach check-update command** detects new versions by comparing local `__version__` against PyPI's latest release data
- Implementation resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within the `_cmd_check_update` function
- Uses `packaging.version.Version` for semantic version comparison and `urllib.request` for HTTP fetching
- Returns exit code 0 when current, exit code 1 when an update is available, enabling shell script integration
- Output is formatted with the `rich` library for clear, colored terminal feedback

## Frequently Asked Questions

### How does Agent Reach check-update handle network errors?

If the PyPI request fails due to network issues, the `_cmd_check_update` function catches the exception and typically returns a non-zero exit code while printing an error message. The test suite in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) specifically validates this error handling by simulating failed HTTP requests.

### What version comparison algorithm does the check-update command use?

The command uses `packaging.version.Version` from the `packaging` library to parse and compare version strings. This ensures semantic versioning rules are applied correctly, properly ordering major, minor, and patch levels along with pre-release identifiers.

### Can I use the check-update command in automated scripts?

Yes. The command is designed for programmatic use by returning standardized exit codes: `0` indicates you are on the latest version, while `1` indicates a newer version is available. This allows shell scripts and CI pipelines to branch based on whether an upgrade is required.

### Where is the current version number stored in Agent Reach?

The runtime version is defined as `__version__` in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py), which is imported by the CLI module. The canonical version for packaging is maintained in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml), though both should remain synchronized in official releases.