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 Mercadona CLI was designed from the ground up for AI agents and shell scripts. All data goes to stdout, all log messages and errors go to stderr, every command exits with code 0 on success, 1 on error, or 2 on a usage error, and a spending guard actively stops agents before they can overspend. These properties make the CLI safe to pipe, parse, and orchestrate without special wrappers.

​
Output conventions

The CLI follows Unix conventions strictly, so standard tooling like jq, awk, and shell pipelines work without ceremony:
  • Data → stdout, logs/errors → stderr. Your pipeline only sees clean output; error messages never contaminate JSON.
  • Exit code 0 on success, 1 on error, 2 on a usage error. Agents can set -e or check $? without parsing output.
  • --json on any command emits machine-readable JSON. The flag can appear anywhere after the subcommand.
  • Safe to pipe immediately:
mercadona search queso --json | jq '.hits[].id'
The same --json flag works on every subcommand — search, batch, product, categories, cart get, checkout create, and the rest.

​
Spending caps — critical for agents

When an agent drives the CLI, you must cap how much it can ever spend. Any cart or checkout command whose estimated total exceeds the cap is refused with a non-zero exit and an error: line on stderr — the agent stops instead of running up a large order. Pass --max <eur> on every cart and checkout command: 
mercadona cart add 10379 99 --max 50
# → error: BUDGET EXCEEDED (estimated ≈576.00€ > 50.00€ limit): not writing add — raise the cap with --max, MERCADONA_MAX_EUR, or [limits].max_eur
Set a session-wide cap with MERCADONA_MAX_EUR so every command in a script is automatically guarded: 
export MERCADONA_MAX_EUR=100
mercadona cart set-many -f basket.txt   # refuses if basket > 100€
mercadona checkout submit --checkout <id> --yes   # also refuses if total > 100€
Or write it to config for a persistent default: 
# ~/.mercadona/config.toml
[limits]
max_eur = 100
Precedence is flag > env > config; 0/unset means no limit. The set-many command prices the resulting basket before writing, so a cap breach leaves the cart untouched. checkout submit fails closed — with a cap set, if it cannot read the order total it refuses rather than pay blind.
The cart --max covers only the product subtotal. The checkout --max must also cover the delivery fee (~8.20€). For a ~60€ basket, use --max 61 on cart commands and --max 70 on checkout commands.

​
Idempotent cart writes with set-many

For agent workflows that build or replace a basket, cart set-many is the correct primitive. It performs a single GET, applies every <id> <qty> change atomically, and issues a single PUT — one round trip, no race conditions. 
printf '5044 1\n60393 1\n85499 1\n' | mercadona cart set-many -f - --max 20
Avoid firing multiple sequential cart add calls in a loop. The cart backend is eventually consistent: a cart get fired immediately after a write may show the pre-write state for a beat, and back-to-back separate writes can race (the second read sees the pre-first-write cart and overwrites it). set-many sidesteps both problems entirely. Use cart clear to empty the cart in a single write before rebuilding from scratch: 
mercadona cart clear

​
Agent workflow pattern

A safe, complete agent workflow for grocery shopping follows these steps in order:
1

Check the existing cart

A real account often holds items from a prior session. Inspect first.
mercadona cart get --json
2

Resolve product names to IDs

Use batch to translate natural-language terms to product IDs and prices in a single request (~100 items per call).
mercadona batch -f terms.txt --json
3

Price the basket before touching the cart

Compute the total deterministically with total. This is the pre-cart estimate; no login required.
mercadona total -f basket.txt --json
4

Set the cart atomically

Write the whole basket in one PUT. The --max flag prices it first and refuses before writing if the total exceeds the cap.
mercadona cart set-many -f basket.txt --max 80
5

Create a checkout

Opens a checkout from the current cart and returns the checkout ID and default delivery address.
mercadona checkout create --json --max 90
6

Browse delivery slots

Slots are attached to the delivery address, not the checkout object.
mercadona checkout slots --address <id> --json
7

Attach delivery address and slot

Reserves the slot; the response carries the final price breakdown including the delivery fee.
mercadona checkout set-delivery --checkout <id> --address <id> --slot <id> --max 90
8

Submit only on explicit user consent

checkout submit is irreversible. Only run it after displaying the full total and receiving unambiguous confirmation from the user.
mercadona checkout submit --checkout <id> --max 90 --yes

​
JSON parsing with jq

The --json flag produces consistently structured output on every command. Common patterns: 
# Get product IDs from a batch search
printf 'leche\nhuevos\n' | mercadona batch -f - --json | jq -r '.[].hits[0].id'

# Check the current cart total
mercadona cart get --json | jq -r '.summary.total'

# Find products on sale in a category
mercadona categories --id 112 --json | jq '.. | objects | select(.price_decreased==true) | {id, display_name, unit_price: .price_instructions.unit_price}'
The search hit shape (from search --json and batch --json) carries id, display_name, packaging, categories, and price_instructions (with unit_price, reference_price, reference_format). The cart shape (from cart get --json) carries id, version, products_count, lines, and summary.total.

​
Environment variables

All configuration that should not appear in shell history or process arguments can be passed via environment variables. The full set:
VariablePurpose
MERCADONA_TOKENBearer access token (short-lived, ~6 weeks)
MERCADONA_COOKIESession cookie accompanying the access token
MERCADONA_CUSTOMERCustomer ID (decoded automatically from the token when omitted)
MERCADONA_USERUsername/email for login (fallback; prefer import-har)
MERCADONA_PASSPassword for login (fallback; prefer import-har)
MERCADONA_MAX_EURSession-wide spending cap in euros — every command honours it
MERCADONA_CONCURRENCYParallel price-fetch threads inside set-many (1–16, default 4)
MERCADONA_CONFIG_DIROverride the default config directory (~/.mercadona/)
Precedence for credentials: flags > env > ~/.mercadona/config.toml > cached token.json.

​
Rate limiting and concurrency

The CLI auto-retries HTTP 429 and 503 responses with backoff, honouring the Retry-After header. An occasional throttle appears as a short pause, not an error. To stay comfortably within rate limits:
  • Use batch instead of many individual search calls. A single batch request handles ~100 terms.
  • MERCADONA_CONCURRENCY tunes the concurrent price-fetch burst inside set-many (default 4, range 1–16). Lower it if you see throttling during large cart builds.
MERCADONA_CONCURRENCY=2 mercadona cart set-many -f large-basket.txt --max 150

​
IP sensitivity

Not all commands have the same network requirements:
  • Search (Algolia) — not behind Mercadona’s Akamai at all. Works from any IP, including CI, serverless, and datacenter egress.
  • Catalog reads (/api/...) — Akamai-fronted but served to anonymous GETs at human-paced volume.
  • Auth, cart, and checkout — IP-sensitive. These must run from a residential IP. Datacenter and serverless egress IPs are flagged by Akamai and trigger hard challenges. Run authenticated commands locally or on a box on your own network.

Build docs developers (and LLMs) love

Get started for freeTalk to us