iiPythonx / USPS
A CLI for tracking packages from USPS (with crude support for UPS packages).
If you have any tracking numbers you're willing to share, please send them to usps@iipython.dev.
Installation
uv pip install usps-cli
# or, install from dev:
uv pip install git+https://github.com/iiPythonx/usps
Usage
[!IMPORTANT]
For UPS packages, USPS-cli only support the1Zversion of UPS tracking numbers right now.
Get the tracking information for a package:
usps track 9400100000000000000000
Add a tracking number to your package list:
usps add 9400100000000000000000
Remove a tracking number from your package list:
usps remove 9400100000000000000000
Show all your current packages:
usps track
Add a name to a package:
$ usps name 9400100000000000000000 "Amazon Package"
# If you don't specify name, it will prompt for one.
$ usps name 9400100000000000000000
Choose a package name: Amazon Package
Remove the name from a package:
usps name --erase 9400100000000000000000
For more details, run usps --help.
Requirements
[!NOTE]
If you only plan to track UPS packages, you can skip installing a selenium driver.
Since this package uses selenium for challenge solving, you'll need to install a Gecko-based browser and geckodriver.
Feel free to modify the code to use Chromium instead if you prefer it.
If you're on Arch: sudo pacman -S firefox geckodriver,
How it works
- Selenium goes to the USPS tracking website, completing the JS challenge and saving the cookies.
- This client saves that request data to a JSON file for reuse (speeds up the client dramatically).
- Next, requests pulls the page from USPS using our saved cookies and parses it with BeautifulSoup.
- Apply some basic scraping and there you go, a USPS tracking client.
It's worth noting I scrape USPS because their APIs get basically no support, require the creation of business accounts and filling out every piece of information about yourself, and even then you have to request explicit access to the tracking API.
Triggered?
If you're a USPS web tools representative or something and have a problem with this repository, shoot me an email: ben@iipython.dev.
1 maintainer
Metadata
1 maintainer
Release files for usps-cli 0.10.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| usps_cli-0.10.2.tar.gz | 10.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| usps_cli-0.10.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 22.9 kB
Release files / usps_cli-0.10.2.tar.gz
| Download URL | usps_cli-0.10.2.tar.gz |
|---|---|
| Size | 10.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
008ae712b2003e9759dd7c6402b62ecd7922391a0123891383506558e97982ab
|
|
BLAKE2b-256 checksum How to use checksums |
d91a0bc078f0beb38c323d55941dd52673c1d3972b77063635832ee4cc15ed18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 18, 2025.
Transparency logRelease files / usps_cli-0.10.2-py3-none-any.whl
| Download URL | usps_cli-0.10.2-py3-none-any.whl |
|---|---|
| Size | 12.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8408a3131a537c56b715f27c038783dcdac70af914256dbc1d671a59f62dbeac
|
|
BLAKE2b-256 checksum How to use checksums |
b11f741d73b0f149f3dcd27cac60e57f98b26efd655c359fa9cb7bcc85ea19b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 18, 2025.
Transparency log
