Skip to main content

woolies-nz-cli

Unofficial command-line tool for Woolworths New Zealand. Search products, manage your trolley, and script your shopping — all from the terminal.

$ woolies login
Email: you@example.com
Password: ********
✓ Logged in as you@example.com

$ woolies search milk --limit 3
Found 3 products (3 groups):

Anchor Uht Milk Blue Top
  - Size: 1L (ctn) | Price: $3.40 (Special, was $3.79)
    SKU: 269671 | In Stock | Category: Fridge & Deli
    Unit: Each ($3.40 per 1L)
...

$ woolies cart add 269671 2
✓ Added 2x (SKU: 269671) to cart

What this is / isn't

  • ✅ For: NZ shoppers who want CLI / scriptable access to Woolworths NZ.
  • ✅ For: building your own automations on top (rotating shopping lists, price alerts, etc.).
  • ❌ Not: an official Woolworths product. Hobby-grade, maintained by one person.
  • ❌ Not: for AU Woolworths or the rebranded Countdown UI — woolworths.co.nz only.
  • ❌ Not: for redistributing scraped Woolworths product data as a dataset.

Disclaimer: This tool is not affiliated with, endorsed by, or connected to Woolworths Limited or Woolworths New Zealand Limited. Use of this tool may violate Woolworths' Terms of Service. Use at your own risk. The author accepts no liability for account suspensions, rate limiting, blocked access, or any other consequence of using this software. Consider using a dedicated Woolworths account for automated access.

Stability: it's janky and that's okay

