How Agent Reach's `version` and `check-update` Commands Ensure Version Consistency Between `pyproject.toml` and `__init__.py`

Agent Reach guarantees version consistency by treating agent_reach/__init__.py as the single runtime source of truth for its version and check-update CLI commands, while a CI-enforced test in tests/test_cli.py blocks any pull request where pyproject.toml falls out of sync.

The open-source Agent Reach project must keep its package version aligned across source code, CLI output, and Python packaging metadata. Rather than parsing pyproject.toml at runtime, the commands defined in agent_reach/cli.py import __version__ directly from agent_reach/__init__.py. This design ensures that terminal output and update checks always reflect the installed package's internal version string, and a dedicated consistency test prevents accidental divergence in the build manifest.

The Single Source of Truth in agent_reach/__init__.py

The runtime version is declared exactly once in the Python package root:

# agent_reach/__init__.py

__version__ = "1.4.0"

The same string is duplicated in pyproject.toml under the [project] table:

# pyproject.toml

[project]
name = "agent-reach"
version = "1.4.0"

Because the CLI never reads pyproject.toml at runtime, that file serves only as passive metadata for pip and build frontends. Every user-facing command resolves the version from the live __version__ variable instead.

How the version Command Reads __version__

Both the --version flag and the explicit version sub-command live in agent_reach/cli.py. The argparse --version action (around lines 55–60) and the version sub-command handler (around lines 116–120) format output using the imported constant:

print(f"Agent Reach v{__version__}")

By pulling directly from agent_reach.__version__, these paths guarantee that CLI output always reflects the current state of __init__.py, independent of any packaging-time changes.

How check-update Compares Against __version__

The check-update command is implemented in agent_reach/cli.py (lines ~1614–1665). It imports __version__ at module scope (line 16) and prints the locally installed version:

print(f"当前版本: v{__version__}")

It then queries the GitHub releases API, extracts the latest tag, strips the leading v, and compares the result to __version__:

latest = data.get("tag_name", "").lstrip("v")

# comparison against __version__ (line 33)

If the remote tag differs from __version__, the command reports an available update; otherwise it confirms the current installation is up-to-date (lines 45–46). Because the comparison uses the same __version__ variable displayed by the version command, users always receive an accurate assessment of whether their installed copy matches the latest published release.

The CI Test That Enforces pyproject.toml Parity

Version drift is prevented by a test in tests/test_cli.py that loads agent_reach.__version__ and parses pyproject.toml with tomllib to assert the two values are identical:

def test_version_consistency():
    from agent_reach import __version__
    import tomllib, pathlib

    pyproj = pathlib.Path("pyproject.toml")
    data = tomllib.loads(pyproj.read_text())
    assert __version__ == data["project"]["version"]

Because this test runs on every pull request, any commit that updates one file without the other fails the build. This gate guarantees that pip-visible package metadata stays locked to the source-code constant powering the CLI.

Practical Examples

Display the installed version as reported by agent_reach/__init__.py:

$ agent-reach version
Agent Reach v1.4.0

Query GitHub for newer releases:

$ agent-reach check-update
当前版本: v1.4.0
✅ 已是最新版本

If a newer tag exists—for example v1.5.0—the same command outputs:

当前版本: v1.4.0
最新版本: v1.5.0 ← 有更新！
更新内容：
  ...release notes...
更新命令:
  pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip

Summary

• agent_reach/__init__.py defines __version__, the single runtime source of truth used by both the version and check-update commands.
• agent_reach/cli.py imports __version__ to render local version output and to compare against the latest GitHub release tag.
• pyproject.toml mirrors the version for build tools, but the CLI never depends on it at runtime.
• tests/test_cli.py enforces parity between the two files, failing CI whenever __version__ and project.version diverge.

Frequently Asked Questions

What happens if pyproject.toml and __init__.py have different versions?

The version and check-update commands will report the value from agent_reach/__init__.py. However, the test_version_consistency test in tests/test_cli.py will fail in CI, blocking the merge or release until both files are synchronized.

Why doesn't Agent Reach read the version from pyproject.toml at runtime?

Reading pyproject.toml on every CLI invocation adds file-system overhead and coupling to the package installation path. By importing __version__ directly from agent_reach/__init__.py, the CLI stays fast and deterministic, using the same constant that Python's import agent_reach would expose.

How does check-update know whether a new release exists?

The command queries the GitHub releases API, extracts the tag_name field, strips the leading v with lstrip("v"), and compares the resulting string to agent_reach.__version__. If the remote tag is newer, it prints the release notes and an upgrade command.

Where are the version and check-update commands defined?

Both commands live in agent_reach/cli.py. The --version flag and version sub-command reside around lines 55–60 and 116–120, respectively, while check-update spans approximately lines 1614–1665 in the same file.

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