| name | amazon-fresh-shopping |
| description | Build, inspect, edit, schedule, price, place, and cancel Amazon Fresh grocery orders through the local `fresh` CLI. Use when a user asks an agent to search Amazon Fresh, choose groceries, create or modify a cart, compare prices, select an address or delivery slot, configure substitutions or tip, preview checkout, place an order, inspect orders, or cancel an order. |
Amazon Fresh Shopping
Use fresh as the sole execution layer. Let the agent make shopping decisions; keep authentication, cart mutations, checkout, and orders inside the CLI. Commands emit one JSON value to stdout and errors to stderr.
Safety rules
- Never request or accept Amazon passwords, MFA codes, cookies, CSRF tokens, HAR secrets, or raw authenticated HTML. Use
fresh auth login or fresh auth refresh.
- Treat search, cart edits, address selection, slot selection, substitutions, and tip changes as reversible.
- Treat order placement and cancellation as irreversible actions requiring fresh, explicit user confirmation.
- Never infer
PLACE ORDER or CANCEL ORDER from vague approval such as “looks good,” “try it,” or “go ahead.”
- Before requesting
PLACE ORDER, show item count, masked address and payment method, delivery window, every checkout line, tip, exact total, and maximum total.
- Bind the preview maximum to the exact total unless the user explicitly chooses a higher ceiling.
- Never reuse an expired preview token or place after any cart, address, slot, payment, tip, substitution, or price change. Preview again.
- Never retry an ambiguous placement or cancellation. Inspect orders and cart state; report the outcome as unknown until an order ID or user-visible confirmation exists.
- Never claim success from an empty cart alone.
Authenticate
Run:
fresh auth status
If unauthenticated, use fresh auth refresh. If refresh cannot recover the session, use fresh auth login and let the user complete Amazon's device-code flow. Never automate credential entry.
Build a cart
- Read the existing cart with
fresh cart list before changing it.
- Search with
fresh search --limit 10 "QUERY".
- Compare title, size, price, unit price, availability, promotion, and cart quantity. Avoid out-of-stock results and misleading pack sizes.
- Add the selected result using its exact returned ASIN, price, and URL:
fresh cart add ASIN --expected-price PRICE --source-url 'SEARCH_RESULT_URL'
The source URL must be the exact Fresh search URL returned by the same search. If the CLI reverses an add because the live price differs, search again and reassess rather than bypassing the guard.
- Serialize cart mutations. Amazon may reject concurrent adds with HTTP 400.
- Use
fresh cart quantity ASIN_OR_ITEM_ID N and fresh cart remove ASIN_OR_ITEM_ID for edits.
- Read
fresh cart list again and summarize what is actually present. Do not rely on planned additions.
Choose products according to the user's budget, dietary requirements, existing food, effort tolerance, servings, and preferences. Ask only for missing information that materially changes the cart.
Configure fulfillment
Use only masked identifiers returned by the CLI:
fresh address list
fresh address use INDEX_OR_ID
fresh schedule list
fresh schedule select INDEX
fresh substitutions list
fresh substitutions set INDEX_OR_ASIN similar
fresh substitutions set INDEX_OR_ASIN none
Do not change the address, slot, or substitution policy unless requested or necessary to fulfill the task. Explain any material choice.
Preview checkout and set tip
Preview with an explicit ceiling and optional tip:
fresh checkout preview --max-total AMOUNT --tip TIP
Tip may be $0.00 through $100.00. Treat the returned order_total as the purchase total. Show the complete breakdown; do not estimate fees by subtracting stale cart prices. A higher temporary card authorization is not the order total.
Preview once with a reasonable observation ceiling when the exact total is unknown. Then, after user review, preview again with the intended maximum to obtain the placement token. Tokens expire after five minutes and are one-shot.
Place an order
Require a user message containing the exact phrase PLACE ORDER after presenting the current preview. Then use the token and the same maximum:
fresh checkout place --token TOKEN --confirm 'PLACE ORDER' --max-total AMOUNT
Do not place if the user's confirmation refers to a different cart, total, tip, address, or slot. If Amazon reports an ambiguous redirect or unknown outcome, do not retry. Check fresh orders list and fresh cart list, but report only confirmed evidence.
Inspect or cancel orders
List orders with:
fresh orders list
Before cancellation, identify the exact order and summarize the consequence. Require a user message containing the exact phrase CANCEL ORDER, then run:
fresh orders cancel INDEX_OR_ORDER_ID --confirm 'CANCEL ORDER'
Never retry an ambiguous cancellation. A user-visible Amazon cancellation confirmation can resolve an otherwise ambiguous CLI response.