There is no official Woolworths NZ API. This tool works by:

  • Driving a real browser to log in (selectors against Woolworths' login page).
  • Calling Woolworths' internal /api/v1/* endpoints with the resulting cookies (request shapes that Woolworths can change at any time).
  • Spoofing browser fingerprints to get past Akamai's bot detection.

Any of this can break with no warning — a selector tweak, a payload-shape change, a fingerprint heuristic update. When that happens, this tool will fail with confusing errors until someone (you? me? a passing stranger?) digs in and fixes it.

There are no uptime promises and no fix-time SLAs. I'll patch breakage when I can be bothered and have time. If that's not soon enough for you, PRs are very welcome — see CONTRIBUTING.md. A one-line selector fix is a real contribution and will get merged fast.

Install

pipx install woolies-nz-cli
# or with uv:
uv tool install woolies-nz-cli

Don't have pipx or uv? See pipx install or uv install, or use plain pip install into a venv.

Requires Python 3.11+. Tested on macOS (Apple Silicon) and Linux. Windows untested.

First-run heads-up

Your first command that needs a browser (typically woolies login) downloads the Camoufox browser (~300MB, ~10–60s). After that, the browser is cached in ~/Library/Caches/camoufox (macOS) or ~/.cache/camoufox (Linux) and reused across runs.

Setup

woolies login

That's it. It prompts for your Woolworths NZ email + password, runs the browser login (~25s), saves the session cookies, and stores credentials at ~/.config/woolies-nz-cli/config.toml (mode 0600).

Verify with:

woolies doctor

You'll re-run woolies login only when Woolworths invalidates your session (typically every few weeks).

Alternative: environment variables

For unattended environments (CI, Docker, headless servers, scheduled jobs), skip woolies login and set:

export WOOLWORTHS_USERNAME="you@example.com"
export WOOLWORTHS_PASSWORD="your-password"

Env vars override anything in config.toml.

Alternative: password_command

If you keep secrets in 1Password / pass / Bitwarden / etc., add to ~/.config/woolies-nz-cli/config.toml:

username = "you@example.com"
password_command = "op read op://Personal/Woolies/password"

The shell command is executed and its stdout is used as the password.

Usage

woolies search "milk"
woolies search "milk" --limit 20
woolies search "milk" --size 2L
woolies search "bread" --json

Output groups variants of the same product, shows brand / size / unit price / availability / category, and highlights dual-priced loose produce.

Search → cart (typical workflow)

$ woolies search "milk" --limit 3
...
    SKU: 269671 | In Stock | Category: Fridge & Deli
...

$ woolies cart add 269671 2
✓ Added 2x (SKU: 269671) to cart

The SKU from search output is what cart add takes.

Cart

woolies cart list
woolies cart add <sku> <quantity>
woolies cart update <sku> <quantity>
woolies cart remove <sku>
woolies cart clear --force

Add --json to any command for structured output suitable for scripts.

Dual-priced loose produce

Some loose produce (carrots, onions, apples) supports both --unit Each and --unit Kilogram:

woolies cart add 135344 3 --unit Each       # 3 carrots
woolies cart add 135344 0.45 --unit Kilogram # 450g of carrots

Search results indicate which products support dual pricing.

Inspect (debug)

Launches a visible browser with your active session. The browser stays open until Ctrl-C — useful for inspecting selectors, watching API calls in DevTools, or testing the login flow when something breaks:

woolies inspect

Logout

woolies logout

Removes saved credentials and cookies. Next woolies login will start fresh.

Privacy

  • Your credentials and cookies stay on your machine. Nothing is uploaded to anywhere except woolworths.co.nz itself, with the same data your browser would send when you log in to their website.
  • Credentials are stored at ~/.config/woolies-nz-cli/config.toml with file mode 0600 (owner read/write only).
  • Cookies are stored at ~/.local/state/woolies-nz-cli/cookies.json.
  • No telemetry, no analytics, no phone-home. The source is MIT-licensed — read it, audit it, fork it.

How it works

  • httpx for fast API calls (~1s per request) using cached cookies.
  • Camoufox (Firefox-based anti-detect browser) only for initial login or cookie refresh (~25s).
  • Sessions persist until Woolworths invalidates them (typically a few weeks).

File locations

What Where
Credentials ~/.config/woolies-nz-cli/config.toml (or $XDG_CONFIG_HOME/woolies-nz-cli/), mode 0600
Cookies + screenshots ~/.local/state/woolies-nz-cli/ (or $XDG_STATE_HOME/woolies-nz-cli/)
Camoufox browser ~/Library/Caches/camoufox (macOS) / ~/.cache/camoufox (Linux)

Optional: HTTP proxy for the browser

export WOOLIES_PROXY="http://user:pass@host:port"

Routes the Camoufox browser through a proxy. Useful for residential proxies if Akamai starts blocking your IP.

Troubleshooting

Run woolies doctor first — it diagnoses creds, paths, browser, and DNS in one go.

Symptom Likely cause Fix
Credentials not found Haven't logged in Run woolies login
Login failed: invalid credentials Wrong username/password Run woolies login again
Could not find email input field Woolworths changed login UI See CONTRIBUTING.md, or open an issue
Cannot process request API format changed See CONTRIBUTING.md
Every run is slow (~25s) Cookies not persisting Check ~/.local/state/woolies-nz-cli/ is writable

To force a fresh login:

woolies logout && woolies login

To report a bug or request a feature: GitHub issues.

Contributing

PRs welcome — see CONTRIBUTING.md. Selector and API-format fixes are especially valuable; even a one-line fix when Woolworths shifts something is a real contribution.

License

MIT © Jake McInteer

The MIT license covers the code only — it does not grant rights to redistribute scraped Woolworths product data as a dataset.

Metadata

Release files for woolies-nz-cli 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for woolies-nz-cli 0.1.1
File Size Uploaded Provenance Actions
woolies_nz_cli-0.1.1.tar.gz 21.1 kB Without provenance Details for woolies_nz_cli-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for woolies-nz-cli 0.1.1
File Interpreter ABI Platform Actions
woolies_nz_cli-0.1.1-py3-none-any.whl Python 3 none any Details for woolies_nz_cli-0.1.1-py3-none-any.whl

Total release size: 43.4 kB

Release files / woolies_nz_cli-0.1.1.tar.gz

Download URL woolies_nz_cli-0.1.1.tar.gz
Size 21.1 kB
Tags Source
SHA-256 checksum
How to use checksums
50592c52119547c2bf94210f2313adab3f12407469177b6cde7913cb4ca42158
BLAKE2b-256 checksum
How to use checksums
af3bda1208e8f7bb1d19516297732f4ff75e8a8673ec792326e1221d15644127
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / woolies_nz_cli-0.1.1-py3-none-any.whl

Download URL woolies_nz_cli-0.1.1-py3-none-any.whl
Size 22.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a0231a89e071e17ef5cf0b57b76779ac23a8779cf241db5dbbe4de66502e5285
BLAKE2b-256 checksum
How to use checksums
ca3fa4c4eed8db4e16b849a3943bb16ff241363cb410ce324947597da7b3f35d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for woolies-nz-cli 0.1.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page