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.
uv pip install usps-cli
# or, install from dev:
uv pip install git+https://github.com/iiPythonx/uspsImportant
For UPS packages, USPS-cli only support the 1Z version of UPS tracking numbers right now.
Get the tracking information for a package:
usps track 9400100000000000000000Add a tracking number to your package list:
usps add 9400100000000000000000Remove a tracking number from your package list:
usps remove 9400100000000000000000Show all your current packages:
usps trackAdd 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 PackageRemove the name from a package:
usps name --erase 9400100000000000000000For more details, run usps --help.
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,
- 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.
If you're a USPS web tools representative or something and have a problem with this repository, shoot me an email: ben@iipython.dev.