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

> Learn how Agent Reach's version and check-update commands maintain consistency between pyproject.toml and __init__.py, ensuring error-free deployments. Discover the single source of truth strategy.

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

---

**Agent Reach guarantees version consistency by treating [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) blocks any pull request where [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) at runtime, the commands defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) import `__version__` directly from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)

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

```python

# agent_reach/__init__.py

__version__ = "1.4.0"

```

The same string is duplicated in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) under the `[project]` table:

```toml

# pyproject.toml

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

```

Because the CLI never reads [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/__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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines ~1614–1665). It imports `__version__` at module scope (line 16) and prints the locally installed version:

```python
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__`:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) Parity

Version drift is prevented by a test in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) that loads `agent_reach.__version__` and parses [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) with `tomllib` to assert the two values are identical:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py):

```bash
$ agent-reach version
Agent Reach v1.4.0

```

Query GitHub for newer releases:

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

```

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

```bash
当前版本: 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** imports `__version__` to render local version output and to compare against the latest GitHub release tag.
- **[`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)** mirrors the version for build tools, but the CLI never depends on it at runtime.
- **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) have different versions?

The `version` and `check-update` commands will report the value from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py). However, the `test_version_consistency` test in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) at runtime?

Reading [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.