Skip to main content

Documentation 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.

The repository ships a Claude Code skill called mercadona-shop, found at .claude/skills/mercadona-shop/. Install it in your Claude Code skills directory and it drives the full grocery shopping workflow end to end — resolving natural-language requests into real priced products, filling the cart, preparing delivery checkout, and placing the order — with two mandatory safety gates that require your explicit approval before any irreversible action.
Build the mercadona binary and make sure it is on your PATH before installing the skill. The skill calls the CLI directly and will fail if the binary is missing.

​
Installation

# Option 1: symlink (stays in sync with the repo automatically)
ln -s /path/to/mercadona-cli/.claude/skills/mercadona-shop ~/.claude/skills/mercadona-shop

# Option 2: copy
cp -r /path/to/mercadona-cli/.claude/skills/mercadona-shop ~/.claude/skills/
Confirm the binary is available first: 
mercadona version

​
What the skill does

The mercadona-shop skill converts natural-language grocery requests into real Mercadona orders. It understands both Spanish and English phrasings:
  • Spanish: “hazme la compra”, “haz la compra de Mercadona”, “compra en Mercadona”, “añade leche al carrito”, “¿cuánto cuesta esta lista?”, “pídeme estos productos”
  • English: “do my Mercadona shop”, “price this grocery list at Mercadona”, “fill my Mercadona cart”, “order these groceries”
  • Recipe mode: “quiero hacer una paella para 4”, “ingredientes para una cena para 6” — the skill resolves the full ingredient list, scaling quantities to your headcount, and asks about allergens before pricing anything
The skill also triggers when you paste a grocery list and mention Mercadona, without needing to say “skill” or “CLI” explicitly.

​
The two mandatory safety gates

This skill spends real money on a real account. Two checkpoints are non-negotiable and cannot be skipped. Gate 1 — Confirm before touching the cart. Before the first cart add or cart set call, the skill shows you the full resolved product plan: every list item mapped to the exact product it selected, with ID, name, size, and price. You must explicitly approve this plan. Product matching is fuzzy, so this is where you catch a wrong brand or wrong size — cheap to fix before the cart is touched, annoying to fix after. Gate 2 — Never submit without explicit consent. checkout submit places a paid order and is irreversible. The skill will never add --yes on your behalf to “save a step.” You must clearly say “yes, place it” (or “dale”) for the specific order you are looking at. Any ambiguity → the skill stops and asks. Everything between those two gates — search, batch pricing, cart get, checkout create, checkout slots, set-delivery — is reversible and the skill runs it freely to build toward your approval.

​
The spending cap

On top of the two gates, the skill sets --max <eur> on every cart and checkout command. The cap is drawn from:
  • Your stated budget, if you gave one (“máximo 80€”, “no más de 100”)
  • Otherwise, the agreed plan total from Gate 1 plus a small margin
Any cart or checkout command whose total would exceed --max fails with error: BUDGET EXCEEDED … and a non-zero exit — the agent stops rather than overspending. Treat a budget breach as a stop-and-report signal; the cap only goes up if you explicitly raise your budget.
The cart --max covers only the product subtotal. The checkout --max must also cover the delivery fee (~8.20€). A ~60€ basket needs --max 61 on cart commands and --max 70 on checkout commands. Using the cart cap on checkout submit will wrongly refuse a valid order.

​
Shopping workflow

The skill follows this sequence every time:
1

Scope and clarify

Before pricing anything, the skill checks what it already knows — saved warehouse, authenticated session, budget you just stated — and only asks about the gaps that actually change the basket. For a recipe request it asks headcount and allergens (once, batched into a single question). It never asks for information it already has.
2

Resolve the list to real products

The skill runs batch to translate all terms in a single request, then follows up with targeted mercadona search --limit 5 calls for anything where the top hit looks uncertain. It applies --fresh when you asked for fresh seafood, produce, or meat, dropping the frozen and canned aisles.
printf 'leche entera\nhuevos\nplátano\naceite de oliva\n' | mercadona batch -f -
3

Show the plan and price it — wait for OK (Gate 1)

The skill shows a compact table: each list item → the chosen product ([id] name — size — unit_price) with quantities. It computes the total with mercadona total, never by hand:
printf '5044 1\n60393 1\n85499 1\n16044 1\n' | mercadona total -f -
Every assumption (headcount, brand choice, fresh vs. frozen, a substituted product) is surfaced here so you can veto it. The skill waits for your go-ahead before touching the cart.
4

Fill the cart with one write

After your approval, the skill writes the whole basket in a single set-many call — one GET, all changes applied, one PUT. It annotates every line with a # product name comment so the basket stays human-readable.
mercadona cart set-many -f - --max 61 <<'EOF'
5044    1   # Arroz redondo Hacendado
60393   1   # Gambón grande congelado
85499   1   # Mejillón mediterráneo
16044   1   # Tomate triturado Hacendado
EOF
5

Create checkout and browse delivery slots

Opens a checkout from the cart and fetches available delivery slots for your address.
mercadona checkout create --json --max 70
mercadona checkout slots --address <id> --json
6

Attach delivery address and slot

Reserves your chosen slot. The response carries the final price breakdown: product subtotal + delivery fee = order total.
mercadona checkout set-delivery --checkout <chk> --address <addr> --slot <slot> --max 70
7

Show final total and wait for explicit consent (Gate 2)

The skill shows the complete order: all line items, subtotal, delivery fee, final total, and the chosen delivery slot. Only after you clearly confirm does it proceed.
mercadona checkout submit --checkout <chk> --max 70 --yes
checkout submit places a real, paid order and cannot be undone. The skill requires unambiguous confirmation for every order, every time — there is no “remember my answer” shortcut. A prepared checkout left unsubmitted is harmless; it can sit until you decide, or be abandoned.

Build docs developers (and LLMs) love

Get started for freeTalk to us