Self-Managing Tool Lifecycle

The Pattern

Problem: Your tool runs as a long-lived service. Users need to check if it's healthy, upgrade it without SSH'ing in, and have it start on boot. You need this to work on both Linux (systemd) and macOS (launchd).

Approach: A doctor command for diagnostics, PEP 610 introspection for install source detection, an upgrade flow that stops-reinstalls-regenerates-restarts-verifies, and cross-platform service management with PATH forwarding.

Pattern proven in production across multiple Python CLI tools and web services.

Key Design Decisions

1. Doctor — structured checklist with colored output

Implement a doctor command that checks prerequisites, versions, service status, and update availability:

def doctor() -> None:
    ok_mark = "\033[32m\u2713\033[0m"    # green check
    fail_mark = "\033[31m\u2717\033[0m"  # red x
    warn_mark = "\033[33m!\033[0m"       # yellow warning

The checklist should cover:

• Python version (3.11+ required)
• External dependencies (docker, git, etc.)
• Tool version + install source + update check
• Settings file existence
• Serve configuration
• TLS certificate status and expiry (if applicable)
• Auth status (if applicable)
• Active sessions/instances
• Platform + service status

The service status check should be platform-aware:

if sys.platform == "darwin":
    plist = Path.home() / "Library" / "LaunchAgents" / "com.my-tool.plist"
    if plist.exists():
        result = subprocess.run(
            ["launchctl", "print", f"gui/{uid}/com.my-tool"],
            capture_output=True, text=True,
        )
        if result.returncode == 0:
            print(f"  {ok_mark} Service: launchd agent running")
else:
    systemd_user = Path.home() / ".config" / "systemd" / "user" / "my-tool.service"
    if systemd_user.exists():
        print(f"  {ok_mark} Service: systemd user unit installed")

2. PEP 610 install source detection via direct_url.json

Detect how the tool was installed to determine the correct upgrade strategy:

def _get_install_info() -> dict:
    """Detect how the tool was installed using PEP 610 direct_url.json."""
    dist = distribution("my-tool")
    info["version"] = dist.metadata["Version"]
    du_text = dist.read_text("direct_url.json")
    if du_text:
        du = json.loads(du_text)
        if "vcs_info" in du:
            info["source"] = "git"
            info["commit"] = du["vcs_info"].get("commit_id", "")
            info["url"] = du.get("url", "")
        elif "dir_info" in du and du["dir_info"].get("editable"):
            info["source"] = "editable"
        else:
            info["source"] = "unknown"
    else:
        info["source"] = "pypi"  # No direct_url.json → probably PyPI

Update checking uses the install source:

def _check_for_update(info) -> tuple[bool, str]:
    if info["source"] == "editable":
        return False, "editable install — manage updates manually"
    if info["source"] == "git":
        # Compare installed commit_id against remote HEAD sha
        result = subprocess.run(["git", "ls-remote", info["url"], "HEAD"], ...)
        remote_sha = result.stdout.strip().split()[0]
        if local_sha == remote_sha:
            return False, f"up to date (commit {local_sha[:8]})"
        return True, f"update available ({local_sha[:8]} → {remote_sha[:8]})"
    if info["source"] == "pypi":
        # Compare against PyPI JSON API
        ...

3. Upgrade flow: stop > reinstall > regenerate service > restart > verify

The upgrade sequence is strict and ordered:

def upgrade(force=False):
    # 1. Check if update is available (skip if --force)
    # 2. Stop the running service
    subprocess.run(["launchctl", "bootout", f"gui/{uid}/{label}"])
    # 3. Reinstall from source
    subprocess.run([uv_path, "tool", "install",
                    "git+https://...", "--force"])

…