mercadona-cli-shopping

Mercadona CLI Shopping

Skill by ara.so — Devtools Skills collection.

Overview

mercadona-cli is an unofficial, agent-friendly command-line interface for Spain's Mercadona supermarket (tienda.mercadona.es). It provides structured access to the catalog, pricing, cart management, and checkout flow through a single Go binary with no runtime dependencies.

Key capabilities:

• Search products by name with full-text search
• Get real-time prices and product details (per warehouse)
• Build and manage shopping carts programmatically
• Complete checkout flow (with authentication)
• Structured JSON output for automation
• Batch operations (price many items in one request)
• Budget guards to prevent overspending

Important: This is unofficial and uses the same HTTP endpoints as the website. Bring your own Mercadona credentials and use at a reasonable request rate.

Installation

Via npm (recommended)

npm install -g @ivorpad/mercadona
# Or run without installing:
npx @ivorpad/mercadona search queso

Via curl (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/ivorpad/mercadona-cli/main/install.sh | sh

From source (Go 1.26+)

git clone https://github.com/ivorpad/mercadona-cli.git
cd mercadona-cli
go build -o mercadona ./cmd/mercadona

Configuration

Set warehouse location (required for accurate pricing)

Product IDs and prices are warehouse-specific. Set your warehouse from your postal code:

mercadona set-postal 28022
# Resolves to warehouse (e.g., mad1) and saves as default

This creates ~/.mercadona/config.toml:

[defaults]
warehouse = "mad1"
postal_code = "28022"

Authentication (for cart/checkout operations)

The preferred method is to import a HAR file from your browser session:

# 1. Log in to tienda.mercadona.es in your browser (email or Google)
# 2. Open DevTools → Network tab
# 3. Export HAR (⤓ "Export HAR...")
# 4. Import it:
mercadona import-har --file tienda.mercadona.es.har

# Verify authentication:
mercadona whoami

This extracts the refresh_token (which auto-renews headlessly forever) and saves it to config:

[auth]
refresh_token = "your_refresh_token_here"

Alternative one-off method (expires after ~6 weeks):

# Copy any authenticated request as cURL from DevTools
mercadona import-curl --file request.txt

Budget limits (agent safety)

Prevent overspending by setting a maximum budget:

[limits]
max_eur = 100  # Refuse any cart/checkout over 100€

Or use flags/env vars:

mercadona cart add 51110 2 --max 50
export MERCADONA_MAX_EUR=100

Core Commands (No Authentication Required)

Search products

# Basic search
mercadona search queso

# Limit results
mercadona search queso --limit 5

# JSON output for automation
mercadona search mayonesa --json --limit 3

Example JSON output:

{
  "results": [
    {
      "id": "13406",
      "display_name": "Mayonesa Hacendado",
      "price": 1.20,
      "reference_price": 2.400,
      "reference_format": "€/L"
    }
  ]
}

Get fresh items only (skip frozen/canned)

mercadona search mejillon --fresh --limit 1
# Returns fresh seafood instead of canned mussels

Batch search (multiple terms in one request)

# From a file
cat lista.txt
queso
carne
mayonesa

mercadona batch -f lista.txt

# From stdin
printf 'queso\ncarne\nmayonesa\n' | mercadona batch -f -

Output:

• queso    → [51110] Queso rallado mozzarella pizza-Roma Hacendado — 1.60€ (8.000€/kg)
• carne    → [34157] Carne de pimiento choricero Hacendado — 1.55€ (11.072€/kg)
• mayonesa → [13406] Mayonesa Hacendado — 1.20€ (2.400€/L)

Product details

mercadona product 13406
# Returns: name, price, reference_price, nutrition info (when available)

mercadona product 13406 --json

Browse categories

# List all categories
mercadona categories

# Get products in a specific category
mercadona categories --id 118 --json  # 118 = Rice category

Price a shopping basket

Create a basket file with <product_id> <quantity> format:

# paella.txt - comments are allowed
5044  1     # Arroz redondo Hacendado
60393 1     # Gambón grande congelado
85499 1     # Mejillón mediterráneo
16044 1     # Tomate triturado Hacendado
4740  0.5   # Aceite de oliva virgen extra

Price it:

mercadona total -f paella.txt
# Output shows each line item and total in euros

mercadona total -f paella.txt --json
# Returns: {"lines": [...], "total": 1603, "count": 5, "complete": true}

Cart & Checkout Commands (Authentication Required)

Verify authentication

mercadona whoami
# Output: "ok — customer id=..."

Get current cart

mercadona cart get
mercadona cart get --json

Add items to cart

# Add 2 units of product 51110 (adds to existing quantity)
mercadona cart add 51110 2

# With budget guard
mercadona cart add 51110 2 --max 80

Set absolute quantity

# Set quantity to exactly 3 (overwrites existing)
mercadona cart set 51110 3

# Remove item (set to 0)
mercadona cart set 51110 0

Bulk cart operations

# Load many items from a file (one write operation)
cat basket.txt
51110 2
13406 1
5044 3

mercadona cart set-many -f basket.txt --max 80

# From stdin
printf '51110 2\n13406 1\n' | mercadona cart set-many -f - --max 80

Clear cart

mercadona cart clear

Checkout flow

# 1. Create a checkout
mercadona checkout create --json
# Returns: checkout_id, default_address

# 2. List delivery addresses
mercadona checkout addresses

# 3. Get available delivery slots for an address
mercadona checkout slots --address <address_id>

# 4. Set delivery details
mercadona checkout set-delivery \
  --checkout <checkout_id> \
  --address <address_id> \
  --slot <slot_id>

# 5. Review checkout
mercadona checkout get --checkout <checkout_id>

# 6. Submit order (IRREVERSIBLE - places real order)
mercadona checkout submit \
  --checkout <checkout_id> \
  --max 80 \
  --yes

Common Patterns

Convert plain-text shopping list to IDs

# 1. Create plain text list
cat shopping_list.txt
arroz redondo hacendado
gambón grande congelado
tomate triturado hacendado

# 2. Get product IDs and prices
mercadona batch -f shopping_list.txt --json > products.json

# 3. Parse JSON to create basket file (use jq or your language)
jq -r '.results[] | "\(.id) 1"' products.json > basket.txt

# 4. Price it
mercadona total -f basket.txt

Track price changes over time

#!/bin/bash
# price_tracker.sh - Track specific products daily

PRODUCTS="51110 13406 5044"
DATE=$(date +%Y-%m-%d)

for id in $PRODUCTS; do
  mercadona product $id --json | \
    jq -r "\"$DATE,\(.id),\(.display_name),\(.price)\"" \
    >> price_history.csv
done

Find best value in a category (sort by €/kg)

# Get rice category (id=118), extract reference_price, sort
mercadona categories --id 118 --json | \
  jq -r '.products[] | [.reference_price, .display_name, .id] | @tsv' | \
  sort -n | \
  head -10

Automated weekly order (agent-safe)

#!/bin/bash
# weekly_order.sh - Place recurring order with safety checks

export MERCADONA_MAX_EUR=100

# Load standard basket
mercadona cart set-many -f weekly_basket.txt --max 100 || exit 1

# Create checkout
CHECKOUT=$(mercadona checkout create --json | jq -r '.checkout_id')

# Use saved address and preferred slot
mercadona checkout set-delivery \
  --checkout $CHECKOUT \
  --address $ADDRESS_ID \
  --slot $SLOT_ID

# Review total before submitting
TOTAL=$(mercadona checkout get --checkout $CHECKOUT --json | jq -r '.total')
echo "Order total: $TOTAL"

# Submit (requires --yes flag)
mercadona checkout submit --checkout $CHECKOUT --max 100 --yes

Global Flags

These work with any command and can be placed anywhere on the command line:

--wh mad1              # Override warehouse (default: from config or mad1)
--lang es              # Language code (default: es)
--json                 # Output structured JSON instead of human-readable text
--max 80               # Budget cap in euros (for cart/checkout commands)

Environment Variables

MERCADONA_TOKEN          # Bearer token (access token)
MERCADONA_COOKIE         # Session cookie
MERCADONA_CUSTOMER       # Customer ID
MERCADONA_MAX_EUR        # Budget limit in euros
MERCADONA_REFRESH_TOKEN  # Refresh token (for auto-renewal)

Precedence: flag > env var > config file

Troubleshooting

"401 token_not_valid" error

Your access token expired. Re-import authentication:

mercadona import-har --file fresh_export.har
# Or if using curl method:
mercadona import-curl --file fresh_request.txt

Wrong warehouse / prices don't match website

Set correct warehouse for your postal code:

mercadona set-postal YOUR_POSTAL_CODE

Budget exceeded on cart operation

# Error: BUDGET EXCEEDED (exit 1)
# Solution: Increase limit or reduce quantities
mercadona cart add 10379 99 --max 100  # Increase from 50 to 100

Batch search returns no results for a term

The term might be too vague. Try more specific queries:

mercadona search queso --json  # Too generic, many results
mercadona search "queso manchego curado" --json  # More specific

Can't complete checkout

1. Verify authentication: mercadona whoami
2. Check cart has items: mercadona cart get
3. Ensure warehouse matches delivery address postal code
4. Verify address exists: mercadona checkout addresses
5. Check slots available: mercadona checkout slots --address <id>

Output Parsing

All commands send:

• Data to stdout (JSON with --json or human-readable text)
• Logs/errors to stderr
• Exit code 1 on error, 0 on success

This makes the CLI pipe-friendly for automation:

# Example: Get cheapest item from search results
mercadona search leche --json | \
  jq -r '.results | sort_by(.price) | .[0] | "\(.id) \(.display_name) — \(.price)€"'

Security Notes

• Never hardcode credentials — use import-har to extract tokens or set env vars
• Refresh tokens are durable — they auto-renew indefinitely (no browser/captcha needed)
• Access tokens expire after ~6 weeks — CLI auto-refreshes them when using refresh_token
• Config file is mode 0600 — only readable by owner
• Budget guards fail closed — if total can't be read, submit refuses to proceed

Real-World Agent Examples

Agent builds shopping list from recipe

# User: "I need ingredients for paella for 4 people"
# Agent logic:
mercadona batch -f - --json <<EOF
arroz bomba
azafrán
gambón
mejillón
pollo troceado
pimiento rojo
tomate
EOF

# Parse JSON results, multiply quantities by 4 servings
# Create basket.txt with IDs and quantities
# Price it: mercadona total -f basket.txt

Agent finds allergen-free alternatives

# User: "Find gluten-free bread alternatives"
mercadona search "pan sin gluten" --json --limit 10

# Agent parses results, checks product details for allergen info
mercadona product <each_id> --json | jq '.allergens'

Agent tracks inflation on staples

# Daily cron job storing prices
mercadona batch -f staples.txt --json >> price_log_$(date +%Y-%m).jsonl

# Agent analyzes month-over-month changes