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.

Read commands — search, batch, product, and categories — require no login and work anonymously from any IP. Cart and checkout commands require a Bearer token (SimpleJWT) issued by Mercadona’s API. The very first login must happen in a real browser because the POST /api/auth/tokens/ endpoint requires a Google reCAPTCHA Enterprise token that can only be minted by a browser, and Google-account users have no password at all. Once you have authenticated once, however, the refresh token renews your session completely headlessly: POST /api/auth/tokens/ {refresh_token} needs no CAPTCHA, rotates the token, and works from any IP indefinitely — one browser login, then unattended forever.

​
Auth methods

MethodCommandRefresh token?Headless renewal?When to use
HAR importimport-har✅ Yes✅ ForeverRecommended — works for email and Google logins
cURL importimport-curl❌ No❌ ~6 weeksQuick one-off, no ongoing use
Manual seedset-refresh✅ Yes✅ ForeverAdvanced: copy token manually from DevTools
Password loginlogin❌❌ Fails headlessLast resort, requires browser reCAPTCHA

​
How token renewal works

Every authenticated command loads the cached session from ~/.mercadona/token.json. When a request returns 401 token_not_valid, the client automatically calls POST /api/auth/tokens/ with the stored refresh_token to obtain a fresh access_token. The response may also rotate the refresh token itself — the new value is written back to token.json immediately. The original request is then retried transparently, so a token expiry is invisible to the caller. The access token is a SimpleJWT and lasts approximately six weeks. The refresh token is durable: it remains valid until you explicitly log out in the browser or Mercadona rotates it server-side. As long as config.toml holds a valid refresh token, the CLI is always authenticated.

​
Credential precedence

The client resolves credentials in the following order, stopping at the first source that provides a usable token:
  1. Flags — --wh, --lang, and similar per-command flags (no direct token flag; tokens come from the sources below)
  2. Environment variables — MERCADONA_TOKEN, MERCADONA_COOKIE, MERCADONA_CUSTOMER, MERCADONA_USER, MERCADONA_PASS
  3. ~/.mercadona/config.toml — [auth] refresh_token, username, password
  4. Cached session — ~/.mercadona/token.json (written by import-har, import-curl, and login)
A refresh token in config.toml triggers an automatic headless refresh if no access token is found. Credentials stored under [auth] username / password in config.toml can also trigger a full login, but that call requires a reCAPTCHA token the CLI cannot supply — so in practice only the refresh_token path yields a working headless session.
The CLI never echoes secret values. After import-har, import-curl, and set-refresh it prints only the length of each credential (e.g. token=312 chars) and the non-secret customer ID. Secrets never appear in stdout, stderr, or log output.

​
Next steps

HAR Import

Export a HAR from DevTools and extract your refresh token for headless-forever auth. Recommended for all new setups.

cURL Import

Copy a browser request as cURL to import a Bearer token for a quick one-off authenticated session.

set-refresh

Seed a refresh token directly from DevTools into config.toml without a full HAR export.

Build docs developers (and LLMs) love

Get started for freeTalk to us