The release checklist, in order. Every command here is PowerShell on Windows. Nothing is optional — each step exists because skipping it has burned a release before (see Known traps at the end).
Authentication is interactive: twine prompts for the token at upload time, so no secret is ever written to disk or into this repo.
Run everything from the project root:
cd C:\Users\doyle\PycharmProjects\webamon-cli
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pip install build twineGet a PyPI API token — https://pypi.org/manage/account/token/ → Add API
token, scoped to the webamon-cli project. Keep it in your password manager.
Get a separate TestPyPI token from https://test.pypi.org/manage/account/token/ (the two sites have independent accounts and tokens).
You do not need a .pypirc file. Twine will prompt for credentials on each
upload, which keeps the tokens off this machine's disk. When prompted:
Enter your username: __token__
Enter your password: <paste the pypi-... token — input is hidden>
__token__ is the literal username, not your PyPI account name. The password
is the whole token including the pypi- prefix. Paste with Ctrl+V or
right-click; the prompt shows nothing as you type — that's expected.
The version lives in two files and they must match:
| File | Field |
|---|---|
webamon_cli\__init__.py |
__version__ = "X.Y.Z" |
pyproject.toml |
version = "X.Y.Z" |
Everything else derives from __init__.py — the --version flag and the HTTP
User-Agent. setup.py reads pyproject.toml, so there's nothing to change
there.
Also update EXPECTED in tests\test_version.py to the new version.
.\.venv\Scripts\python.exe -m pytest tests/test_version.py -qThat test fails if the two files drift, or if the User-Agent falls behind.
Semver: patch = fixes, minor = new commands/options, major = breaking changes.
.\.venv\Scripts\python.exe -m pytestAll tests must pass. For a coverage view:
.\.venv\Scripts\python.exe -m pytest --cov=webamon_cli --cov-report=term-missingFast loop — source changes take effect with no reinstall:
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\webamon.exe --version
.\.venv\Scripts\webamon.exe --help
.\.venv\Scripts\webamon.exe campaigns --help
.\.venv\Scripts\webamon.exe clusters --helpSmoke-test against the live API with a key:
$env:WEBAMON_API_KEY = "your-key-here"
.\.venv\Scripts\webamon.exe status
.\.venv\Scripts\webamon.exe clusters list --size 5
.\.venv\Scripts\webamon.exe campaigns list --size 5An editable install proves your source works. It does not prove the built artifact works — that's step 5, and it's the step that catches packaging bugs.
Always clean first. Stale artifacts in dist\ are the single most common
way to publish the wrong thing:
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m buildProduces:
dist\webamon_cli-X.Y.Z-py3-none-any.whl
dist\webamon_cli-X.Y.Z.tar.gz
Confirm both carry the new version and that dist\ holds nothing else:
Get-ChildItem distwebamon fields reads a bundled JSON file. If it isn't in the wheel, that
command breaks for every installed user while working perfectly for you:
.\.venv\Scripts\python.exe -c "import zipfile,glob; print('\n'.join(zipfile.ZipFile(sorted(glob.glob('dist/*.whl'))[-1]).namelist()))"webamon_cli/scans_fields.json must be in that list. It's included via
MANIFEST.in (recursive-include webamon_cli *.json).
.\.venv\Scripts\python.exe -m twine check dist/*Both files must report PASSED. This catches a malformed README that PyPI
would reject — or that would render as raw text on the project page.
The most important step. Install the wheel exactly as a user would, in a venv that shares nothing with your dev environment:
$verify = "$env:TEMP\verifyvenv"
Remove-Item -Recurse -Force $verify -ErrorAction SilentlyContinue
python -m venv $verify
& "$verify\Scripts\python.exe" -m pip install (Get-ChildItem dist\*.whl).FullName
& "$verify\Scripts\webamon.exe" --version
& "$verify\Scripts\webamon.exe" --help
& "$verify\Scripts\webamon.exe" clusters --help
& "$verify\Scripts\webamon.exe" fields --search domain --format jsonChecklist:
-
--versionprints the version you just built (not an older one) - Every command group appears:
campaigns,clusters,configure,fields,infostealers,report,scan,screenshot,search,status -
fieldsreturns JSON (proves the bundled data file shipped) - No
ModuleNotFoundError— a dependency missing frompyproject.tomlsurfaces here, because the clean venv has nothing preinstalled
.\.venv\Scripts\python.exe -m twine upload --repository testpypi dist/*Twine prompts:
Enter your username: __token__
Enter your password: <paste your TestPyPI token>
Install it from TestPyPI into another clean venv. --extra-index-url is
required because the real dependencies (click, requests, rich) don't exist on
TestPyPI:
$tp = "$env:TEMP\tpvenv"
Remove-Item -Recurse -Force $tp -ErrorAction SilentlyContinue
python -m venv $tp
& "$tp\Scripts\python.exe" -m pip install `
--index-url https://test.pypi.org/simple/ `
--extra-index-url https://pypi.org/simple/ `
webamon-cli==X.Y.Z
& "$tp\Scripts\webamon.exe" --versionAlso eyeball https://test.pypi.org/project/webamon-cli/ — README rendering, description, links.
.\.venv\Scripts\python.exe -m twine upload dist/*At the prompt use __token__ and your production PyPI token (not the
TestPyPI one).
Then verify from real PyPI:
$final = "$env:TEMP\finalvenv"
Remove-Item -Recurse -Force $final -ErrorAction SilentlyContinue
python -m venv $final
& "$final\Scripts\python.exe" -m pip install webamon-cli==X.Y.Z
& "$final\Scripts\webamon.exe" --versionA version number on PyPI can never be reused. Even after deleting a release, that version is burned forever. If you publish a broken
0.3.0, the only fix is to publish0.3.1. That's why steps 5 and 6 exist.
git add -A
git commit -m "Release vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push
git push --tags[ ] Version bumped in webamon_cli\__init__.py AND pyproject.toml
[ ] EXPECTED updated in tests\test_version.py
[ ] Full test suite passes
[ ] Remove-Item -Recurse -Force dist, build, *.egg-info
[ ] python -m build
[ ] Get-ChildItem dist -> new version only, nothing stale
[ ] scans_fields.json present in the wheel
[ ] twine check dist/* -> PASSED
[ ] Clean-venv install of the wheel: --version correct, all commands present
[ ] TestPyPI upload + clean install verified
[ ] twine upload dist/* (interactive: __token__ + production token)
[ ] Verified from real PyPI
[ ] Tagged and pushed
Stale wheels in dist\. During 0.3.0 development a rebuild produced a wheel
with the same version as one already in dist\. pip installed the stale file
and the new campaigns command was silently missing from the "verified"
install. Always clean before building, and always confirm --version in the
clean venv.
A version bump in only one file. __init__.py and pyproject.toml are
independent. If they disagree, the wheel metadata and --version disagree too.
tests\test_version.py guards this — run it.
Hardcoded version strings. The User-Agent sat at 0.1.1 while the package
was 0.2.3, so API logs mislabelled every request for two releases. It now
derives from __version__; keep it that way.
Editable install passing while the wheel fails. pip install -e . uses your
source tree directly, so it can't catch a missing package-data file or an
unlisted dependency. Only the clean-venv wheel test does.
Missing runtime dependency. Anything imported at runtime must be in
pyproject.toml's dependencies. Your dev venv has extras installed; the clean
venv is what proves the list is complete.
PowerShell gotchas.
- Use the backtick
`for line continuation, not\. .\.venv\Scripts\python.exe— the leading.\is required to run from the current directory.- Use
&to invoke an executable held in a variable:& "$verify\Scripts\webamon.exe" --version. Remove-Item -Recurse -Forceis therm -rfequivalent;-ErrorAction SilentlyContinuestops it erroring when the path is absent.
If you ever do want stored credentials instead of the interactive prompt,
the file is C:\Users\<you>\.pypirc (twine finds it automatically) and it must
contain a [distutils] block listing the servers. Lock it down with
icacls "$env:USERPROFILE\.pypirc" /inheritance:r /grant:r "$env:USERNAME:(R,W)".
The interactive prompt is preferred — a release happens a few times a year, and
nothing lands on disk.