pubcli

pubcli is a Go CLI for fetching current Publix weekly ad deals by store number or ZIP code.

Features

• Fetch weekly ad deals for a specific store
• Resolve nearest Publix store from a ZIP code
• Filter deals by category, department, keyword, and BOGO status
• Sort deals by estimated savings or ending date
• List weekly categories with deal counts
• Compare nearby stores for best filtered deal coverage
• Browse deals interactively in terminal (tui)
• Output data as formatted terminal text or JSON
• Generate shell completions (bash, zsh, fish, powershell)
• Tolerate minor CLI syntax mistakes when intent is clear
• Robot-mode behavior for AI agents (compact help, auto JSON when piped, structured errors, meaningful exit codes)

Requirements

• Go 1.24.4 or newer to build from source
• Network access to:
  • https://services.publix.com/api/v4/savings
  • https://services.publix.com/api/v1/storelocation

Installation

Build locally

git clone https://github.com/tayloree/publix-deals.git
cd publix-deals
go build -o pubcli ./cmd/pubcli

Install with go install

go install github.com/tayloree/publix-deals/cmd/pubcli@latest

Quick Start

Find nearby stores:

pubcli stores --zip 33101

Fetch deals using a store number:

pubcli --store 1425

Fetch deals by ZIP (uses the nearest store):

pubcli --zip 33101

Fetch JSON output:

pubcli --zip 33101 --json

Commands

pubcli

Fetch weekly ad deals.

pubcli [flags]

pubcli stores

List up to 5 nearby stores for a ZIP code.

pubcli stores --zip 33101
pubcli stores -z 32801 --json

pubcli categories

List available categories for the current week.

pubcli categories --store 1425
pubcli categories -z 33101 --json

pubcli compare

Compare nearby stores and rank them by filtered deal quality. Requires --zip. Stores are ranked by number of matched deals, then deal score, then distance.

pubcli compare --zip 33101
pubcli compare --zip 33101 --category produce --sort savings
pubcli compare --zip 33101 --bogo --count 3 --json

pubcli tui

Full-screen interactive browser for deal lists with a responsive two-pane layout:

• async startup loading spinner + skeleton while store/deals are fetched
• visual deal sections (BOGO/category grouped) with jump navigation

Controls:

• tab — switch focus between list and detail panes
• / — fuzzy filter deals in the list pane
• s — cycle sort mode (relevance -> savings -> ending)
• g — toggle BOGO-only inline filter
• c — cycle category inline filter
• a — cycle department inline filter
• l — cycle result limit inline filter
• r — reset inline sort/filter options back to CLI-start defaults
• j / k or arrows — navigate list and scroll detail
• u / d — half-page detail scroll
• b / f or pgup / pgdown — full-page detail scroll
• [ / ] — jump to previous/next section
• 1..9 — jump directly to a numbered section
• ? — toggle inline help
• q — quit

pubcli tui --zip 33101
pubcli tui --store 1425 --category meat --sort ending

Flags

Global flags (available on all commands):

• -s, --store string Publix store number (example: 1425)
• -z, --zip string ZIP code for store lookup
• --json Output JSON instead of styled terminal output

Deal filtering flags (available on pubcli, compare, and tui):

• --bogo Show only BOGO deals
• -c, --category string Filter by category (example: bogo, meat, produce)
• -d, --department string Filter by department (substring match, case-insensitive)
• -q, --query string Search title/description (case-insensitive)
• --sort string Sort by relevance (default), savings, or ending
• -n, --limit int Limit results (0 means no limit)

Compare-specific flags:

• --count int Number of nearby stores to compare, 1-10 (default 5)

Sort accepts aliases: end, expiry, and expiration are equivalent to ending.

Behavior Notes

• Either --store or --zip is required for deal and category lookups. compare requires --zip.
• If only --zip is provided, the nearest store is selected automatically.
• When using text output and ZIP-based store resolution, the selected store is shown.
• Filtering is applied in this order: bogo + category, department, query, sort, limit.
• Category matching is case-insensitive and supports synonym groups (see below).
• Department and query filters use case-insensitive substring matching.
• Running pubcli with no args prints compact quick-start help.
• When stdout is not a TTY (for example piping to another process), JSON output is enabled automatically unless explicitly set.

Category Synonyms

Category filtering recognizes synonyms so common names map to the right deals:

Category	Also matches
bogo	bogof, buy one get one, buy1get1, 2 for 1, two for one
produce	fruit, fruits, vegetable, vegetables, veggie, veggies
meat	beef, chicken, poultry, pork, seafood
dairy	milk, cheese, yogurt
bakery	bread, pastry, pastries
deli	delicatessen, cold cuts, lunch meat
frozen	frozen foods
grocery	pantry, shelf

Synonym matching is bidirectional — using chicken as a category filter matches deals tagged meat, and vice versa.

CLI Input Tolerance

The CLI auto-corrects common input mistakes and prints a note: describing the normalization:

• -zip 33101 -> --zip 33101
• zip=33101 -> --zip=33101
• --ziip 33101 -> --zip 33101
• stores zip 33101 -> stores --zip 33101
• categoriess -> categories

Flag aliases are recognized and rewritten:

Alias	Resolves to
zipcode, postal-code	--zip
store-number, storeno	--store
dept	--department
search	--query
sortby, orderby	--sort
max	--limit

Command argument tokens are preserved for command workflows like:

• pubcli completion zsh
• pubcli help stores

JSON Output

Deals (pubcli ... --json)

Array of objects with fields:

• title (string)
• savings (string)
• description (string)
• department (string)
• categories (string[])
• additionalDealInfo (string)
• brand (string)
• validFrom (string)
• validTo (string)
• isBogo (boolean)
• imageUrl (string)

Stores (pubcli stores ... --json)

Array of objects with fields:

• number (string)
• name (string)
• address (string)
• distance (string)

Categories (pubcli categories ... --json)

Object map of category name to deal count:

{
  "bogo": 175,
  "meat": 88,
  "produce": 81
}

Compare (pubcli compare ... --json)

Array of objects ranked by deal quality:

• rank (number)
• number (string) — store number
• name (string)
• city (string)
• state (string)
• distance (string)
• matchedDeals (number)
• bogoDeals (number)
• score (number)
• topDeal (string)

Structured Errors

When command execution fails, errors include:

• code (example: INVALID_ARGS, NOT_FOUND, UPSTREAM_ERROR)
• message
• suggestions (when available)
• exitCode

JSON-mode errors are emitted as:

{"error":{"code":"INVALID_ARGS","message":"unknown flag: --ziip","suggestions":["Try `--zip`.","pubcli --zip 33101"],"exitCode":2}}

Exit Codes

• 0 success
• 1 not found
• 2 invalid arguments
• 3 upstream/network failure
• 4 internal failure

Shell Completion

Generate completions:

pubcli completion bash
pubcli completion zsh
pubcli completion fish
pubcli completion powershell

Development

Run tests:

go test ./...

Run without building:

go run ./cmd/pubcli --zip 33101 --limit 10