Mercadona CLI is an unofficial, agent-friendly command-line tool for tienda.mercadona.es. It lets you search the catalog, read prices, build a cart, and run the full checkout flow — all from your terminal or from an automated agent. It ships as a single static Go binary with no runtime dependencies, and every command supportsDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/ivorpad/mercadona-cli/llms.txt
Use this file to discover all available pages before exploring further.
--json output so scripts and AI agents can consume the data without screen-scraping. Mercadona has no public API; this CLI talks to the same HTTP endpoints the website uses.
Key capabilities
Search via Algolia
Full-text product search powered by Algolia — no login required. The CLI auto-discovers and caches the Algolia app-id and key from the live SPA bundle, surviving credential rotations automatically.
Batch pricing
Price a whole shopping list written in plain words in a single request.
batch resolves each term to its top hit and returns the id, name, price, and reference price (€/kg or €/L).Cart management
Add, set, or clear cart lines.
cart set-many applies an entire basket of <id> <qty> lines in one write, pricing it first so the spending guard can refuse before anything changes.Checkout flow
Open a checkout, list delivery addresses, browse available delivery slots, assign an address and slot, and submit the order — all scriptable and idempotent up to the final
checkout submit.Spending guard
Cap how much any cart or checkout operation can ever spend. Pass
--max <eur> per command, set MERCADONA_MAX_EUR in your environment, or write [limits] max_eur in config.toml. checkout submit fails closed: if the total cannot be read and a cap is set, it refuses rather than spending blind.JSON output for agents
Every command emits structured data to stdout and logs or errors to stderr, with exit code
1 on failure. Pipe --json output straight into jq, an LLM tool call, or a CI step.Architecture overview
The CLI is designed around three layers, ordered by how sensitive they are to the IP address they run from. Layer 1 — Search (Algolia). Product search does not touch Mercadona’s infrastructure at all. Algolia is not behind Mercadona’s Akamai CDN, so it works from any IP including CI runners, serverless functions, and developer laptops. The Algolia app-id and index name are public values baked into the SPA bundle; they rotate occasionally. Rather than hardcoding them, the CLI ships a last-known-good fallback and, on any stale-credential signal (DNS failure, 401, 403, or 404), re-discovers the current values from the live SPA bundle, caches them in~/.mercadona/algolia.json, and retries transparently. No manual intervention is needed when credentials rotate.
Layer 2 — Catalog reads (/api/...). Product detail, categories, and pricing endpoints are fronted by Akamai but are served to anonymous GET requests at human-paced volume. The CLI sends web-app-like headers to stay in monitor mode and avoid triggering bot-detection challenges.
Layer 3 — Auth, cart, and checkout. Authenticated operations are the only IP-sensitive layer. They should be run from a residential IP — your own machine or a box on your home network — rather than a flagged datacenter or serverless egress address. You log in once via a browser (to solve the reCAPTCHA or Google OAuth flow), export a HAR file, and then import-har seeds the durable refresh_token into ~/.mercadona/config.toml. Every subsequent 401 token_not_valid triggers an automatic headless refresh and retry — no browser, no captcha, unattended.
Mercadona CLI is an unofficial project and is not affiliated with or endorsed by Mercadona. It uses the same HTTP endpoints as the website. Use it at a sane request rate, bring your own credentials, and comply with Mercadona’s terms of service.
Where to go next
Installation
Install via npm, curl, manual binary download, or build from Go source.
Quickstart
Go from zero to a priced shopping basket in five minutes.
Authentication
Seed a refresh token for headless, unattended authenticated operations.
Command Reference
Full syntax, flags, and examples for every command.