--- name: pp-costco-sameday description: "Printing Press CLI for Costco Sameday. Costco Same-Day (sameday.costco.com) GraphQL CLI. Cookie auth after Costco Azure B2C SSO." author: "DashLabsDev" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - costco-sameday-pp-cli install: - kind: go bins: [costco-sameday-pp-cli] module: github.com/mvanhorn/printing-press-library/library/commerce/costco-sameday/cmd/costco-sameday-pp-cli --- # Costco Sameday — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `costco-sameday-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install costco-sameday --cli-only ``` 2. Verify: `costco-sameday-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/commerce/costco-sameday/cmd/costco-sameday-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Costco Same-Day (sameday.costco.com) GraphQL CLI. Cookie auth after Costco Azure B2C SSO. Place-order mutation is FinalizeCheckout — exposed only via gated `order place` (--yes + --confirm-charge; --dry-run never charges). Tip updates via UpdateCheckout tipsUpdate. Cancel mutation not captured. ## HTTP Transport This CLI uses standard HTTP transport with HTTP/2 disabled for browser-facing endpoints. It does not require a resident browser process for normal API calls. `auth login` starts a browser only for sign-in and closes it after capturing the session cookies; it drives that browser over `--remote-debugging-pipe` (no DevTools network port; Windows falls back to a 127.0.0.1 random port). ## Command Reference **account** — Costco Same-Day account GraphQL operations - `costco-sameday-pp-cli account gethouseholdbyuser` — GraphQL query GetHouseholdByUser (persistedQuery) - `costco-sameday-pp-cli account householdbyuser` — GraphQL query HouseholdByUser (persistedQuery) **cart** — Costco Same-Day cart GraphQL operations - `costco-sameday-pp-cli cart show` (alias `cart list`) — cart items with quantity, unit price and line total plus an estimated subtotal (read-only; per-lb items marked estimate) - `costco-sameday-pp-cli cart activecartid` — GraphQL query ActiveCartId (persistedQuery) - `costco-sameday-pp-cli cart cartbottombannerquery` — GraphQL query CartBottomBannerQuery (persistedQuery) - `costco-sameday-pp-cli cart cartcheckoutvalidation` — GraphQL query CartCheckoutValidation (persistedQuery) - `costco-sameday-pp-cli cart cartcouponremovalpopupquery` — GraphQL query CartCouponRemovalPopupQuery (persistedQuery) - `costco-sameday-pp-cli cart cartonloadplacementquery` — GraphQL query CartOnloadPlacementQuery (persistedQuery) - `costco-sameday-pp-cli cart cartproductsrecomendation` — GraphQL query CartProductsRecomendation (persistedQuery) - `costco-sameday-pp-cli cart cartrecommendationsplacements` — GraphQL query CartRecommendationsPlacements (persistedQuery) - `costco-sameday-pp-cli cart cartsignaledeta` — GraphQL query CartSignaledEta (persistedQuery) - `costco-sameday-pp-cli cart cartswitchervariant` — GraphQL query CartSwitcherVariant (persistedQuery) - `costco-sameday-pp-cli cart carttotals` — GraphQL query CartTotals (persistedQuery) - `costco-sameday-pp-cli cart cartviewlayout` — GraphQL query CartViewLayout (persistedQuery) - `costco-sameday-pp-cli cart familyexpeditedonboardingcart` — GraphQL query FamilyExpeditedOnboardingCart (persistedQuery) - `costco-sameday-pp-cli cart finishmycartviewlayout` — GraphQL query FinishMyCartViewLayout (persistedQuery) - `costco-sameday-pp-cli cart finishmycartviewuilayout` — GraphQL query FinishMyCartViewUILayout (persistedQuery) - `costco-sameday-pp-cli cart fixcartbasketforcheckout` — GraphQL query FixCartBasketForCheckout (persistedQuery) - `costco-sameday-pp-cli cart floatingcartmessages` — GraphQL query FloatingCartMessages (persistedQuery) - `costco-sameday-pp-cli cart getexpresscartplacementsquery` — GraphQL query GetExpressCartPlacementsQuery (persistedQuery) - `costco-sameday-pp-cli cart inlinecarteppvariant` — GraphQL query InlineCartEppVariant (persistedQuery) - `costco-sameday-pp-cli cart othersingleretailercarts` — GraphQL query OtherSingleRetailerCarts (persistedQuery) - `costco-sameday-pp-cli cart personalactivecarts` — GraphQL query PersonalActiveCarts (persistedQuery) - `costco-sameday-pp-cli cart treatmentcartmessages` — GraphQL query TreatmentCartMessages (persistedQuery) - `costco-sameday-pp-cli cart updatecartitemsmutation` — GraphQL mutation UpdateCartItemsMutation (persistedQuery) - `costco-sameday-pp-cli cart usercart` — GraphQL query UserCart (persistedQuery) - `costco-sameday-pp-cli cart usercartenriched` — GraphQL query UserCartEnriched (persistedQuery) **checkout** — Costco Same-Day checkout GraphQL operations - `costco-sameday-pp-cli checkout checkoutaisleitemmin` — GraphQL query CheckoutAisleItemMin (persistedQuery) - `costco-sameday-pp-cli checkout checkoutcmd` — GraphQL query CheckoutCmd (persistedQuery) - `costco-sameday-pp-cli checkout checkoutdraftorderinvoicev2` — GraphQL query CheckoutDraftOrderInvoiceV2 (persistedQuery) - `costco-sameday-pp-cli checkout checkoutheaderview` — GraphQL query CheckoutHeaderView (persistedQuery) - `costco-sameday-pp-cli checkout checkoutpagemeta` — GraphQL query CheckoutPageMeta (persistedQuery) - `costco-sameday-pp-cli checkout checkoutv4disclaimeronetrusttoggle` — GraphQL query CheckoutV4DisclaimerOneTrustToggle (persistedQuery) - `costco-sameday-pp-cli checkout getexpresscheckouttoggleplacements` — GraphQL query GetExpressCheckoutTogglePlacements (persistedQuery) - `costco-sameday-pp-cli checkout giftingexpandedcheckoutdetails` — GraphQL query GiftingExpandedCheckoutDetails (persistedQuery) - `costco-sameday-pp-cli checkout initializecheckout` — GraphQL query InitializeCheckout (persistedQuery) - `costco-sameday-pp-cli checkout updatebuyflowpaymentinstructionsv2` — GraphQL mutation UpdateBuyflowPaymentInstructionsV2 — attach/select payment instrument on checkout session (not - `costco-sameday-pp-cli checkout updatecheckout` — GraphQL mutation UpdateCheckout (persistedQuery). Tip changes use checkoutUpdates.tipsUpdate.tippingFields. **orders** — Costco Same-Day orders GraphQL operations - `costco-sameday-pp-cli orders customercancelselections` — GraphQL query CustomerCancelSelections — cancel-reason options UI. - `costco-sameday-pp-cli orders orderuptimer` — GraphQL query OrderUpTimer (persistedQuery) - `costco-sameday-pp-cli order start` — open a checkout session (InitializeCheckout; never charges). Cart, shop and ZIP come from the session context; `--service-type delivery|pickup` (any case). `--shop-id` is the shop id, not the store's retailer location id (a location id is refused with the right shop id named). `--dry-run` sends nothing. Prints `checkout_session_id` for `slots windows`, `order preview` and `order place` - GraphQL failures count as failures: a top-level `errors` array or a `*Error` / `*ErrorResponse` result type gives `success: false` and a non-zero exit, for generated commands and `order tip` alike **products** — Costco Same-Day products GraphQL operations - `costco-sameday-pp-cli products autosuggestions --query ` — search-box suggestions (persisted-query POST; shop from the session context) - `costco-sameday-pp-cli products itemcardsizesearchvariant` — GraphQL query ItemCardSizeSearchVariant (persistedQuery) - `costco-sameday-pp-cli products itemdetaildata` — GraphQL query ItemDetailData (persistedQuery) - `costco-sameday-pp-cli products itemdetailfeaturedproductlist` — GraphQL query ItemDetailFeaturedProductList (persistedQuery) - `costco-sameday-pp-cli products itemdetailsrecommendationsplacements` — GraphQL query ItemDetailsRecommendationsPlacements (persistedQuery) - `costco-sameday-pp-cli products itemdetailsretailerproduct` — GraphQL query ItemDetailsRetailerProduct (persistedQuery) - `costco-sameday-pp-cli products itemdetailsupplementalfields` — GraphQL query ItemDetailSupplementalFields (persistedQuery) - `costco-sameday-pp-cli products itemdetailsv2flags` — GraphQL query ItemDetailsV2Flags (persistedQuery) - `costco-sameday-pp-cli products itemdetailsv4` — GraphQL query ItemDetailsV4 (persistedQuery) - `costco-sameday-pp-cli products itemdetailviewlayout` — GraphQL query ItemDetailViewLayout (persistedQuery) - `costco-sameday-pp-cli products items` — GraphQL query Items (persistedQuery) - `costco-sameday-pp-cli products klarnaosmitemdetails` — GraphQL query KlarnaOSMItemDetails (persistedQuery) - `costco-sameday-pp-cli products postaddtocartsearchlayoutquery` — GraphQL query PostAddToCartSearchLayoutQuery (persistedQuery) - `costco-sameday-pp-cli products searchfacets` — GraphQL query SearchFacets (persistedQuery) - `costco-sameday-pp-cli products searchresultsplacements --query ` — product search with prices (same persisted-query POST as `search`; only --query and --limit are used) - `costco-sameday-pp-cli products viewlayoutsearchresults` — GraphQL query ViewLayoutSearchResults (persistedQuery) **retailer** — Costco Same-Day retailer GraphQL operations - `costco-sameday-pp-cli retailer currentretailer` — GraphQL query CurrentRetailer (persistedQuery) - `costco-sameday-pp-cli retailer landingretailermetas` — GraphQL query LandingRetailerMetas (persistedQuery) **session** — Costco Same-Day session GraphQL operations - `costco-sameday-pp-cli session complementaryproductitems` — GraphQL query ComplementaryProductItems (persistedQuery) - `costco-sameday-pp-cli session getcobrandcreditcardoffermutation` — GraphQL mutation GetCobrandCreditCardOfferMutation (persistedQuery) **slots** — Costco Same-Day slots GraphQL operations - `costco-sameday-pp-cli slots etas` — earliest delivery/pickup ETA, fee and label for a ZIP (read-only; `--as auto|member|guest`, `--service all|delivery|pickup`); exits non-zero with partial output if an ETA query fails; use this to answer "is Same-Day available at ZIP X" - `costco-sameday-pp-cli slots availableservices` — checkout service picker; empty outside checkout (stderr warning and JSON `note` point to `slots etas`) - `costco-sameday-pp-cli slots windows --checkout-session-id ` — delivery windows and savings labels for an open checkout (read-only; tokens hidden unless `--show-tokens`) - `costco-sameday-pp-cli slots pick --checkout-session-id --index N` — choose a window (UpdateCheckout; refuses without `--yes`, `--dry-run` previews; never places the order; a rejected update prints `updated: false` and exits non-zero). Ask the user before passing `--yes` - `costco-sameday-pp-cli address list` — saved address ids plus a masked label (read-only; the street is never printed). `cart cartsignaledeta` auto-fills `--address-id` (saved address matching the ZIP) and `--subtotal` (cart total) - `costco-sameday-pp-cli slots slotcampaignplacement` — GraphQL query SlotCampaignPlacement (persistedQuery) ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash costco-sameday-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. The index covers sign-in, session, search, cart, slots and order commands. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Auth Setup This CLI uses a Costco Same-Day browser session. One-step sign-in (opens a headed Chrome/Chromium window in a CLI-owned profile; the user signs in; the CLI captures only the Same-Day session cookies and closes the window): ```bash costco-sameday-pp-cli auth login ``` It never reads the user's main Chrome cookie store or Chrome Safe Storage. The user must complete sign-in themselves; do not script the sign-in form. Fallbacks: ```bash costco-sameday-pp-cli auth login --chrome ``` Or import an existing browser capture: ```bash costco-sameday-pp-cli auth login --cookies-file storage-state.json ``` `--cookies-file` accepts Playwright storage-state JSON or a raw `Cookie:` header text file. Use `--cookies-file -` to read the header from stdin (for example `pbpaste | costco-sameday-pp-cli auth login --cookies-file -`). Stdin also accepts DevTools "Copy request headers" or "Copy as cURL (bash)" output from a sameday.costco.com request. Only the `__Host-instacart_sid` session cookie is required; it is HttpOnly, so copy it from DevTools Network rather than `document.cookie`. Other Same-Day cookies are kept when present. Add `--diagnose` to check a paste without saving anything: it prints only the byte count, detected format, parse stage, cookie names, and whether `__Host-instacart_sid` is present, never values. The Chrome path requires a cookie extraction tool (`pycookiecheat` via pip, or `cookies` via Homebrew). Run `costco-sameday-pp-cli doctor` to verify setup. `auth status --json` and `doctor --json` report `session` (valid / guest / expired, from a live read-only probe), `account_type` (`member`, `guest`, `unknown`) and `session_expires`. Cookie names only are reported, never values. Troubleshooting for agents: - Session expired or missing (exit 4, "session is missing or expired"): ask the user to run `costco-sameday-pp-cli auth login` and sign in. - "Costco is rate-limiting sign-in" (429 from signin.costco.com): stop; tell the user to wait about 15-30 minutes before one more `auth login`. Do not retry in a loop. - Keychain denied ("Chrome Safe Storage") on `auth login --chrome`: suggest `auth login` (browser window, no keychain) or `pbpaste | costco-sameday-pp-cli auth login --cookies-file -` from DevTools "Copy as cURL (bash)". - `account_type: guest`: results are not the member account; ask the user to run `auth login`. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash costco-sameday-pp-cli account gethouseholdbyuser --operation-name GetHouseholdByUser --agent ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `COSTCO_SAMEDAY_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `COSTCO_SAMEDAY_CONFIG_DIR`, `COSTCO_SAMEDAY_DATA_DIR`, `COSTCO_SAMEDAY_STATE_DIR`, `COSTCO_SAMEDAY_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `COSTCO_SAMEDAY_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `costco-sameday-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "costco-sameday": { "command": "costco-sameday-pp-mcp", "env": { "COSTCO_SAMEDAY_HOME": "/srv/costco-sameday" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `COSTCO_SAMEDAY_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `COSTCO_SAMEDAY_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash costco-sameday-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "sourc