Kroger CLI 🛒

A comprehensive Ruby command-line interface for the Kroger API, providing full shopping functionality including product search, cart management, store location services, and real-time sales tracking.

✨ Features

🔐 Authentication

• OAuth 2.0 client credentials flow for public data
• User authentication via browser for cart operations
• Automatic token refresh (27-minute strategy)
• Secure token storage (.token file)

🏪 Store Management

• Store location search by ZIP code
• Default store configuration for consistent pricing
• Store-specific inventory and pricing information
• Interactive store selection

🔍 Product Discovery

• Smart product search with fuzzy matching
• Delivery-only filtering for online orders
• Real-time stock levels (High/Low/Out)
• Enhanced sales display with savings calculations
• Product details including nutrition information

🛒 Shopping Cart

• Add/remove items from cart
• Update quantities
• Store-specific cart operations
• Cart persistence across sessions

💰 Sales & Pricing

• Real-time pricing from your selected store
• Sale detection with visual indicators (🏷️ ON SALE)
• Savings calculations ("💰 You Save: $0.16 (6% off)")
• Promotional pricing display

🚀 Installation

Prerequisites

• Ruby 3.0+ (tested with Ruby 3.3.2)
• Bundler for dependency management
• Kroger API credentials from developer.kroger.com

Setup Steps

1. Clone the repository

   git clone <repository-url>
   cd kroger-cli

2. Install dependencies

   bundle install

3. Configure API credentials

   cp .env.example .env

   Edit .env and add your Kroger API credentials:

   KROGER_CLIENT_ID=your_client_id_here
   KROGER_CLIENT_SECRET=your_client_secret_here

4. Set up your default store (recommended)

   ./bin/kroger store set
   # Follow prompts to select your preferred store

5. Test the installation

   ./bin/kroger auth

📋 API Credentials Setup

1. Register at Kroger Developer Portal

   • Visit developer.kroger.com
   • Create a developer account
   • Register a new application

2. Configure your application

   • Redirect URI: http://localhost:8573
   • Required Scopes:
     • product.compact (product search)
     • cart.basic:write (cart management)
     • profile.compact (user info)

3. Copy credentials

   • Client ID and Client Secret to your .env file

💻 Usage

Authentication & Setup

# Test API connection
./bin/kroger auth

# Login for cart functionality (opens browser)
./bin/kroger login

# Set your default store
./bin/kroger store set

# Show current store
./bin/kroger store show

# Logout from user account
./bin/kroger logout

Store Operations

# Find stores by ZIP code
./bin/kroger stores 80525

# Search with custom radius
./bin/kroger stores 80525 --radius 25

Product Search

# Basic product search
./bin/kroger products "organic milk"

# Delivery-only items (recommended)
./bin/kroger products "bread" --delivery

# Limit results
./bin/kroger products "cheese" --delivery --limit 5

# Get detailed product information
./bin/kroger product 0001111041700

Shopping Cart (requires login)

# View cart contents
./bin/kroger cart view

# Add items to cart
./bin/kroger cart add 0001111041700
./bin/kroger cart add 0001111041700 --quantity 3

# Update item quantity
./bin/kroger cart update 0001111041700 2

# Remove items
./bin/kroger cart remove <item_id>

Help & Options

# Show all commands
./bin/kroger help

# Command-specific help
./bin/kroger products --help
./bin/kroger stores --help

🎯 Example Workflow

# 1. Set up authentication and store
./bin/kroger auth
./bin/kroger login
./bin/kroger store set

# 2. Search for delivery-available products
./bin/kroger products "milk" --delivery

# 3. Add items to cart using UPC from search results
./bin/kroger cart add 0001111050236 --quantity 2

# 4. Check what's in your cart
./bin/kroger cart view

📊 Output Examples

Product Search (On Sale)

Kroger® Sharp Cheddar Block Cheese 🏷️ ON SALE
  UPC: 0001111058627
  Brand: Kroger
  Size: 8 oz
  Price: $2.49 $2.33
  💰 You Save: $0.16 (6% off)
  Status: ✓ In stock

Product Search (Regular Price)

Kroger® Ice Cream Tub
  UPC: 0001111050508
  Brand: Kroger
  Size: 48 oz
  Price: $2.99
  Status: ✓ In stock

🔧 Configuration Files

• .env - API credentials (gitignored)
• .token - User authentication tokens (gitignored)
• .kroger_store - Default store configuration (gitignored)

🏗️ Architecture

kroger-cli/
├── bin/kroger              # Main executable
├── lib/
│   ├── kroger.rb          # Main module & configuration
│   ├── kroger/
│   │   ├── auth.rb        # Client credentials OAuth
│   │   ├── user_auth.rb   # User authentication flow
│   │   ├── store_config.rb # Store management
│   │   ├── api_client.rb  # HTTP client & API calls
│   │   ├── services/      # Business logic services
│   │   └── cli/           # Command-line interface
└── README.md

🛡️ Security

• API credentials stored in environment variables
• User tokens stored locally in .token file
• No sensitive data committed to repository
• Automatic token refresh prevents expired sessions
• OAuth 2.0 PKCE flow for secure user authentication

🐛 Troubleshooting

Authentication Issues

# Check if credentials are loaded
./bin/kroger auth

# Clear and re-login if having user auth issues
./bin/kroger logout
./bin/kroger login

Cart Issues

• 404 errors: Ensure you're logged in (./bin/kroger login)
• Invalid items: Use --delivery flag to find deliverable products
• Store not set: Configure default store (./bin/kroger store set)

API Rate Limits

• 10,000 calls per day for public APIs
• Use --delivery flag to reduce unnecessary API calls
• Set default store to avoid repeated location lookups

🎯 Use Cases

• Grocery shopping - Search and add items to cart for delivery
• Price comparison - Check current prices and sales
• Store information - Find locations and hours
• Sale hunting - Identify discounted items with savings calculations
• Meal planning - Search for specific ingredients
• Bulk shopping - Add multiple quantities to cart efficiently

🚀 Future Enhancements

• Recipe integration - Add ingredients from recipes
• Shopping lists - Save and manage multiple lists
• Price tracking - Historical price monitoring
• Coupon management - Digital coupon application
• Order history - View past purchases
• Nutritional analysis - Aggregate nutrition information

📄 License

This project is for educational and personal use. Please respect Kroger's API terms of service.

---

Built with ❤️ using Ruby and the Kroger API