How Agent Reach Synchronizes Version Information Across pyproject.toml, __init__.py, and test_cli.py

Agent Reach maintains version consistency through manual synchronization where pyproject.toml serves as the canonical source, agent_reach/__init__.py exports the value as __version__, and the test suite validates that the CLI outputs the correct version string.

Maintaining accurate version metadata across build configurations and runtime code is essential for Python package reliability. In the Agent Reach repository, version information is explicitly defined in three critical files that require manual alignment during each release. This article explores the architectural pattern used to synchronize version information between the package configuration, module constants, and test assertions.

The Three Locations Defining Version Information

Agent Reach stores identical version strings in three distinct files that serve different stages of the package lifecycle.

Build Configuration in pyproject.toml

The canonical version resides in pyproject.toml at line 3, following PEP 621 standards:

version = "1.5.0"

This value is the single source of truth for build tools like pip and hatchling when packaging and publishing the distribution.

Runtime Export in agent_reach/init.py

The package exposes the version through agent_reach/__init__.py at line 4:

__version__ = "1.5.0"

This constant enables runtime introspection and is imported by the CLI module to display version information to users.

Test Validation in tests/test_cli.py

The test suite contains a validation check in tests/test_cli.py between lines 18 and 25. This test invokes the CLI version command and asserts that the output matches the expected format.

Version Flow Architecture

The data flows through the system following this explicit chain:

1. pyproject.toml holds the authoritative version string used by the build system
2. agent_reach/__init__.py duplicates this value as __version__ for runtime access
3. agent_reach/cli.py imports __version__ and prints it when users execute agent-reach version
4. tests/test_cli.py executes the CLI and verifies the output contains the correct version prefix

This design means the CLI output indirectly reflects the __init__.py value, while the build system reads directly from pyproject.toml.

Implementation Details

CLI Version Command

In agent_reach/cli.py, the application imports the package constant and registers it with the argument parser:

# agent_reach/cli.py

from agent_reach import __version__

def main():
    parser = argparse.ArgumentParser(...)
    parser.add_argument("--version", action="version", version=f"Agent Reach v{__version__}")
    # …

    if args.command == "version":
        print(f"Agent Reach v{__version__}")
        sys.exit(0)

When users run the command:

$ agent-reach version
Agent Reach v1.5.0

The CLI prints the exact value stored in the __version__ constant.

Test Verification Logic

The test in tests/test_cli.py validates the integration without hard-coding the version number:

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

This assertion guards against drift by ensuring the CLI outputs the expected format. A mismatch between pyproject.toml and __init__.py would result in a version string that differs from the intended release, surfacing as a test failure or visual discrepancy.

Manual Synchronization Workflow

Because the repository does not implement automatic version propagation, maintainers must manually synchronize the three locations when cutting a new release:

1. Update the version = "x.y.z" entry in pyproject.toml at line 3
2. Copy the same semantic version string to agent_reach/__init__.py as __version__ = "x.y.z" at line 4
3. Execute the test suite with pytest tests/test_cli.py -q to confirm the CLI reports the updated version

This manual approach requires discipline but ensures explicit control over the release metadata at each stage of the package lifecycle.

Summary

• Canonical source: pyproject.toml at line 3 provides the build-time version authority
• Runtime constant: agent_reach/__init__.py at line 4 exports __version__ for CLI consumption
• Validation layer: tests/test_cli.py lines 18-25 verify the CLI outputs the correct format
• Synchronization method: Manual copying between files without automated tooling
• Import chain: CLI imports from package root, tests invoke CLI directly

Frequently Asked Questions

How does Agent Reach keep pyproject.toml and init.py synchronized?

Agent Reach relies on manual maintenance rather than automation. When releasing a new version, developers must edit both pyproject.toml line 3 and agent_reach/__init__.py line 4 to contain identical version strings. The test suite then validates that the CLI prints the value from __init__.py, acting as a guardrail against accidental divergence.

What happens if the version strings differ between files?

If pyproject.toml and __init__.py contain different versions, the package will build with one version while the CLI reports another. This discrepancy would likely be caught during release testing when the test_version test runs or when developers visually inspect the agent-reach version output.

Why doesn't Agent Reach automate version synchronization?

The repository currently uses a manual approach to maintain explicit control over version metadata. While some Python projects use setuptools-scm or import __version__ dynamically from pyproject.toml, Agent Reach avoids build-time dependencies by duplicating the string explicitly.

Where is the Agent Reach version displayed to end users?

Users can view the version by executing the CLI command agent-reach version or agent-reach --version. Both commands output a string formatted as Agent Reach v{__version__}, where the value comes from agent_reach/__init__.py line 4.

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