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.
All persistent state lives in ~/.mercadona/ — override the location by setting MERCADONA_CONFIG_DIR before any command. The directory holds three files: config.toml (user-authored settings and credentials), token.json (machine-managed session cache written on every token refresh), and algolia.json (auto-refreshed search credentials that rotate with the live SPA bundle).
The config.toml file
config.toml is the only file you should edit by hand. It is created automatically at 0600 permissions the first time any command writes to it, so it is safe to store a refresh_token there.
# ~/.mercadona/config.toml
# Permissions: 0600 (created automatically; may contain secrets)
[auth]
refresh_token = "" # durable credential; set via `import-har` or `set-refresh`
username = "" # optional; only for `login` (not for headless use)
password = "" # optional; only for `login` (not for headless use)
[defaults]
warehouse = "mad1" # set via `set-postal` or auto-detected by `import-har`
lang = "es" # es, en, ca, eu, vai
postal_code = "28022" # saved by `set-postal`
[limits]
max_eur = 0 # 0 = no limit; any cart/checkout over this amount is refused
[auth]
| Key | Purpose |
|---|
refresh_token | Durable, headless-renewable credential. On every 401 token_not_valid, the CLI posts POST /api/auth/tokens/ {refresh_token} to obtain a fresh access token — no browser, no captcha. Set once with import-har or set-refresh. |
username | Email address used only by mercadona login. Stored username/password cannot drive a headless session because the login endpoint also requires a reCAPTCHA token the CLI cannot generate. |
password | Password used only by mercadona login. Ignored during headless token refresh. |
[defaults]
| Key | Purpose |
|---|
warehouse | Warehouse code applied to every command that has no --wh flag. Set automatically by mercadona set-postal or import-har. |
lang | Response language (es, en, ca, eu, vai). Overridden per-command with --lang. |
postal_code | Saved alongside warehouse by set-postal; human-readable record of what the warehouse was derived from. |
[limits]
| Key | Purpose |
|---|
max_eur | Spending cap in euros. Any cart or checkout command whose total exceeds this value is refused with a non-zero exit code. 0 means no limit. Overridden by MERCADONA_MAX_EUR or --max. |
Machine-managed files
These two files are written and updated by the CLI itself. You should not edit them directly.
token.json — Cached bearer access token, refresh token, and Akamai cookie. Written by import-har, import-curl, and login; auto-updated whenever the access token is refreshed. If you need to reset your session, delete this file — the CLI will use config.toml [auth].refresh_token to obtain a new one on the next authenticated command.
algolia.json — Cached Algolia app-id, API key, and index name used for search and batch. The public app-id rotates periodically; when the CLI detects a stale-credentials signal (DNS failure, 401, 403, or 404 from Algolia), it re-discovers the credentials from the live SPA bundle, writes them back to this file, and retries. No manual intervention required.
Environment variables
Environment variables override the corresponding config file value for a single command invocation. They are never written to disk.
| Variable | Purpose |
|---|
MERCADONA_CONFIG_DIR | Override config directory (default: ~/.mercadona) |
MERCADONA_TOKEN | Override Bearer access token for one command |
MERCADONA_COOKIE | Override Akamai cookie for one command |
MERCADONA_CUSTOMER | Override customer ID for one command |
MERCADONA_USER | Email/username for login |
MERCADONA_PASS | Password for login |
MERCADONA_MAX_EUR | Spending cap in euros (overrides [limits].max_eur; overridden by --max) |
MERCADONA_CONCURRENCY | Parallel price-fetch workers for cart set-many (1–16, default 4) |
Precedence rules
When the same setting can come from multiple sources, the CLI applies this precedence — highest to lowest:
| Priority | Source | Example |
|---|
| 1 (highest) | Command-line flag | --wh mad1, --max 80 |
| 2 | Environment variable | MERCADONA_MAX_EUR=80, MERCADONA_TOKEN=… |
| 3 | config.toml | [defaults] warehouse = "mad1", [limits] max_eur = 80 |
| 4 (lowest) | Built-in default | warehouse mad1, lang es, no spending cap |
config.toml, override it for a CI run with MERCADONA_MAX_EUR, and override it further for a single command with --max, without touching the file.
config.toml is created automatically at 0600 permissions (owner read/write only) the first time any command writes to it — for example, after running mercadona set-postal or mercadona import-har. If you create it manually, set the permissions yourself with chmod 0600 ~/.mercadona/config.toml to protect the stored refresh_token.