Every Grubhub restaurant search, plus a sortable delivery-fee comparison board, a cross-restaurant deal radar, and offline menu-item search no Grubhub tool has.
grubhub-pp-cli browses Grubhub's marketplace from the command line: search restaurants by street address, browse full menus, and compare delivery fees, minimums, and ETAs across the whole neighborhood at once with compare. It caches restaurants and menus in a local SQLite store so dish can full-text-search menu items across nearby restaurants and deals can rank every active offer in one sweep. No API key required — it mints an anonymous Grubhub token for you.
Authentication
Grubhub has no public API key. grubhub-pp-cli authenticates exactly like the website: it scrapes a fresh anonymous client id from grubhub.com and mints a short-lived bearer token automatically on first use, caching it locally. You don't set anything. For the raw restaurants endpoint commands you can optionally run grubhub-pp-cli auth login (still credential-free) or set GRUBHUB_TOKEN. Logged-in features like order history are not supported in this version.
Quick Start
# Confirm Grubhub is reachable before searching.
grubhub-pp-cli doctor
# Search restaurants near an address, cheapest delivery first.
grubhub-pp-cli near "350 5th Ave, New York, NY" --sort fee --limit 10
# Side-by-side fee/minimum/ETA board for the whole neighborhood.
grubhub-pp-cli compare "350 5th Ave, New York, NY" --sort eta
# Find which nearby restaurants carry a dish under a price.
grubhub-pp-cli dish "350 5th Ave, New York, NY" "poke bowl" --max-price 15
# Rank nearby restaurants by active offers and coupons.
grubhub-pp-cli deals "350 5th Ave, New York, NY"
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
compare — See delivery fee, minimum, ETA, rating, and distance for every nearby restaurant side by side, sorted however you want.
Reach for this when a user wants the cheapest or fastest option across the whole neighborhood, not one restaurant at a time.
grubhub-pp-cli compare "350 5th Ave, New York, NY" --sort eta --agent
-
dish — Find which nearby restaurants carry a specific dish, with price, by full-text searching cached menus across the neighborhood.
Reach for this when the user names a dish, not a restaurant: 'who near me has a poke bowl under $15'.
grubhub-pp-cli dish "350 5th Ave, New York, NY" "poke bowl" --max-price 15 --agent
Deal hunting
-
deals — Rank every nearby restaurant currently running an offer, coupon, or promo code in one sweep.
Reach for this when the deal should pick the restaurant, not the other way around.
grubhub-pp-cli deals "350 5th Ave, New York, NY" --agent
-
pick — Get one recommended restaurant from a transparent score over fee, rating, active deals, and ETA.
Reach for this when the user wants a single 'just pick one' answer with a visible score breakdown.
grubhub-pp-cli pick "350 5th Ave, New York, NY" --weight-deal 2 --agent
Recipes
Cheapest fast delivery near an address
grubhub-pp-cli compare "350 5th Ave, New York, NY" --sort fee --eta-under 30 --agent
Comparison board filtered to sub-30-minute ETAs, cheapest delivery first, as agent JSON.
Find a dish across the neighborhood
grubhub-pp-cli dish "1 Infinite Loop, Cupertino, CA" "burrito" --max-price 12
Full-text search of cached menus for burritos under $12 at any nearby restaurant.
Pull a full menu as compact JSON for an agent
grubhub-pp-cli menu 1414955 --agent --select menu_category_list.menu_item_list.name,menu_category_list.menu_item_list.price
Restaurant menus are deeply nested; --select narrows the payload to item names and prices so agents don't burn context on the full blob.
Let the deal pick the restaurant
grubhub-pp-cli deals "350 5th Ave, New York, NY" --sort value
Ranks every nearby restaurant running an offer by value in one sweep.
Usage
Run grubhub-pp-cli --help for the full command reference and flag list.
Commands
These are the primary commands. They take a street address (auto-geocoded) and
mint an anonymous token for you — no API key or setup.
grubhub-pp-cli near <address> - Search restaurants near an address (--cuisine, --pickup, --sort, --open-now, --limit)grubhub-pp-cli compare <address> - Sortable delivery fee / minimum / ETA / rating board (--sort, --max-fee, --max-min, --eta-under)grubhub-pp-cli dish <address> <query> - Find which nearby restaurants carry a dish (--max-price, --diet, --max-scan-restaurants; --data-source local for cached)grubhub-pp-cli deals <address> - Rank nearby restaurants by active offers and coupons (--sort value|count)grubhub-pp-cli pick <address> - One recommended restaurant from a transparent score (--weight-fee/-eta/-rating/-deal)grubhub-pp-cli menu <restaurant-id> - Browse a restaurant's full menu (--category, --popular, --limit)grubhub-pp-cli item <restaurant-id> <item-id> - Show a menu item's modifiers and pricesgrubhub-pp-cli geocode <address> - Resolve a street address to coordinates
restaurants (raw API surface)
Hidden, typed endpoint commands for power users. They take a POINT(lng lat) location
and need a token (grubhub-pp-cli auth login, still credential-free, or GRUBHUB_TOKEN).
grubhub-pp-cli restaurants get <id> - Get a restaurant's details and full menu by idgrubhub-pp-cli restaurants menu-item <id> <item-id> - Get a menu item's full detail including modifier/choice categoriesgrubhub-pp-cli restaurants search - Search restaurants near a location (raw; use near for address-based search)
Output Formats
# Human-readable table (default in terminal, JSON when piped)
grubhub-pp-cli restaurants get mock-value
# JSON for scripting and agents
grubhub-pp-cli restaurants get mock-value --json
# Filter to specific fields
grubhub-pp-cli restaurants get mock-value --json --select id,name,status
# Dry run — show the request without sending
grubhub-pp-cli restaurants get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
grubhub-pp-cli restaurants get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
grubhub-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/grubhub-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
GRUBHUB_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, grubhub-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
grubhub-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $GRUBHUB_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- HTTP 403 or 'access denied' on search — Grubhub uses PerimeterX bot protection; retry, slow your request rate, or run from a residential network. The CLI already sends a realistic browser User-Agent.
- Empty results for a valid address — Confirm the address geocodes: run
grubhub-pp-cli geocode "<address>". If it returns no coordinates, add city/state/zip.
- 'no local mirror' from compare/dish/deals — Run
grubhub-pp-cli sync "<address>" first to cache restaurants and menus for that location.
- Token expired after a while — Tokens are minted automatically; just re-run the command. For the raw
restaurants surface, re-run grubhub-pp-cli auth login.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press