--- name: pp-homedepot description: "Search products, manage your cart, and retrieve purchases using your own signed-in session. Trigger phrases: `search Home Depot products`, `show my Home Depot cart`, `find my Home Depot purchases`, `use homedepot`, `run homedepot`." author: "Greg Mushen" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - homedepot-pp-cli install: - kind: go bins: [homedepot-pp-cli] module: github.com/mvanhorn/printing-press-library/library/commerce/homedepot/cmd/homedepot-pp-cli --- # Home Depot — Printing Press CLI ## Local build and publication status This CLI is currently a local build. Public installation, release downloads and pre-built bundles below become available only after library publication. ```bash go build -o ./build/stage/bin/homedepot-pp-cli ./cmd/homedepot-pp-cli go build -o ./build/stage/bin/homedepot-pp-mcp ./cmd/homedepot-pp-mcp ``` ## Prerequisites: Install the CLI This skill drives the `homedepot-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 homedepot --cli-only ``` 2. Verify: `homedepot-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.9 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/homedepot/cmd/homedepot-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. Read products and past purchases through direct HTTP. Cart changes target explicit items and return a verified resulting cart. ## When to Use This CLI Use for signed-in Home Depot product searches, cart changes, and purchase history. ## Anti-triggers Do not use this CLI for: - Checkout and payment - Delivery scheduling - Bulk inventory collection ## Unique Capabilities ### Signed-in shopping - **`cart add`** — Reports the resulting cart after the requested change. _Reports the resulting cart after the requested change._ ```bash homedepot-pp-cli cart add 100001123 --store 4706 --dry-run --agent ``` - **`cart update`** — Updates one explicit cart line and confirms its quantity. _Updates one explicit cart line and confirms its quantity._ ```bash homedepot-pp-cli cart update sample-line --quantity 2 --dry-run --agent ``` - **`products search`** — Returns concrete products and marks absent availability unknown. _Returns concrete products and marks absent availability unknown._ ```bash homedepot-pp-cli products search pencils --agent ``` - **`orders list`** — Lists orders across bounded pages in the requested date range. _Lists orders across bounded pages in the requested date range._ ```bash homedepot-pp-cli orders list --agent ``` - **`auth status`** — Distinguishes stored session presence from a verified signed-in read. _Distinguishes stored session presence from a verified signed-in read._ ```bash homedepot-pp-cli auth status --agent ``` ## HTTP Transport This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls. ## Command Reference **federation-gateway** — Developer transport for observed cart operations; use cart commands for shopping. - `homedepot-pp-cli federation-gateway` — Replay an observed Home Depot GraphQL request. **oms** — Developer transport for observed order requests; use orders commands for purchases. - `homedepot-pp-cli oms get-order-details` — Read one purchase with a complete observed body. - `homedepot-pp-cli oms list-order-history` — Read purchase history with a complete observed body. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash homedepot-pp-cli which "search products" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. 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. ## Recipes ### Find products ```bash homedepot-pp-cli products search pencils --agent --select item_id,name,price ``` Return only shopping identifiers, names and prices. ### Inspect cart ```bash homedepot-pp-cli cart show --agent ``` Get line IDs before changing quantities. ### Find recent purchases ```bash homedepot-pp-cli orders list --agent ``` Return recent order references. ## Auth Setup Sign in to homedepot.com in Safari, then run homedepot-pp-cli auth import. For Chrome, run homedepot-pp-cli auth login --chrome. Session cookies preserve domain, path and expiry in a private local file (0600 on POSIX; owner-only ACL on Windows) at ~/.local/share/homedepot-pp-cli/cookies.json, or the directory selected by --home. An absolute HOMEDEPOT_COOKIE_FILE selects another private file. Imports verify a protected request before replacing the stored session. Run homedepot-pp-cli auth status --verify for a live check; auth logout removes the stored session. No developer API key is needed. Run `homedepot-pp-cli doctor` to verify setup. ## 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 homedepot-pp-cli products search hammer --agent ``` - **Previewable** — shopper `--dry-run` reports the skipped action without network access; generated API commands can preview HTTP requests - **Live shopping** — product search, cart and purchase-history commands use live HTTP; the local store supports agent learning, not offline shopping - **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 Shopper commands (`products`, `cart`, `orders`, and custom auth status) return direct values with `--json`. With `--agent`, normal shopper results use a provenance envelope: ```json { "meta": {"source": "live", "reason": "..."}, "results": "" } ``` Parse `.results` in agent mode. Shopper dry runs instead return `{ "dry_run": true, "action": "...", "would": "..." }`, including with `--agent`; they do not construct or display an HTTP request. Local learning commands and generated API commands have their own output shapes, shown in their help. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `HOMEDEPOT_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `HOMEDEPOT_CONFIG_DIR`, `HOMEDEPOT_DATA_DIR`, `HOMEDEPOT_STATE_DIR`, `HOMEDEPOT_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `HOMEDEPOT_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 `homedepot-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": { "homedepot": { "command": "homedepot-pp-mcp", "env": { "HOMEDEPOT_HOME": "/srv/homedepot" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `HOMEDEPOT_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 `HOMEDEPOT_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, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) homedepot-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. 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", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "homedepot-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `homedepot-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesizes a playbook candidate from this session's journal - you do not need to record one by hand. ``` Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a `Results[]` hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping `mismatches`; pass `--debug-mismatches` only when investigating cold-start surprises. Candidate judgment details: `learnings confirm ` prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. `learnings reject ` tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; `homedepot-pp-cli learnings candidates` lists the full open set. Graceful degradation: if `learnings confirm` is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol. ### Step 3: always read `warnings` - `low_confidence`: row exists at `confidence<2`. Treat as a hint, not a skip-discovery hit. - `resource_not_in_store`: the local store doesn't have the resource the learning points at. The match validator couldn't classify entities — direct-fetch and re-evaluate. - `cross_alias_match` (per-result): the row was taught under a different alias and matched the live query's canonical via `entity_lookups` (e.g., a "USA" teach satisfying a "United States" recall). Trust the resource_id. - `similar_shape_different_entity:` (top-level): a structurally matching row exists but its canonical entity differs from the live query's. Treated as cold start; the warning carries the conflicting canonical as a hint, but the row is NOT promoted into Results. - `ambiguous_alias` (top-level): a single query entity resolved to multiple canonicals (e.g., "Cards" → Arizona Cardinals + St. Louis Cardinals). Surface the ambiguity from context before committing to a resource. - `candidates_present` (top-level): the envelope carries a `candidates` section. Handle it via the candidates branch in Step 2 before anything else. - Top-level `no_learnings_for_query_family`: the table had no rows above the Jaccard floor. Pure cold start. ### Step 4: `teach &` after finalizing your response - always The following learning recipes are templates. Replace placeholders with discovered resource IDs and real file paths before execution. Teaching is unconditional. After resolving a query the store could not answer, background-teach the final resource mapping - no call-count threshold, no judging whether it was "worth" learning. The teach is the anchor of the loop: it triggers playbook synthesis for a family without a playbook, and same-referent phrasings fold into one family so near-duplicate teaches do not fragment the store. Fire it after assembling your user-facing response but BEFORE emitting it, with a shell `&` so the call returns immediately. Pass the query the same way as recall — argv/MCP, or file-then-`$QUERY`. Do not splice the question into the command text: ```text QUERY=$(cat /path/to/question.txt) homedepot-pp-cli teach --query "$QUERY" --resource-type --resource --resource # (append shell `&` to background it) ``` Silent on success. Errors only land in `teach.log` under the resolved state dir. Teach the **most specific** resource - if the user asked a broad question and you walked through parent records to find the specific answer, teach the leaf id, not the parent. The CLI uses seeded `entity_lookups` for cross-alias resolution at recall time, so a teach under one alias (e.g., "Niners") satisfies future queries under another alias (e.g., "49ers", "San Francisco") automatically. PII rule: teach the structural question with identifiers stripped - never include names, emails, phone numbers, account ids, or other personal identifiers in taught queries or notes. The CLI scans teach queries for obvious email/phone shapes and warns, but does not block; strip before teaching rather than relying on the warning. ### Step 5: playbooks - optional flags, automatic synthesis You do not need to decide whether a session "deserves" a playbook: a teach on a family without one auto-synthesizes a `playbook_candidate` from the session's journal, and the next session judges it via confirm/reject. Attach explicit playbook flags only when you already hold choreography worth recording verbatim - workarounds the CLI didn't surface (silently-dropped flags, undocumented params, pagination tricks, payload gotchas). Prefer the **integrated one-call form** - record the resource learning and the playbook in the same `teach` invocation: ```text # Common case: record both the resource learning AND the playbook in one call. QUERY=$(cat /path/to/question.txt) homedepot-pp-cli teach \ --query "$QUERY" \ --resource \ --playbook-file ~/playbooks/.json \ --playbook-notes-file ~/playbooks/-notes.md # (append shell `&` to background it) # Alternate: