Skip to content

DeGrandis/kwfcli

BranchesTags

Repository files navigation

Kimberton Whole Foods

🥬 Kimberton Whole Foods CLI

Command-line tool for searching products, checking prices, getting weekly sales, and store information for Kimberton Whole Foods locations across Pennsylvania.

📦 Quick Install

npx skills add DeGrandis/kimberton-whole-foods

🌱 Overview

This skill provides five commands that interact with the Kimberton Whole Foods website to retrieve:

  • 🔍 Product Search: Find products by keyword with prices, stock status, and shelf locations
  • 📋 Product Details: Get comprehensive information about specific items
  • 🖼️ Product Images: Get direct image URLs for product photos
  • 🏷️ Weekly Sales: Retrieve the current weekly sales flyer image
  • 🏪 Store Information: Get hours, address, and phone numbers for any location

Output Format: All commands output markdown tables by default for easy LLM parsing. Use --json flag to get structured JSON output.

📍 Store Locations

Location Store Code
Malvern 1000-17
Downingtown 1000-4
Douglassville 1000-6
Kimberton 1000-9
Collegeville 1000-22
Ottsville 1000-27
Wyomissing 1000-7055

🛠️ Installation

Requirements

  • Python 3.6+
  • pip

Setup

cd ~/.openclaw/skills/kimberton_whole_foods
pip install -r requirements.txt
chmod +x kwfcli  # Make CLI executable

Usage:

# From the skill directory
./kwfcli search "organic honey"
./kwfcli search "organic honey" --json
./kwfcli details INV-1000-150551
./kwfcli details INV-1000-150551 --fields images location
./kwfcli details INV-1000-150551 --json
./kwfcli image 1000-140364
./kwfcli image 1000-140364 product.jpg
./kwfcli sales
./kwfcli store downingtown
./kwfcli store downingtown --json

# Or use full path from anywhere
~/.openclaw/skills/kimberton_whole_foods/kwfcli search "organic eggs"

Dependencies:

  • requests - HTTP library
  • beautifulsoup4 - HTML parsing
  • lxml - XML/HTML parser

📚 Usage Examples

🔍 Product Search

Search for products by keyword and get a list of matching items with pricing and availability.

Command:

kwfcli search organic honey

Output (Default - Markdown Table):

# Search Results: organic honey
Store: malvern | Total: 38

INV Code|Name|Brand|Price|Suggested|Savings|Stock|Location|Department
---|---|---|---|---|---|---|---|---
INV-1000-157467|Organic Honey Nut O's Cereal|Cascadian Farm|$3.99|$6.49|$2.50|Yes|G1-4|103 Dry Goods
INV-1000-177419|Organic Chocolate Honey Mint Patty|Heavenly Organics|$0.99|$1.49|$0.50|Yes|REG1|105 Candy Snacks & Beverages

Get JSON Output:

kwfcli search organic honey --json

Output (JSON):

{
  "query": "organic honey",
  "store": "malvern",
  "totalResults": 38,
  "products": {
    "INV-1000-157467": {
      "name": "Organic Honey Nut O's Cereal",
      "image": "1000-141348",
      "actualPrice": 3.99,
      "suggestedPrice": 6.49,
      "autoDiscount": 2.5,
      "outOfStock": false,
      "brand": "Cascadian Farm",
      "size": "9.5oz",
      "shelfSequence": 133,
      "location": "G1-4",
      "department": "103 Dry Goods",
      "discontinued": false
    },
    "INV-1000-177419": {
      "name": "Organic Chocolate Honey Mint Patty",
      "image": "1000-136480",
      "actualPrice": 0.99,
      "suggestedPrice": 1.49,
      "autoDiscount": 0.5,
      "outOfStock": false,
      "brand": "Heavenly Organics",
      "size": "1.2oz",
      "shelfSequence": 74,
      "location": "REG1",
      "department": "105 Candy Snacks & Beverages",
      "discontinued": false
    }
  }
}

Key Fields:

  • actualPrice: Current selling price
  • suggestedPrice: Original/regular price
  • autoDiscount: Calculated savings (suggestedPrice - actualPrice)
  • location: Shelf location code (e.g., "G1-4" = Aisle G1, Shelf 4)
  • image: Image ID (can be converted to URL)
  • Stock: "Yes" = in stock, "No" = out of stock

Notes:

  • Returns up to 100 products per search
  • Product INV codes (keys) can be used with the Product Detail scraper
  • Search is keyword-based across product names
  • Boolean values display as "Yes"/"No" in markdown tables, true/false in JSON

📋 Product Details

Get comprehensive information about a specific product using its INV code from search results.

