# Agent Reach Version Synchronization: Keeping pyproject.toml, __init__.py, and test_cli.py Aligned

> Learn how Agent Reach synchronizes versions across pyproject.toml, __init__.py, and test_cli.py. Ensure consistent build metadata, runtime constants, and CLI output for reliability.

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

---

**Agent Reach enforces version synchronization across [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml), [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py), and [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) to ensure that build metadata, runtime constants, and CLI output always report identical version strings.**

Maintaining consistent version numbers across build configuration, Python modules, and test suites prevents packaging errors and user confusion. In the Agent Reach repository, version synchronization is implemented through a manual single-source-of-truth pattern that links [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) declarations to runtime `__version__` constants and CLI verification tests. This article examines the exact file locations and code mechanisms that keep Agent Reach version synchronization intact.

## The Three Critical Files for Version Synchronization

### pyproject.toml (Build Metadata)

Located at the repository root, [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) contains the build configuration used by the **hatchling** build backend. Line 3 declares the canonical version string that determines what `pip` and package indexes publish.

```toml
version = "1.5.0"

```

### agent_reach/__init__.py (Runtime Constant)

The [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) module exposes the **__version__** constant on line 4, making the version available to downstream imports and the CLI. This runtime value must match the [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) declaration exactly.

```python
__version__ = "1.5.0"

```

### tests/test_cli.py (Verification Suite)

The test suite in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) contains `TestCLI.test_version` (lines 15-22), which executes the CLI and asserts that the output contains the expected version string. This creates a CI-enforced check that prevents version drift between the build system and the runtime.

## How Version Synchronization Works in Agent Reach

The synchronization chain flows from build configuration to user-facing interfaces. First, [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) sets the version on line 3. Second, [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) mirrors this value in `__version__` on line 4.

The CLI in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) imports this constant and registers an `argparse` `--version` action that references the runtime constant:

```python
parser.add_argument(
    "--version",
    action="version",
    version=f"Agent Reach v{__version__}"
)

```

When users query the version via the command line:

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

```

The test suite validates this exact output. The `test_version` method in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (lines 15-22) patches system arguments and captures stdout to verify the CLI reports the correct string:

```python
def test_version(self, capsys):
    with pytest.raises(SystemExit) as exc_info:
        with patch("sys.argv", ["agent-reach", "version"]):
            main()
    assert exc_info.value.code == 0
    captured = capsys.readouterr()
    assert "Agent Reach v" in captured.out

```

Because the CLI derives its output directly from `__version__`, any mismatch between [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) surfaces as a failing test, forcing developers to keep all three locations aligned.

## Consequences of Version Drift

If any of the three files contain divergent version strings, the repository's continuous integration fails immediately. A mismatch between [`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) causes the CLI to report a different version than what pip installs, creating confusion for end users. Similarly, if the test expectations in [`test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_cli.py) do not match the actual CLI output, assertion failures block merges and releases.

## Summary

- **Agent Reach version synchronization** requires identical version strings in three specific files: [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) (line 3), [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) (line 4), and the verification logic in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (lines 15-22).
- The **hatchling** build backend reads version metadata from [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) during wheel construction.
- Runtime code accesses the version through `__version__` defined in the package root [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py).
- The CLI generates its `--version` output using this runtime constant, printing `Agent Reach v{__version__}`.
- Automated tests enforce synchronization by verifying that the `agent-reach version` command output matches the expected format, preventing releases with mismatched metadata.

## Frequently Asked Questions

### What is the single source of truth for Agent Reach versioning?

There is no automated single file; instead, the repository enforces synchronization through the test suite. Developers must manually update [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) to identical values, and [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) verifies the CLI reflects these values correctly.

### Which build backend does Agent Reach use for version management?

Agent Reach uses **hatchling**, which reads the `version` field from [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) line 3 when building distribution packages.

### How does the CLI access the package version?

The CLI imports `__version__` directly from the `agent_reach` package (defined in [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) line 4) and passes it to `argparse` as an f-string: `version=f"Agent Reach v{__version__}"`.

### What happens if I update the version in pyproject.toml but forget to update __init__.py?

The `test_version` test in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) will fail because the CLI will report the old version from [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py), causing a mismatch with the expected output and blocking CI/CD pipelines until the values are synchronized.