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 spending guard lets you cap how much the CLI can spend — essential when an AI agent drives the CLI. Any cart or checkout operation that would exceed the cap is refused with a non-zero exit code and a clear error: line on stderr, so agents stop instead of overspending. The guard is enforced at every write step, including the irreversible checkout submit.

​
Three ways to set the cap

You can configure the spending cap at three levels. The highest-precedence source wins:
PriorityMethodExample
1 (highest)--max <eur> flag on the command--max 80
2MERCADONA_MAX_EUR environment variableMERCADONA_MAX_EUR=100
3 (lowest)[limits] max_eur in ~/.mercadona/config.tomlmax_eur = 100
Setting 0 or leaving the option unset disables the guard entirely — no limit is enforced.

​
Config file (persistent, applies to every command)

# ~/.mercadona/config.toml
[limits]
max_eur = 100   # refuse any cart/checkout whose total exceeds 100€

​
Environment variable (session-scoped)

export MERCADONA_MAX_EUR=100
mercadona cart set-many -f basket.txt   # capped at 100€ for this shell session

​
Flag (per-command, highest precedence)

mercadona cart add 51110 2 --max 80
mercadona checkout submit --checkout <id> --max 80 --yes

​
Which commands enforce the cap

The spending guard applies to every command that writes the cart or advances the checkout: 
mercadona cart add <id> <qty> --max 80
mercadona cart set <id> <qty> --max 80
mercadona cart set-many -f basket.txt --max 80
mercadona checkout create --max 80
mercadona checkout set-delivery --checkout <id> --address <id> --slot <id> --max 80
mercadona checkout submit --checkout <id> --max 80 --yes
Read-only commands (search, batch, product, categories, cart get, cart clear, checkout get) do not enforce the cap — they never spend or add to the cart total.

​
How cart set-many enforces the cap

set-many is the preventive enforcement path. When a --max is active, it:
  1. Fetches the current cart from the API.
  2. Folds every <id> <qty> change onto the current lines (new items are priced concurrently, up to MERCADONA_CONCURRENCY parallel requests; items already in the cart reuse their cached price).
  3. Estimates the resulting basket total.
  4. Refuses without writing if the estimate exceeds the cap — the cart is completely untouched.
  5. If the estimate is within the cap, issues the single PutCart write.
  6. Runs a post-write authoritative check against the real total returned by the API; if that real total still breaches the cap, it reverts the cart to its previous state.
This means a cap breach from set-many always leaves the cart unchanged. The same preventive pattern applies to cart add and cart set.

​
How checkout submit enforces the cap (fails closed)

checkout submit is the irreversible step and enforces the cap with the strictest policy — fails closed. With a cap configured:
  • If the order total can be read and exceeds the cap → refuse with a non-zero exit.
  • If the order total cannot be read for any reason → also refuse rather than proceed blind.
Without any cap set, submit prints a warning that no budget guard is active and still proceeds. With a cap set, it never proceeds blind — an unreadable total is treated as a failure.

​
Error messages

When the guard fires, the error is printed to stderr and the command exits with code 1: 
error: BUDGET EXCEEDED: cart total 85.40€ is over the 80.00€ limit — refusing (raise with --max, MERCADONA_MAX_EUR, or [limits].max_eur)
For checkout submit when the total can’t be verified: 
error: refusing to submit: couldn't read the total to enforce the 80.00€ limit (set MERCADONA_MAX_EUR=0 to disable the guard)

​
Three distinct euro figures

These three amounts are easy to conflate but are completely separate concepts:
FigureWhat it isWhere it applies
Minimum order ≈ 60€A floor — the product subtotal must clear this for checkout to proceed. The CLI prints a faltan X€… warning (to stderr) in cart get and checkout create when the basket is below it.Set by Mercadona’s API; not controlled by the CLI.
--max on cart commandsA ceiling on the product subtotal only.cart add, cart set, cart set-many
--max on checkout commandsA ceiling on the total including the delivery fee (~8.20€). Must be sized to cover products plus delivery.checkout create, checkout set-delivery, checkout submit

​
Example: agent-safe configuration

# ~/.mercadona/config.toml
[limits]
max_eur = 100   # refuse any cart/checkout whose total exceeds 100€
Then in a script or agent prompt: 
# Build basket — refused if estimated total > 100€
printf '51110 2\n13406 1\n5044 3\n' | mercadona cart set-many -f -

# Create checkout — refused if cart total > 100€
mercadona checkout create --json

# Submit — refused if order total > 100€, or if total can't be verified
mercadona checkout submit --checkout <id> --max 100 --yes
Size the --max value for checkout commands to include the delivery fee (~8.20€ on top of the product subtotal). If your basket target is 80€ of products, pass --max 90 (or higher) on checkout set-delivery and checkout submit, or the guard will refuse a valid order.
Leave a small headroom margin above a round basket target. Product prices are discrete, so a basket aimed at “around 60€” can land at 60.10€. Passing --max 61 instead of --max 60 avoids a spurious refusal while still giving the guard meaningful coverage.

Build docs developers (and LLMs) love

Get started for freeTalk to us