Command:

kwfcli details INV-1000-157467

Output (Default - Markdown Table):

# Product Details: INV-1000-157467
Store: malvern

Field|Value
---|---
id|INV-1000-157467
name|Organic Honey Nut O's Cereal
brand|Cascadian Farm
size|9.5oz
scanCode|021908455594
actualPrice|$3.99
suggestedPrice|$6.49
outOfStock|No
location|G1-4
shelfSequence|133
images|1000-141348

Filter specific fields:

# Get only images and shelf location
kwfcli details INV-1000-157467 --fields images location shelfSequence

Output (Filtered):

# Product Details: INV-1000-157467
Store: malvern

Field|Value
---|---
location|G1-4
shelfSequence|133
images|1000-141348

Get JSON Output:

kwfcli details INV-1000-157467 --json

Output (JSON):

{
  "productId": "INV-1000-157467",
  "store": "malvern",
  "details": {
    "id": "INV-1000-157467",
    "name": "Organic Honey Nut O's Cereal",
    "brand": "Cascadian Farm",
    "size": "9.5oz",
    "scanCode": "021908455594",
    "actualPrice": 3.99,
    "suggestedPrice": 6.49,
    "outOfStock": false,
    "sellOutOfStock": true,
    "department": "103 Dry Goods",
    "departmentId": "1000-89",
    "location": "G1-4",
    "shelfSequence": 133,
    "discontinued": false,
    "maxQuantity": 99.0,
    "loyalty": 0,
    "local": false,
    "hasModifiers": false,
    "hasLinkedItems": false,
    "hasRestriction": false,
    "hasAgeRestriction": false,
    "cashierApprovalRequired": false,
    "weightProfile": {},
    "images": [
      {
        "id": "1000-141348",
        "caption": null
      }
    ],
    "itemGroups": [
      "CGP-1000-10238",
      "CGP-1000-10295",
      "CGP-1000-6135"
    ]
  }
}

Additional Fields:

  • scanCode: UPC/barcode for the product
  • sellOutOfStock: Whether product can be sold when out of stock
  • maxQuantity: Maximum purchase quantity
  • local: Whether product is locally sourced
  • weightProfile: Bulk/weight item settings (if applicable)
  • itemGroups: Category group IDs

Field Filtering:

Use --fields to return only specific attributes, reducing response size:

kwfcli details INV-1000-157467 --fields images location shelfSequence

Filtered Output:

{
  "productId": "INV-1000-157467",
  "store": "malvern",
  "details": {
    "location": "G1-4",
    "shelfSequence": 133,
    "images": [
      {
        "id": "1000-141348",
        "caption": null
      }
    ]
  }
}

Available Fields: id, name, brand, size, scanCode, actualPrice, suggestedPrice, outOfStock, sellOutOfStock, department, departmentId, location, shelfSequence, discontinued, maxQuantity, loyalty, local, hasModifiers, hasLinkedItems, hasRestriction, hasAgeRestriction, cashierApprovalRequired, weightProfile, images, itemGroups

Field Filtering Benefits:

  • Reduces response size for LLM token usage
  • Faster parsing when you only need specific data
  • Combine multiple fields as needed (e.g., --fields images location actualPrice)
  • All boolean fields display as "Yes"/"No" in markdown, true/false in JSON

🏷️ Weekly Sales Flyer

Retrieve the current weekly sales flyer image URL.

Command:

kwfcli sales

Output:

{
  "page_url": "https://www.kimbertonwholefoods.com/real-deals/",
  "image_url": "https://www.kimbertonwholefoods.com/wp-content/uploads/2026/02/WeeklySales_Email_2.18.jpg"
}

Notes:

  • Image URL updates weekly
  • No arguments required
  • Direct link to the sales flyer image

🏪 Store Information

Get hours, address, and phone number for any Kimberton Whole Foods location.

Command:

kwfcli store downingtown

Output (Default - Markdown Table):

# Store Information: Downingtown
URL: https://www.kimbertonwholefoods.com/locations/downingtown/

Field|Value
---|---
Location|Downingtown
Address|150 East Pennsylvania Avenue, Downingtown, PA 19335
Phone|(610) 873-8225
Hours|Monday - Friday: 8:00 AM to 8:00 PM<br>Saturday: 8:00 AM to 8:00 PM<br>Sunday: 8:00 AM to 6:00 PM
Holiday Hours|New Year's Eve<br>Closed at 6:00 PM<br>...

Get JSON Output:

kwfcli store downingtown --json

Output (JSON):

