---
slug: "kroger-cli"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/cschneid/kroger-cli@main/README.md"
repo: "https://github.com/cschneid/kroger-cli"
source_file: "README.md"
branch: "main"
---
# 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](https://developer.kroger.com/)

### Setup Steps

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd kroger-cli
   ```

2. **Install dependencies**
   ```bash
   bundle install
   ```

3. **Configure API credentials**
   ```bash
   cp .env.example .env
   ```
   Edit `.env` and add your Kroger API credentials:
   ```bash
   KROGER_CLIENT_ID=your_client_id_here
   KROGER_CLIENT_SECRET=your_client_secret_here
   ```

4. **Set up your default store** (recommended)
   ```bash
   ./bin/kroger store set
   # Follow prompts to select your preferred store
   ```

5. **Test the installation**
   ```bash
   ./bin/kroger auth
   ```

## 📋 API Credentials Setup

1. **Register at Kroger Developer Portal**
   - Visit [developer.kroger.com](https://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

```bash
# 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

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

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

### Product Search

```bash
# 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)

```bash
# 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

```bash
# Show all commands
./bin/kroger help

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

## 🎯 Example Workflow

```bash
# 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
```bash
# 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