mercadona-cli: a Go CLI for searching Mercadona and building a cart from the terminal

What it is, and the disclaimer it leads with

The README opens with the disclaimer, which is the right place to start. Mercadona has no public API. This is an unofficial client talking to the same HTTP endpoints the website does, you bring your own credentials, and the README asks for a sane request rate.

What it gives you in exchange is the shape a script or an agent needs: a single static Go binary with no runtime dependencies, structured --json output, data on stdout, logs and errors on stderr, and exit code 1 on error.

The anonymous read path

Nothing in the read path needs an account:

mercadona search queso
mercadona search --limit 5 --json mayonesa
mercadona product 13406
mercadona categories

search does full-text product search, product shows detail with price and nutrition where available, and categories prints the category tree. The batch command is the one built for bulk work, taking many terms in a single request at roughly 100 items per call, from a file or from stdin:

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

Common flags are --wh mad1 for the warehouse, --lang es for language and --json for structured output, and they can go anywhere after the subcommand rather than only up front.

Warehouses change prices and product ids

Product ids and prices are per-warehouse, and online checkout requires the cart warehouse to match your delivery address. So the first thing to set is the warehouse, resolved from a postal code with no login at all:

mercadona set-postal 28022

That writes the resolved warehouse into the config as the default. Precedence runs --wh flag, then config.toml defaults, then a built-in mad1, and import-har also detects and saves the warehouse from your session. The README gives a concrete example of why this matters: within one city, 28022 resolves to mad1 and 28013 resolves to mad3.

Installing it and running a first search

Through npm, which downloads the prebuilt binary for your platform:

npm install -g @ivorpad/mercadona
npx @ivorpad/mercadona search queso

Or the curl installer on macOS and Linux:

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

You can pin a release with MERCADONA_VERSION and choose an install location with MERCADONA_INSTALL_DIR, which defaults to /usr/local/bin or else ~/.local/bin. Building from source needs Go 1.26 or newer:

go build -o mercadona ./cmd/mercadona

The README warns that go install is not wired up, because the module path github.com/ivorjpc/mercadona does not match the repository URL.

Authentication: one browser login, then headless

The API authenticates with a Bearer token, a SimpleJWT. The first sign-in has to happen in a browser, because password login needs a Google reCAPTCHA Enterprise token and Google-account users have no password at all. After that the refresh token renews the session headlessly, since POST /api/auth/tokens/ with a refresh_token needs no captcha and rotates the token.

The preferred flow is import-har. Sign in once in the browser, export a HAR, and let the CLI pull the refresh token out:

mercadona import-har --file tienda.mercadona.es.har
mercadona whoami

import-har writes the refresh token into ~/.mercadona/config.toml at mode 0600 and caches the access token and cookie. From then on every 401 token_not_valid triggers an automatic refresh and retry. The README states that it reads only auth responses and Bearer and Cookie headers, and never touches the password in the request body.

There is a hand-written alternative in mercadona set-refresh, plus MERCADONA_TOKEN, MERCADONA_COOKIE and MERCADONA_CUSTOMER for one-off runs. Secrets come from env or files and are never accepted as flags. mercadona login with a user and password exists but fails without a recaptcha_token and does nothing for Google accounts.

Cart and checkout commands

mercadona cart get --json
mercadona cart add 51110 2 --max 80
mercadona cart clear
mercadona checkout create --json
mercadona checkout addresses

cart get inspects the current cart with names, quantity times unit price and the total. cart add takes a product id and a quantity, and --max 80 caps the write at 80 euros. cart set-many takes many id and quantity pairs in one write, where 0 removes an item, and basket files accept inline comments introduced with a hash. checkout create opens a checkout and returns an id plus the default address, checkout addresses lists saved delivery addresses, and delivery slots hang off the address rather than the checkout, so checkout slots takes an address id.

Where it can hurt you, and maintenance

Two things deserve care. The first is blast radius: cart add, cart set-many and cart clear all write to a real cart on a real account, and checkout create opens a real checkout. The --max flag exists precisely because a runaway script spends money.

The second is durability. This is an unofficial client against endpoints Mercadona does not publish, so any server-side change can break it without notice. The README asks you to keep the request rate sane, which is etiquette and self-protection at the same time.

On upkeep: the last push was on 2026-07-13, and v0.1.9 published the same day dropped the npm postinstall step in favour of a lazy first-run download. v0.1.8 added a per-100g nutrition table and guarded partial nutrition tables in the human-readable render. The repository declares no licence.

Editorial conclusion

Use mercadona-cli if you script grocery lookups or want a shopping step inside an agent, and you value JSON on stdout with errors on stderr and exit 1. Do not use it for anything you need to keep working, because it speaks to endpoints Mercadona does not publish and one server-side change ends it. Set the warehouse first with mercadona set-postal on your own postal code, and keep --max on every cart write, since those commands spend real money on a real account.

Frequently asked questions

Official sources

1. Issues
2. ivorpad/mercadona-cli on GitHub
3. Project website
4. README
5. Releases