{
  "location": "Downingtown",
  "url": "https://www.kimbertonwholefoods.com/locations/downingtown/",
  "hours": "Monday - Friday: 8:00 AM to 8:00 PM\nSaturday: 8:00 AM to 8:00 PM\nSunday: 8:00 AM to 6:00 PM",
  "holiday_hours": "New Year's Eve\nClosed at 6:00 PM\nNew Year's Day\nClosed\nEaster\nClosed\nMemorial Day\nClosed at 6:00 PM\n4th of July\nClosed at 6:00 PM\nLabor Day\nClosed at 6:00 PM\nThanksgiving\nClosed",
  "address": "150 East Pennsylvania Avenue, Downingtown, PA 19335",
  "phone": "(610) 873-8225"
}

Available Locations:

  • malvern
  • downingtown
  • douglassville
  • kimberton
  • collegeville
  • ottsville
  • wyomissing

🖼️ Product Image URL

Get the direct image URL for displaying product photos (e.g., in Discord, Slack, or web apps).

Command:

kwfcli image 1000-140364

Output:

https://kimbertonwholefoods.storebyweb.com/api/img/1000-140364

Save to File:

kwfcli image 1000-140364 product.jpg

Output (when saving):

{
  "success": true,
  "url": "https://kimbertonwholefoods.storebyweb.com/api/img/1000-140364",
  "output_path": "product.jpg",
  "size_bytes": 9238,
  "content_type": "image/png"
}

Notes:

  • Returns plain URL (not JSON) for easy embedding in Discord/Slack
  • Image identifiers come from the images array in product details
  • Optionally save to file by providing output path
  • Image URLs are from Kimberton's CDN and load quickly
  • Use this command after getting image IDs from search or details commands

🖼️ Product Images

Product image IDs can be converted to direct image URLs using this pattern:

https://kimbertonwholefoods.storebyweb.com/api/img/{image_id}

Example:

  • Image ID: "1000-141348"
  • Image URL: https://kimbertonwholefoods.storebyweb.com/api/img/1000-141348

This works for:

  • Single image IDs from product search results (products[].image)
  • Image objects from product details (details.images[].id)
  • Weekly sales image IDs

🛒 Typical Workflows

🥜 Shopping for Specific Items

  • Search for products: kwfcli search peanut butter
  • Review results to find the product you want
  • Get details if needed: kwfcli details INV-1000-XXXXXX
  • Construct image URL from the image ID
  • Check store hours before visiting: kwfcli store malvern

💰 Weekly Sales Check

  • Get sales flyer: kwfcli sales
  • View image at the returned URL to see current deals
  • Search for specific sale items to check stock: kwfcli search item name

🏷️ Price Comparison

  • Search for product at multiple stores (if supported)
  • Compare actualPrice and autoDiscount values
  • Note shelf location (location field) for in-store pickup

✅ Inventory Check

  • Search for product: kwfcli search eggs
  • Check outOfStock field in results
  • Get details to see sellOutOfStock flag (can still be purchased if true)

💻 Output Format

Default (Markdown Tables):

  • Optimized for LLM parsing with minimal formatting
  • Search results: Horizontal table with product rows
  • Details/Store info: Vertical key-value table
  • Easy to read and parse without visual spacing overhead

JSON (with --json flag):

  • Structured JSON to stdout only (no files created)
  • Perfect for programmatic parsing and automation
  • All fields preserved with full data types

Both formats:

  • Send errors to stderr
  • Exit with code 1 on errors
  • No debug output

Perfect for:

  • LLM/AI agent integration (default markdown)
  • Shell scripts and automation (--json)
  • CI/CD pipelines
  • Data analysis workflows

⚠️ Error Handling

Network Issues:

$ kwfcli search test
Error: Failed to fetch search results

Invalid Product ID:

$ kwfcli details INV-INVALID
Error: Product not found

Invalid Location:

$ kwfcli store invalid_location
Error: Unknown location 'invalid_location'

All errors are sent to stderr and scripts exit with code 1.

🤖 Integration with OpenClaw

These scrapers are designed as an OpenClaw skill. See SKILL.md for LLM integration details including:

  • Tool calling parameters
  • Example prompts
  • Response formatting guidelines
  • User preference handling

🌿 Contributing

When modifying scrapers:

  • Maintain JSON output format for backward compatibility
  • Send all errors to stderr
  • Exit with code 1 on failures
  • Update both SKILL.md and README.md with changes
  • Test with real API calls to verify output

📜 License

This project is for personal/educational use. Kimberton Whole Foods website data is their property - please scrape responsibly and respect their terms of service.

About

A cli interface for the Kimberton Whole Foods grocery store chain

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages