Zonasul Groceries

Zona Sul Grocery Ordering

Order groceries from Zona Sul supermarket in Rio de Janeiro using the zonasul CLI. Supports search, cart management, lists, favorites, reorder, delivery scheduling, and checkout.

First-time setup: see SETUP.md. Debugging: see TROUBLESHOOTING.md.

Prerequisites Check

Before anything, verify the CLI is installed and auth is valid:

zonasul auth status --json

If auth returns "status":"expired" or "status":"unauthenticated", the user needs to log in -- see SETUP.md. If credentials are stored, expired tokens auto-refresh on next command.

Authentication

# Email/password (recommended -- stores credentials for auto-refresh)
zonasul auth login --email user@example.com --password pass

# Or via env vars
ZONASUL_EMAIL=user@example.com ZONASUL_PASSWORD=pass zonasul auth login

# Or paste JWT directly
zonasul auth login --token <jwt>

Once logged in with email/password, the CLI auto-refreshes expired tokens. No manual re-auth needed.

Ordering Workflow

Step 1: Search for Products

zonasul search "banana" --limit 5
zonasul search "feijao preto" --limit 5 --json

Search in Portuguese. Results include SKU ID, name, price, and availability.

Step 2: Add Items to Cart

zonasul cart add <SKU> [--qty N]
zonasul cart add 33277 --qty 3    # Banana Prata x3

Or add from a saved list:

zonasul list order diarista        # add all items in "diarista" list
zonasul fav order                  # add all favorites
zonasul cart reorder               # re-add items from most recent order
zonasul cart reorder <order-id>    # re-add from specific order

Step 3: Review Cart

zonasul cart              # human-readable
zonasul cart --json       # structured JSON
zonasul cart clear        # empty the cart
zonasul cart remove 2     # remove item at index 2

Step 4: Check Delivery Windows

zonasul delivery windows

Wide 5-hour windows are free, tight 2-hour windows cost R$7.00.

Step 5: Place Order

Preview first (no --confirm):

zonasul checkout --window 0

Place the order:

zonasul checkout --window 0 --confirm                              # Pix (default)
zonasul checkout --window 0 --payment credit --cvv XXX --confirm   # credit card

Minimum order is R$100.

Step 6: Verify Order

zonasul orders
zonasul orders --json

Lists and Favorites

Named SKU lists stored in ~/.config/zonasul/lists.json:

zonasul list show                  # all lists
zonasul list show diarista         # items in list
zonasul list add diarista 39908    # add SKU
zonasul list remove diarista 39908 # remove SKU
zonasul list order diarista        # add all to cart
zonasul list order diarista --qty 2 # all with qty 2
zonasul list delete diarista       # delete list

fav is shorthand for the favorites list. Zona Sul has no server-side wishlist, so favorites are stored locally on this machine:

zonasul fav add 18868              # add to favorites
zonasul fav                        # show favorites
zonasul fav order                  # add all to cart

Recipe-Based Ordering

When the user gives a recipe or meal plan:

1. Identify ingredients in Portuguese grocery terms
2. Search each with zonasul search
3. Pick sensible defaults: cheapest for staples, mid-range for key ingredients
4. Present options to the user with prices
5. Check total against R$100 minimum -- suggest additions if under
6. Add all items and place order

Common Portuguese grocery terms:

Environment Variables

Exit Codes