Karrt

Add -p to any command for pretty-printed JSON.

How to Run Commands

cd ~/karrt && node dist/cli.js <command>

If you get an error about missing dist/, build first: npm run build

Date & Time Handling

Time-sensitive commands (timeslots, orders, receipts, timeslot-reserve) include a now field showing the current date and time in German locale (Europe/Berlin). Use this to:

• Convert "tomorrow" / "next Tuesday" / "this weekend" into actual dates
• Present timeslots as human-readable day names ("Tuesday 08:00–09:00") relative to now
• All API timestamps are UTC — convert to Europe/Berlin (UTC+1 winter, UTC+2 summer) when presenting to the user
• REWE typically does not offer Sunday pickup

Authentication

The CLI uses browser-based login (Playwright + stealth + 2Captcha extension). Session cookies expire roughly every 10 minutes (rstp cookie).

If you get a 401/403 error, the session has expired. Re-authenticate:

cd ~/karrt && node dist/cli.js login

Login is fully autonomous when TOTP is configured — no human interaction needed. Credentials come from REWE_EMAIL and REWE_PASSWORD environment variables.

Do not ask the user about authentication. Just re-login silently and retry the failed command. Only tell the user if login itself fails.

Searching for Products

The Category Filter (Important!)

REWE's search is fuzzy — searching "Milch" returns shower gel and cat food alongside actual milk, and "Eier" returns Kinder Surprise eggs. Always use --category <slug> to constrain results to the right product type.

karrt search "Milch" --sort PRICE_ASC --category milch
karrt search "Eier" --sort PRICE_ASC --category eier-ei-ersatz
karrt search "Hähnchenbrust" --sort PRICE_ASC --category gefluegelfleisch
karrt search "Parmesan" --sort PRICE_ASC --category hartkaese

Heads-up on "eier-ei-ersatz": This category includes both real eggs AND vegan egg substitutes. The substitute (REWE Bio + vegan Eiersatz, 0.69€) sorts cheapest but is NOT eggs — skip it when the user wants actual eggs. Real eggs start around 1.89€ (Bodenhaltung) / 2.29€ (Freiland).

Category Slug Reference

The --category flag accepts URL-style slugs derived from REWE's category tree. Here are the most commonly needed ones:

Dairy & Eggs:

Meat & Fish:

Staples & Pantry:

Fresh Produce:

Bakery & Bread:

Beverages:

Frozen & Convenience:

Snacks & Sweets:

Deriving new slugs: Category slugs are kebab-case versions of the German category name with umlauts converted (ä→ae, ö→oe, ü→ue, ß→ss). If a slug returns 404, try the parent category or a broader term. Check categoryPath in any search result to discover the exact hierarchy.

Search Strategy

Always use --category when you know what type of product the user wants. Only omit it for genuinely open-ended searches (e.g., "what's on offer this week?").

When the category slug is unknown or returns 404:

1. Do a quick search without --category first
2. Check the categoryPath field in the results to discover the right slug
3. Re-search with --category for clean results

Finding the Cheapest Option

Always use --sort PRICE_ASC when the user wants cheap/cheapest. Use --per-page 5 to keep output small when you only need the top few:

karrt search "Mozzarella" --sort PRICE_ASC --category frischkaese --per-page 5

The first result is the cheapest. Compare by grammage (price per kg/L) when products have different sizes — a larger pack at a higher total price may be cheaper per unit.

Search Strategy for Recipes / Meal Planning

When shopping for a recipe, search each ingredient individually with the appropriate category:

karrt search "Spaghetti" --sort PRICE_ASC --category nudeln
karrt search "Speck" --sort PRICE_ASC --category roher-schinken-speck
karrt search "Eier" --sort PRICE_ASC --category eier-ei-ersatz
karrt search "Parmesan" --sort PRICE_ASC --category hartkaese
karrt search "Pfeffer" --sort PRICE_ASC --category gewuerze

Use German terms for searches. If a search returns no results, try shorter/simpler terms.

Attribute Filters

These can be combined with each other and with --category:

karrt search "Milch" --organic --category milch
karrt search "Hähnchen" --organic --regional --category gefluegelfleisch

Understanding Product Quality Labels

Bio/Organic: Use --organic flag. Brands: "REWE Bio", "ja! Natürlich", "Demeter", "Bioland".

Haltungsform (animal welfare tiers): NOT a search filter — check product names:

• Haltungsform 1 (Stallhaltung) — basic factory farming, cheapest
• Haltungsform 2 (StallhaltungPlus) — slightly better conditions
• Haltungsform 3 (Außenklima) — outdoor access
• Haltungsform 4 (Premium) — highest welfare, most expensive
• Bio/organic meat is typically Haltungsform 4

