marktguru-cli 🧘‍♂️

CLI for Marktguru supermarket deals in Austria and Germany.

This is a maintained fork of manmal/marktguru-cli, published as @udondan/marktguru-cli.

AI Agent Skill

Install into your coding agent with the skills CLI:

npx skills add udondan/marktguru-cli

Or read skills/marktguru-grocery-deals/SKILL.md directly — a comprehensive reference designed for AI coding agents.

Quick Start (Recommended)

Use npx to run without installing anything:

npx --yes @udondan/marktguru-cli login
npx --yes @udondan/marktguru-cli search raw "milch OR soja"
npx --yes @udondan/marktguru-cli search build --term milch --or soja

Requirements

• Node.js 18+ (built-in fetch)
• Works with npm, pnpm, and bun

Commands

Login (extracts API key via HTTP by scanning the site’s JS):

marktguru login

Search (raw query string syntax):

marktguru search raw "kellys OR \"erdnuss snips\""

Search (structured builder):

marktguru search build --term kellys --phrase "erdnuss snips" --or manner --explain

Show supported query syntax:

marktguru search syntax

Set a default ZIP code:

marktguru set-zip 1010

Set a default country (at or de, default: at):

marktguru set-country de

Show config:

marktguru config

Also Working (Install Locally)

Install and run from source:

npm ci
npm run build
npm start -- --help

Dev mode (TS directly):

npm run dev -- --help

Lint, format and test (same targets CI runs):

make eslint
make format
make test
make validate-package

Search Options

Available for both search raw and search build:

• -z, --zip <code>: ZIP code for location-based results
• -n, --limit <number>: Number of results (default: 10)
• -r, --retailer <name>: Filter by retailer (client-side)
• -j, --json: JSON output

If no API key is configured, search will automatically run login to extract one.

Note: API keys are country-specific. After switching country with set-country, run login again to fetch the matching key.

Builder-only:

• --term <value>: Add a term (repeatable)
• --phrase <value>: Add an exact phrase (repeatable)
• --wildcard <value>: Add a wildcard term like kell* (repeatable)
• --or <value>: Add a term to an OR group (repeatable)
• --group <value>: Add a raw group wrapped in parentheses (repeatable)
• --explain: Print the built query to stderr

Query Syntax (Observed)

The API appears to accept a Lucene/Elasticsearch-style query string, not SQL.

Supported:

• OR for boolean OR
• * wildcard (e.g., kell*)
• "..." exact phrase
• ( ... ) grouping

Not supported (observed):

• AND, NOT, ~, ^

Notes on login

• Uses HTTP requests (no browser automation).
• Scans entry HTML and boot scripts for embedded API keys and validates them.
• May break if the website changes.

Config Location

• ~/.marktguru/config.json