{"id":46337029,"url":"https://github.com/abracadabra50/uk-grocery-cli","last_synced_at":"2026-03-04T19:04:45.937Z","repository":{"id":338798060,"uuid":"1158177596","full_name":"abracadabra50/uk-grocery-cli","owner":"abracadabra50","description":"Multi-supermarket grocery automation for UK. Search products, manage baskets, book delivery, checkout across Sainsbury's, Ocado, and more. Built for AI agents.","archived":false,"fork":false,"pushed_at":"2026-02-16T13:22:56.000Z","size":223,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T21:36:11.603Z","etag":null,"topics":["ai-agents","automation","groceries","meal-planning","ocado","sainsburys","shopping","typescript","uk"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abracadabra50.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T23:16:53.000Z","updated_at":"2026-02-16T18:24:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abracadabra50/uk-grocery-cli","commit_stats":null,"previous_names":["abracadabra50/uk-grocery-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/abracadabra50/uk-grocery-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abracadabra50%2Fuk-grocery-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abracadabra50%2Fuk-grocery-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abracadabra50%2Fuk-grocery-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abracadabra50%2Fuk-grocery-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abracadabra50","download_url":"https://codeload.github.com/abracadabra50/uk-grocery-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abracadabra50%2Fuk-grocery-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30090040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T18:31:08.343Z","status":"ssl_error","status_checked_at":"2026-03-04T18:31:07.708Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","groceries","meal-planning","ocado","sainsburys","shopping","typescript","uk"],"created_at":"2026-03-04T19:04:45.301Z","updated_at":"2026-03-04T19:04:45.927Z","avatar_url":"https://github.com/abracadabra50.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n🛒\n\n# UK Grocery CLI\n\n**One CLI that handles grocery shopping at any UK supermarket.**  \nYour AI agent can now search products, manage baskets, book delivery, and checkout across Sainsbury's, Ocado, Tesco, and more.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![Stars](https://img.shields.io/github/stars/abracadabra50/uk-grocery-cli?style=social)](https://github.com/abracadabra50/uk-grocery-cli/stargazers)\n[![npm](https://img.shields.io/npm/v/uk-grocery-cli)](https://www.npmjs.com/package/uk-grocery-cli)\n\n[Quick Start](#quick-start) • [Supported Stores](#supported-supermarkets) • [How It Works](#how-it-works) • [Agent Integration](#agent-integration) • [Smart Shopping](#smart-shopping-features) • [API Reference](#cli-commands)\n\n\u003c/div\u003e\n\n---\n\n## Why\n\nIf you're building AI agents for the agentic era, there's a gap: **UK supermarkets offer zero APIs.**\n\nSainsbury's, Ocado, Tesco, Asda, Morrisons — none of them provide developer APIs. No OAuth, no REST endpoints, no webhooks. If you want your agent to shop for groceries, there's no official way to do it.\n\nBut agents need to eat. Meal planning, auto-reordering, budget optimization — these are perfect agent workflows. The infrastructure just doesn't exist.\n\n**UK Grocery CLI closes that gap.** Reverse-engineered integrations that give your agent a unified command-line interface to every major UK supermarket. Your agent calls `groc search \"milk\"` and it works whether you're shopping at Sainsbury's or Ocado.\n\nBuilt for agent frameworks like [OpenClaw](https://github.com/claw-labs/openclaw), Pi, Claude Desktop MCP. Works with any agent that can shell out to a CLI. Your agent handles the intelligence (meal planning, budget optimization, dietary preferences). The CLI handles the grunt work (authentication, API calls, basket state).\n\n## Supported Supermarkets\n\n- ✅ **Sainsbury's** - UK-wide delivery, full API coverage\n- ✅ **Ocado** - London \u0026 South England, complete integration  \n- 🔜 **Tesco** - Coming soon (API reverse-engineering in progress)\n- 🔜 **Asda** - Planned Q2 2026\n- 🔜 **Morrisons** - Planned Q2 2026\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/abracadabra50/uk-grocery-cli.git\ncd uk-grocery-cli\n\n# Install dependencies\nnpm install\n\n# Install Playwright for authentication\nnpx playwright install chromium\n\n# Optional: Link globally to use 'groc' command anywhere\nnpm link\n```\n\n### First Time Setup\n\n```bash\n# Login to Sainsbury's (saves session to ~/.sainsburys/session.json)\nnpm run groc login --email YOUR_EMAIL --password YOUR_PASSWORD\n\n# Or if installed globally:\ngroc --provider sainsburys login --email YOUR_EMAIL --password YOUR_PASSWORD\n\n# Test it works\nnpm run groc search \"milk\"\n```\n\n### Basic Usage\n\n```bash\n# Search for products\nnpm run groc search \"organic milk\"\n\n# Add to basket\nnpm run groc add 357937 --qty 2\n\n# View basket\nnpm run groc basket\n\n# Book delivery and checkout\nnpm run groc slots\nnpm run groc book \u003cslot-id\u003e\nnpm run groc checkout\n```\n\n### For AI Agents\n\n```bash\n# Agent calls via bash:\ncd /path/to/uk-grocery-cli \u0026\u0026 npm run groc search \"chicken breast\" --json\ncd /path/to/uk-grocery-cli \u0026\u0026 npm run groc add 357937 --qty 2\ncd /path/to/uk-grocery-cli \u0026\u0026 npm run groc basket --json\n```\n\nSee [SKILL.md](SKILL.md) for complete agent integration guide.\n\n## How It Works\n\n**The CLI provides a unified interface:**\n\n```bash\ngroc --provider \u003cstore\u003e \u003ccommand\u003e [options]\n```\n\nSwitch providers with a flag. Commands stay the same.\n\n```bash\ngroc --provider sainsburys search \"milk\"  # Sainsbury's\ngroc --provider ocado search \"milk\"       # Ocado\ngroc --provider tesco search \"milk\"       # Tesco (coming soon)\n```\n\n**Under the hood:**\n\nEach provider implements a common interface:\n\n```typescript\ninterface GroceryProvider {\n  search(query: string): Promise\u003cProduct[]\u003e;\n  getBasket(): Promise\u003cBasket\u003e;\n  addToBasket(id: string, qty: number): Promise\u003cvoid\u003e;\n  getSlots(): Promise\u003cDeliverySlot[]\u003e;\n  checkout(): Promise\u003cOrder\u003e;\n}\n```\n\nThe CLI routes commands to the right provider. Your agent doesn't care which store you're using.\n\n## Agent Integration\n\n### Add as a Skill\n\nYour agent can call the CLI directly:\n\n```typescript\n// User: \"Order milk from Sainsbury's\"\n\n// Agent executes:\nawait exec('groc --provider sainsburys search \"milk\" --json');\nawait exec('groc --provider sainsburys add 357937 --qty 2');\nawait exec('groc --provider sainsburys checkout');\n```\n\n### Example Agent Workflow\n\n**User:** \"Plan meals for this week, £60 budget, prefer organic\"\n\n**Agent logic:**\n1. Plans 7 meals based on preferences\n2. Extracts ingredient list  \n3. For each ingredient:\n   - Searches product: `groc search \"strawberries\"`\n   - Decides organic vs conventional (see [Smart Shopping](#smart-shopping-features))\n   - Adds to basket: `groc add \u003cid\u003e --qty \u003cn\u003e`\n4. Books delivery slot\n5. Checks out\n\n**The CLI handles:** Product search, basket operations, checkout  \n**Your agent handles:** Meal planning, organic decisions, budget optimization\n\nSee [`AGENTS.md`](./AGENTS.md) for complete integration guide.\n\n## Smart Shopping Features\n\nThe CLI provides product data. Your agent makes intelligent decisions.\n\n### Organic Prioritization (Dirty Dozen)\n\n```typescript\n// Agent logic (not CLI)\nconst dirtyDozen = ['strawberries', 'spinach', 'kale', 'apples'];\nconst cleanFifteen = ['avocados', 'sweetcorn', 'pineapple'];\n\nif (dirtyDozen.includes(product)) {\n  // High pesticide residue - always buy organic\n  await search('organic strawberries');\n} else if (cleanFifteen.includes(product)) {\n  // Low pesticide - save money with conventional\n  await search('strawberries');\n}\n```\n\n### Budget Optimization\n\n```typescript\n// Compare organic vs conventional pricing\nconst organic = await search('organic milk');\nconst conventional = await search('milk');\nconst premium = (organic.price - conventional.price) / conventional.price;\n\nif (premium \u003c 0.20 \u0026\u0026 budget.hasRoom()) {\n  return organic;  // Less than 20% more - worth it\n} else {\n  return conventional;  // Save money\n}\n```\n\n### Multi-Store Price Comparison\n\n```typescript\n// Agent can shop across stores\nconst sainsburys = await groc('--provider sainsburys search \"milk\"');\nconst ocado = await groc('--provider ocado search \"milk\"');\n\n// Choose based on price, delivery area, or availability\n```\n\nSee [`docs/SMART-SHOPPING.md`](./docs/SMART-SHOPPING.md) for complete guide on organic decisions, seasonal produce, waste prevention, and meal optimization.\n\n## CLI Commands\n\n### Provider Selection\n\n```bash\n-p, --provider \u003cname\u003e    Choose: sainsburys, ocado, tesco\ngroc providers           List available providers\n```\n\n### Product Search\n\n```bash\ngroc search \u003cquery\u003e      Search products\n--json                   Output JSON for parsing\n```\n\nExample output:\n```json\n[\n  {\n    \"id\": \"357937\",\n    \"name\": \"Sainsbury's Organic Semi-Skimmed Milk 2L\",\n    \"price\": 1.65,\n    \"unit\": \"2L\",\n    \"available\": true\n  }\n]\n```\n\n### Basket Management\n\n```bash\ngroc basket              View current basket\ngroc add \u003cid\u003e --qty \u003cn\u003e  Add item to basket\ngroc remove \u003citem-id\u003e    Remove item from basket\ngroc clear               Empty basket\n```\n\n### Delivery \u0026 Checkout\n\n```bash\ngroc slots               View available delivery slots\ngroc book \u003cslot-id\u003e      Reserve delivery slot\ngroc checkout            Place order\n--dry-run                Preview order without placing\n```\n\n### Authentication\n\n```bash\ngroc login --email \u003cemail\u003e --password \u003cpass\u003e\ngroc logout\ngroc status              Check login status\n```\n\n## Payment \u0026 Security\n\nUses your existing supermarket account and saved payment method.\n\n**How it works:**\n1. Login once via browser automation (Playwright)\n2. Session cookies saved locally (`~/.sainsburys/session.json`)\n3. CLI uses cookies for API authentication\n4. Checkout uses your saved card from account settings\n5. No card details ever touch the CLI\n\n**Security:**\n- Session files git-ignored by default\n- Cookies stored locally only\n- No card data handled by CLI\n- PCI compliant (payment stays in supermarket systems)\n- Same security model as using the website\n\n**Setup payment method:**\n1. Visit sainsburys.co.uk/myaccount (or your provider)\n2. Add payment method in account settings\n3. Set default card\n4. CLI will use it when checking out\n\n## Architecture\n\n### Provider Abstraction\n\n```typescript\ninterface GroceryProvider {\n  search(query: string): Promise\u003cProduct[]\u003e;\n  getBasket(): Promise\u003cBasket\u003e;\n  addToBasket(id: string, qty: number): Promise\u003cvoid\u003e;\n  removeFromBasket(itemId: string): Promise\u003cvoid\u003e;\n  getSlots(): Promise\u003cDeliverySlot[]\u003e;\n  bookSlot(slotId: string): Promise\u003cvoid\u003e;\n  checkout(): Promise\u003cOrder\u003e;\n}\n```\n\nEach provider implements this interface. Adding new supermarkets is plug-and-play.\n\n### Clean REST APIs\n\nBoth Sainsbury's and Ocado use simple REST:\n\n```\nSainsbury's:\n  GET  /groceries-api/gol-services/product/v1/product?filter[keyword]=milk\n  POST /groceries-api/gol-services/basket/v2/basket/items\n  \nOcado:\n  GET  /api/search/v1/products?query=milk\n  POST /api/trolley/v1/items\n```\n\nSee [`API-REFERENCE.md`](./API-REFERENCE.md) for complete endpoint documentation.\n\n## Use Cases\n\n### Meal Planning Automation\nAgent plans meals → generates shopping list → searches products → orders → delivers\n\n### Auto-Reordering\nAgent tracks consumption → monitors inventory → reorders essentials when low\n\n### Budget Management\nAgent tracks spending → suggests cheaper alternatives → keeps you on budget\n\n### Dietary Preferences\nAgent filters by halal/kosher/vegan/gluten-free → excludes restricted items\n\n### Health Optimization  \nAgent prioritizes organic for Dirty Dozen → saves money on Clean Fifteen\n\nSee [`docs/SMART-SHOPPING.md`](./docs/SMART-SHOPPING.md) for implementation examples.\n\n## Project Structure\n\n```\nuk-grocery-cli/\n├── src/\n│   ├── providers/\n│   │   ├── types.ts           # Common interface\n│   │   ├── sainsburys.ts      # Sainsbury's implementation\n│   │   ├── ocado.ts           # Ocado implementation\n│   │   └── index.ts           # Provider factory\n│   ├── auth/\n│   │   └── login.ts           # Playwright authentication\n│   └── cli.ts                 # Multi-provider CLI\n├── docs/\n│   ├── SMART-SHOPPING.md      # Agent intelligence guide\n│   └── API-REFERENCE.md       # Complete API documentation\n├── SKILL.md                   # OpenClaw skills format\n├── AGENTS.md                  # Agent integration guide\n└── README.md                  # This file\n```\n\n## Known Limitations\n\n### Authentication\n- **2FA Required**: Sainsbury's requires SMS verification on every login\n- **Session Duration**: Sessions expire after ~7 days (re-login needed)\n\n### API Coverage\n- ✅ **Working**: Search, basket management, product data\n- ⚠️ **Experimental**: Delivery slots (endpoint partially documented)\n- ⚠️ **Experimental**: Checkout flow (needs real-world testing)\n- 🔜 **Coming**: Order tracking, substitutions, favourites\n\nSome endpoints are still being reverse-engineered. Contributions welcome.\n\n## Development\n\n```bash\ngit clone https://github.com/abracadabra50/uk-grocery-cli\ncd uk-grocery-cli\nnpm install\nnpm run build\nnpm run groc -- --provider sainsburys search \"milk\"\n```\n\n## Contributing\n\nContributions welcome!\n\n**Want to add:**\n- More supermarkets (Tesco, Asda, Morrisons)\n- Missing API endpoints (slots, checkout improvements)\n- Smart shopping algorithms\n- Nutritional data integration\n- Meal planning templates\n\nOpen an issue or PR.\n\n## Roadmap\n\n### v2.0 (Current)\n- ✅ Multi-provider architecture\n- ✅ Sainsbury's provider (full coverage)\n- ✅ Ocado provider (full coverage)\n- ✅ Smart shopping guide\n\n### v2.1 (Q1 2026)\n- 🔜 Tesco provider\n- 🔜 Delivery slot optimization\n- 🔜 Price history tracking\n- 🔜 Substitution handling\n\n### v2.2 (Q2 2026)\n- 🔜 Asda \u0026 Morrisons providers\n- 🔜 Nutritional data API\n- 🔜 Recipe database integration\n\n### v3.0 (Q3 2026)\n- 🔜 MCP server implementation for Claude Desktop\n- 🔜 Model Context Protocol integration\n- 🔜 Native Claude app support\n\n## License\n\nMIT - Free to use, modify, distribute.\n\n## Legal \u0026 Usage\n\n**Personal Use Only**\n\nThis tool is designed for personal grocery shopping automation and agent development. It is not intended for:\n- Commercial scraping or data collection\n- Reselling grocery data\n- Automated bulk ordering for businesses\n- Any use that violates supermarket terms of service\n\n**How It Works**\n\nThe CLI uses your personal supermarket account credentials. You authenticate once (just like logging into the website), and the CLI uses your session to place orders on your behalf. This is functionally equivalent to using the website, just via command line instead of a browser.\n\n**Your Responsibility**\n\nBy using this tool, you agree to:\n- Use it only for your personal grocery shopping\n- Comply with each supermarket's terms of service\n- Not abuse rate limits or cause disruption\n- Not use it for commercial purposes\n\n**No Affiliation**\n\nThis project is not affiliated with, endorsed by, or sponsored by Sainsbury's, Ocado, Tesco, Asda, Morrisons, or any other supermarket chain. All trademarks are property of their respective owners.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built by [zish](https://github.com/abracadabra50)**\n\nInspired by [Shellfish](https://github.com/abracadabra50/shellfish) - Agentic commerce for Shopify\n\n**Enable your AI agent to handle grocery shopping. Focus on cooking, not ordering. 🛒**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabracadabra50%2Fuk-grocery-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabracadabra50%2Fuk-grocery-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabracadabra50%2Fuk-grocery-cli/lists"}