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

Agent Reach enforces version synchronization across pyproject.toml, agent_reach/__init__.py, and 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 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 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.

version = "1.5.0"

agent_reach/init.py (Runtime Constant)

The 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 declaration exactly.

__version__ = "1.5.0"

tests/test_cli.py (Verification Suite)

The test suite in 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 sets the version on line 3. Second, agent_reach/__init__.py mirrors this value in __version__ on line 4.

The CLI in agent_reach/cli.py imports this constant and registers an argparse --version action that references the runtime constant:

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

When users query the version via the command line:

$ agent-reach version
Agent Reach v1.5.0

The test suite validates this exact output. The test_version method in tests/test_cli.py (lines 15-22) patches system arguments and captures stdout to verify the CLI reports the correct string:

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 and 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 and __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 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 (line 3), agent_reach/__init__.py (line 4), and the verification logic in tests/test_cli.py (lines 15-22).
• The hatchling build backend reads version metadata from pyproject.toml during wheel construction.
• Runtime code accesses the version through __version__ defined in the package root __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 and agent_reach/__init__.py to identical values, and 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 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 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 will fail because the CLI will report the old version from __init__.py, causing a mismatch with the expected output and blocking CI/CD pipelines until the values are synchronized.

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