pypi-maintainer

name	pypi-maintainer
type	command
description	Switch a PyPI package install between the production index, TestPyPI pre-release builds, and a local editable checkout. Use when an agent maintains a package and needs to verify a TestPyPI dev build before promoting to production, or when the user says "install from test-pypi", "switch to local", "change package source", or "install from pypi".

PyPI Maintainer

Switch the install source for a package the agent maintains. Three sources are supported: production PyPI, TestPyPI (pre-release / dev builds), and a local editable checkout. The same script works for any package an AgentCulture sibling publishes — pass the package name as the first argument.

When to use

• Verifying a PR's TestPyPI dev build before merging.
• Reproducing a user-reported bug against the published version.
• Hot-patching against a local checkout while a fix is in flight.
• Restoring the production install after local-mode debugging.

Usage

# Production PyPI
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> pypi

# TestPyPI (pre-release dev builds)
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> test-pypi

# TestPyPI, pinned to a specific dev version
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> test-pypi --version 0.4.0.dev42

# Local editable checkout (defaults to current directory)
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> local

# Local editable from an explicit path
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> local --path ../<package>

Prerequisites

The script requires the following tools on PATH:

• bash
• uv — the script delegates to uv tool install and uv tool list (or uv pip install for local).

Why TestPyPI needs special flags

When a package is published to both PyPI and TestPyPI, uv tool install finds the production version on PyPI first and never looks at TestPyPI. The script passes --index-strategy unsafe-best-match so uv compares the two index sets and picks the highest version, plus --prerelease=allow because TestPyPI builds carry dev suffixes (e.g. 0.4.0.dev42).

After running

The script prints the resolved version once install completes — cross-check that against the expected version (PR run number, local pyproject.toml) before continuing.

Arguments

Position / flag	Meaning
<package> (required)	The PyPI distribution name, e.g. steward-cli, culture, daria-cli.
<source> (required)	One of pypi, test-pypi, local.
--version VERSION	Pin to a specific version (TestPyPI builds typically need this).
--path PATH	Local-source-only: path to the editable checkout (default: cwd).