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

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 – Exposes the __version__ string that represents the currently installed release of the package.
• 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:

1. Retrieve the installed version. The CLI imports __version__ from 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:

python -m agent_reach.cli check-update

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

📦  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:

✅  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 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, 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, 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. 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.

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