| 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
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> pypi
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> test-pypi
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> test-pypi --version 0.4.0.dev42
bash .claude/skills/pypi-maintainer/scripts/switch-source.sh <package> local
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). |