sainsburys-cli

Build a Sainsbury's Groceries basket from a plain-text shopping list, from the command line.

It talks directly to Sainsbury's internal Groceries API and authenticates by borrowing the session from a browser you're already logged in to — so there's no password to store and no browser being driven around. It never places an order; it only fills the basket, ready for you to review and check out yourself.

⚠️ This uses an undocumented, unofficial API. It can break if Sainsbury's changes their site, and it's for personal use with your own account only.

Install

cd ~/code/sainsburys_cli
python3 -m venv .venv
.venv/bin/pip install -e .

This gives you a sainsburys command (at .venv/bin/sainsburys).

First-time setup: log in

1. Open your normal browser and log in at https://www.sainsburys.co.uk.

2. Leave that session logged in.

3. Check it works:

   .venv/bin/sainsburys whoami
   

   You should see your name/email. The CLI reads the Sainsbury's cookies from your browser automatically. If you have several browsers, point it at one:

   .venv/bin/sainsburys --browser firefox whoami
   

When your session later expires, just reload sainsburys.co.uk in the browser and run any command with --refresh.

Build a basket from a list

Write a shopping list, one item per line:

# weekly shop
2 x semi skimmed milk
free range eggs x2
wholemeal bread
600g chicken breast
bananas

Quantities can go at the start (2 x milk, 3 bananas) or end (milk x2). Blank lines and # comments are ignored.

Preview first (nothing is added):

.venv/bin/sainsburys add-list shopping.txt

You'll get a per-line report: ✓ confident matches, ? low-confidence or out-of-stock (with alternatives shown), and ✗ no-match. When it looks right, commit:

.venv/bin/sainsburys add-list shopping.txt --commit

Only confident, in-stock matches are added; anything flagged for review is left for you to add manually (e.g. with search + add). Then open the basket on the website to review and check out.

Other commands

.venv/bin/sainsburys search "oat milk"        # find products + their ids
.venv/bin/sainsburys add 7977681 --qty 2      # add one product by id
.venv/bin/sainsburys basket                   # show the current basket (with item ids)
.venv/bin/sainsburys remove "oat milk"        # remove an item by name (or [item ...] id)

remove matches on the product name; if more than one basket item matches equally (e.g. remove "milk" with two milks) it lists them and does nothing, so you can re-run with the specific [item ...] id or --all.

Add --json to any command for machine-readable output (handy when Claude is driving it).

Using it with Claude Desktop

Claude Desktop drives this through a bundled MCP server (sainsburys-mcp) so your partner can just chat — "add milk, eggs and bread to my Sainsbury's basket" — with no terminal. See docs/CLAUDE_DESKTOP.md for the one-time setup. (In Claude Code, use the CLI directly as below.)

Using it with Claude (CLI)

You don't have to pre-format anything. Paste a messy list into Claude — prose, a copied spreadsheet, mixed units ("6 pints semi-skimmed, a dozen eggs, loaf of wholemeal") — and ask it to build the basket. Claude interprets the list itself, then uses search --json to find each product and add to put it in the basket, stopping to ask you whenever an item is ambiguous (which size? which brand? the usual one's out of stock — swap it?). It confirms the basket at the end; you review and check out on the website. See CLAUDE.md for the exact protocol Claude follows.

If reading browser cookies doesn't work

Some locked-down work machines (or Chrome on recent Windows) block reading the cookie store. Fallback: copy the request cookies from your browser's dev tools (Network tab → any groceries-api request → Cookie header, and the wcauthtoken request header) and set them as env vars:

set -x SAINSBURYS_COOKIE "WC_AUTHENTICATION_123=...; JSESSIONID=..."
set -x SAINSBURYS_WCAUTHTOKEN "..."

Running the tests

.venv/bin/pip install pytest
.venv/bin/python -m pytest

The tests cover the list-parsing and product-matching logic (which run offline); the API calls themselves need a live logged-in session to exercise.