REWE Brand Tiers (cheapest → most expensive):

• "ja!" — Budget brand, cheapest for most staples
• "REWE Beste Wahl" — Mid-tier quality
• "REWE Bio" — Organic line
• "REWE Feine Welt" — Premium/gourmet

Understanding Search Results

Each product in results has this structure (key fields):

productName: "ja! Mozzarella"
brand.name: "ja!"
_embedded.articles[0]._embedded.listing.id: "8-1234567-890123"  ← listingId for basket
_embedded.articles[0]._embedded.listing.pricing:
  currentRetailPrice: 85        ← price in CENTS (85 = 0.85€)
  grammage: "125 g (1 kg = 6,80 €)"
_embedded.categoryPath: "Käse, Eier & Molkerei/Käse & Käseersatz/Frischkäse/"  ← verify product type

Prices are in cents. Divide by 100 to get euros.

The listingId is what you need for basket operations. Extract it from _embedded.articles[0]._embedded.listing.id.

The categoryPath tells you whether the product is actually what you searched for. Use it to verify results and to discover new category slugs.

Basket Management

Adding Items

karrt basket add "8-1234567-890123" --qty 2

Building a Shopping List

When the user asks you to shop for a recipe or meal:

1. Clear the basket first (if they want a fresh start): karrt basket clear
2. Search each ingredient with --sort PRICE_ASC --category <slug> for budget-conscious shopping
3. Pick the best match — consider: price, brand (ja! = cheapest), size, and whether it matches
4. Add each item to the basket
5. Show a summary with item names, quantities, and total cost
6. Check timeslots if the user wants to pick up

Bulk Add

For adding many items at once (faster than individual adds):

karrt basket bulk-add '[{"listingId":"8-123-456","qty":1},{"listingId":"8-789-012","qty":2}]'

Viewing the Basket

karrt basket show

The response includes:

• lineItems: each item with name, quantity, price, totalPrice
• summary.totalPrice: basket total in cents
• staggerings: free pickup thresholds (usually 50€ for free pickup)

Free Pickup Threshold

REWE charges a pickup fee (usually 2€) for baskets under 50€. The basket response includes staggerings info:

• reachedStaggering.displayText — current fee tier
• nextStaggering.remainingArticlePrice — cents needed to reach the next (cheaper/free) tier

When the user is close to 50€, suggest adding a few more items. Use karrt suggestion 5 to find frequently-ordered items that could fill the gap.

Clearing the Basket

karrt basket clear

This removes all items one by one. It's not instant for large baskets.

Timeslots & Pickup

karrt timeslots

The response includes a now field with the current date/time. Use this to present slots as readable days.

• REWE pickup is available most days, typically 08:00–18:00 hourly slots
• Timeslot IDs look like UUIDs — pass them to karrt timeslot-reserve <slotId>
• Reservations expire (usually ~30 min) — reserve close to when the user wants to finalize
• The serviceFee in the response is in cents (0 = free pickup, usually when basket > 50€)

Smart Shopping Patterns

"Find me the cheapest X"

karrt search "X" --sort PRICE_ASC --category <appropriate-slug>

Report the top 1-3 results with name, price, and grammage.

"Get me ingredients for [dish]"

1. Think through what ingredients the dish needs
2. Search each one with --sort PRICE_ASC --category <slug>
3. Pick one product per ingredient (prefer ja! brand for budget, REWE Bio for organic)
4. Add all to basket
5. Report: what you picked, individual prices, total

"What's on offer?"

karrt search "Obst" --offers --category frisches-obst

"Show me organic/bio options for X"

karrt search "X" --organic --category <slug>

"Suggest items to fill my cart for free pickup"

karrt suggestion 5

This analyzes past orders and suggests frequently-bought items not in the current basket, plus shows how much more is needed for the free pickup threshold.

Error Handling

When a session error occurs, re-login automatically and retry the command. Don't burden the user with auth details.

Presenting Results to the User

• Prices: Always in euros with 2 decimal places (e.g., "0.85€")
• Products: Name + brand + price + grammage on one line
• Basket summaries: Table or list format with total at the bottom
• Timeslots: Group by day, show as "Tuesday 08:00–09:00" not raw ISO timestamps
• Keep it concise: The user is on Telegram — short messages, no walls of JSON
• Use German product names: Don't translate "Hähnchenbrustfilet" to "chicken breast fillet" in the summary — keep the original name so the user recognizes it at pickup