pp-crestron

# Crestron — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `crestron-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 crestron --cli-only ``` 2. Verify: `crestron-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.5 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/devices/crestron/cmd/crestron-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. Crestron.com has no public API and no way to ask a question across more than one product at a time. This CLI mirrors the product catalog, the documentation library, and the firmware release history into local SQLite, then answers the questions integrators actually have: what firmware covers my installed models, what changed between two versions, which parts are discontinued and what replaced them. Sign in and it also unlocks release notes and firmware downloads. ## When to Use This CLI Use this CLI for any question about Crestron hardware that lives on Crestron.com rather than on a device: what a product is, what its specifications are, which firmware version is current, what changed in a release, which documentation exists for a model, and whether a part has been discontinued. It is especially strong for questions spanning many models at once, which the website cannot answer at all. ## Anti-triggers Do not use this CLI for: - Do not use this CLI to control, configure, or communicate with Crestron hardware on a network — it never talks to devices. Use Crestron Toolbox or the Crestron EDK PowerShell modules for that. - Do not use this CLI to push or install firmware onto a control processor or touch panel; it only downloads the files. - Do not use this CLI for Crestron Home smart-home control such as lights, shades, or scenes. - Do not use this CLI to obtain dealer pricing — Crestron's public pricing endpoint returns no data for most models. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Fleet lifecycle intelligence - **`fleet status`** — Check every model in your installed fleet against current firmware in one command. _Reach for this instead of checking models one at a time; it also catches releases that a per-model search would miss because the release is titled under a sibling model._ ```bash crestron-pp-cli fleet status --file fleet.txt --agent ``` - **`lifecycle`** — Report whether a model is still sellable and trace its replacement chain. _Reach for this when triaging an as-built list to find which parts can still be ordered and what replaced the rest._ ```bash crestron-pp-cli lifecycle UC-FCM-Z --agent ``` ### Firmware knowledge base - **`search`** — Search every firmware release note and change log at once for a term. _Use this to answer 'which version fixed X' without opening a dozen version pages._ ```bash crestron-pp-cli search "HDCP" --type firmware_release --agent ``` - **`firmware diff`** — Show what changed between two firmware versions for a model. _Pick this when deciding whether an upgrade is worth scheduling on a live site._ ```bash crestron-pp-cli firmware diff DM-NVX-384 7.3.5149.23092 7.4.0255.22319 --agent ``` ### Design and submittal workflow - **`submittal`** — Download every documentation asset for a list of models into per-model folders with a coverage report. _Use this to assemble a CSI submittal package in one step instead of hundreds of individual downloads._ ```bash crestron-pp-cli submittal DM-NVX-384 --agent ``` - **`specs compare`** — Compare two models field by field across the full specification table. _Use this when choosing between sibling models in the same series, which often differ in only a few spec rows._ ```bash crestron-pp-cli specs compare DM-NVX-360 DM-NVX-363 --agent ``` ## Command Reference **account** — Crestron.com sign-in state - `crestron-pp-cli account` — Check whether the stored Crestron.com session is still signed in **asset** — Download Crestron documentation and firmware files - `crestron-pp-cli asset <guid> <filename>` — Download a public documentation asset such as a spec sheet, manual, certificate, CAD drawing, or Revit family **catalog** — Browse the Crestron product catalog taxonomy - `crestron-pp-cli catalog category` — Open a catalog category page and read its subcategories and product counts - `crestron-pp-cli catalog products` — List the products in a catalog category (needs the category's document and node ids) - `crestron-pp-cli catalog tree` — List every product category path in the catalog **firmware** — Crestron firmware and software releases - `crestron-pp-cli firmware release` — Read a firmware release page including its version, date, release notes, and change log (requires sign-in) - `crestron-pp-cli firmware search` — Find firmware and software releases for a model or family **product** — Look up Crestron products, specifications, and their documentation - `crestron-pp-cli product accessories` — List optional accessories for a product - `crestron-pp-cli product page` — Fetch a product detail page including its JSON-LD, specification table, and document id - `crestron-pp-cli product replacements` — List replacement products for a discontinued item - `crestron-pp-cli product resources` — List every documentation asset for a product by its document id - `crestron-pp-cli product variants` — List the member models of a product series **resource** — Search Crestron's documentation and firmware resource library - `crestron-pp-cli resource` — Search spec sheets, manuals, firmware, certificates, and drawings ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash crestron-pp-cli which "<capability in your own words>" ``` `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. ## Recipes ### Audit a whole fleet for firmware currency ```bash crestron-pp-cli fleet status --file fleet.txt --agent --select model,installed,latest,days_behind ``` Reads a plain list of model numbers and reports which are behind, resolving family-scoped releases so nothing is missed. ### Find which firmware version fixed something ```bash crestron-pp-cli search "Dante" --type firmware_release --limit 10 --agent ``` Full-text searches every synced release note and change log at once. ### Narrow a verbose spec table to the fields you care about ```bash crestron-pp-cli specs show DM-NVX-360 --agent --select sections.name,sections.rows.key,sections.rows.value ``` Specification tables run to dozens of rows across a dozen sections; selecting dotted paths keeps agent context small. ### Assemble a submittal package for a project ```bash crestron-pp-cli submittal DM-NVX-384 TSW-1070 CP4N --out ./submittal --agent ``` Downloads every documentation asset for each model into its own folder and reports which asset classes were missing. ### Triage an as-built list for discontinued parts ```bash crestron-pp-cli lifecycle UC-FCM-Z --agent --select model,status,replaced_by ``` Reports sellable status and the successor chain so a refresh estimate can be priced. ## Auth Setup Most of this CLI works with no account at all: the product catalog, specifications, spec sheets, manuals, certificates, CAD and Revit files, and firmware version numbers and release dates are all public. A Crestron account unlocks two more things — firmware release notes and the firmware binaries themselves. Run `crestron-pp-cli auth login --chrome` and the CLI imports your existing Crestron.com session cookies straight from Chrome; it never asks for or stores your password. Run `crestron-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **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 crestron-pp-cli asset mock-value mock-value --agent --select id,name,status ``` - **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 - **Read-only** — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests ### 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": <data> } ``` 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 <dir>` for one invocation, or set `CRESTRON_HOME=<dir>` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `CRESTRON_CONFIG_DIR`, `CRESTRON_DATA_DIR`, `CRESTRON_STATE_DIR`, `CRESTRON_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `CRESTRON_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 `crestron-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": { "crestron": { "command": "crestron-pp-mcp", "env": { "CRESTRON_HOME": "/srv/crestron" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `CRESTRON_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 `CRESTRON_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 crestron-pp-cli recall "<user's question>" --agent ``` The response envelope: ```json { "query": "...", "normalized": "<normalized form>", "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": ["<trial command>", "crestron-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } }, "notes": "<workarounds + gotchas for this query family>" }, "notes": "<duplicate surface for non-playbook callers>" } ``` 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 <id>` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject <id>`. -> 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 `crestron-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 <id>` prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. `learnings reject <id>` tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; `crestron-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.