--- name: pp-clarify description: "Every Clarify API operation as a typed command, plus the morning briefing, meeting prep, and pipeline analytics the autonomous CRM knows about but cannot run. Trigger phrases: `prep me for my next meeting`, `which deals are going stale`, `add this lead to Clarify`, `pull the transcript from my last call`, `which meetings did I never follow up on`, `use clarify`, `run clarify`." author: "Isaac Marks" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - clarify-pp-cli install: - kind: go bins: [clarify-pp-cli] module: github.com/mvanhorn/printing-press-library/library/sales-and-crm/clarify/cmd/clarify-pp-cli --- # Clarify — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `clarify-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 clarify --cli-only ``` 2. Verify: `clarify-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/sales-and-crm/clarify/cmd/clarify-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. Clarify auto-builds your CRM from email, calendar, and meetings, but its only programmatic surfaces are a hosted MCP server and raw curl. This CLI covers all 75 API operations with the api-key auth scheme and JSON:API envelope handled natively, keeps a local SQLite mirror with transcript full-text search, and adds commands like prep, brief, followup, and dossier that no Clarify surface offers. ## When to Use This CLI Use this CLI whenever a task touches Clarify CRM data from a terminal or agent: querying or updating people, companies, deals, meetings, and tasks; bulk imports; pulling meeting transcripts; or answering pipeline questions (stale deals, velocity, follow-up gaps) that Clarify's own API cannot express. It is the offline-capable alternative to Clarify's hosted MCP server. ## Anti-triggers Do not use this CLI for: - Do not use this CLI to send email or run outreach sequences; Clarify is the CRM of record, not a sending tool. - Do not use it for other CRMs (Salesforce, HubSpot, Close) — it only speaks to api.clarify.ai. - Do not use it to transcribe new meetings; it retrieves transcripts Clarify has already produced. - Do not use dynamic-list SQL commands to run arbitrary analytics upstream; use the local search and analytics commands against the mirror instead. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Rituals the CRM knows but cannot run - **`prep`** — One command before a call: the meeting's attendees, their company, open deals, and transcript excerpts from past meetings with that company. _Reach for this when the task is preparing for one specific upcoming meeting rather than fetching raw records. Requires a synced local mirror (sync --resources resources --path-context object= first)._ ```bash clarify-pp-cli prep --next --agent ``` - **`brief`** — Start-of-day overview: today's meetings joined to their companies, open deals, and yesterday's record activity, on one screen. _Use this for a whole-day overview; use prep for a single meeting. Requires a synced local mirror (sync --resources resources --path-context object= first)._ ```bash clarify-pp-cli brief --json ``` - **`followup`** — The dropped-ball list: meetings with no subsequent activity, comment, or task on the linked deal or company. _Run it after a busy week to find meetings that never got a follow-up; --no-deal also surfaces companies with meetings but no open deal. Requires a synced local mirror (sync --resources resources --path-context object= first)._ ```bash clarify-pp-cli followup --since 7d --json ``` ### Pipeline analytics the API does not have - **`stale`** — Open deals with no activity in N days, grouped by pipeline stage. _The Monday pipeline-review question answered in one command instead of a CSV export. Requires a synced local mirror (sync --resources resources --path-context object= first)._ ```bash clarify-pp-cli stale --days 14 --json ``` - **`velocity`** — Per-stage dwell time and stage-to-stage conversion counts, accrued from a local stage-history table across repeated runs (the first run reports the current stage distribution). _Answers 'how long do deals sit in each stage' without exporting anything to a spreadsheet. Requires a synced local mirror; dwell and conversion analytics build up as you re-run sync and velocity over time._ ```bash clarify-pp-cli velocity --json ``` - **`dupes`** — Finds likely duplicate people or companies by shared email, domain, or normalized name, and prints ready-to-run merge commands. _Weekly hygiene sweep for auto-built CRM data; each finding comes with the exact merge invocation to fix it. Requires a synced local mirror (sync --resources resources --path-context object= first)._ ```bash clarify-pp-cli dupes --type person --json ``` ### Agent-native plumbing - **`dossier`** — A complete background bundle on any record: fields, relationships, activities, comments, and related meetings with transcript references, in one compact payload. _The one-call answer to 'tell me everything about this person/company/deal' — use prep instead when the subject is a specific upcoming meeting. Requires a synced local mirror._ ```bash clarify-pp-cli dossier 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71 --agent --select record,related ``` ## Command Reference **campaigns** — Manage campaigns **comments** — Manage comments - `clarify-pp-cli comments create` — Creates a comment on a record. - `clarify-pp-cli comments delete` — Permanently deletes a comment. - `clarify-pp-cli comments get` — Returns a single comment by its ID. - `clarify-pp-cli comments update` — Replaces the body of an existing comment. Only the comment’s author may edit it. Returns the updated comment. **layouts** — Manage layouts - `clarify-pp-cli layouts get-by-id` — Returns a single layout by its ID. - `clarify-pp-cli layouts update` — Replaces the layout’s `tree` and returns the updated layout. **lists** — Manage lists - `clarify-pp-cli lists ` — Returns every list across all object types in the workspace as a paginated JSON:API collection. **meetings** — Manage meetings **objects** — Manage objects **schemas** — Manage schemas - `clarify-pp-cli schemas create-custom-object` — Creates a new custom object type in the workspace and returns its generated JSON Schema. - `clarify-pp-cli schemas delete-custom-object` — Deletes a custom object type and all of its records. - `clarify-pp-cli schemas get` — Returns every object schema in the workspace as a cursor-paginated list of JSON:API resources. - `clarify-pp-cli schemas patch-enum-field-values` — Adds or removes options on enum (single- and multi-select) fields for one object type. - `clarify-pp-cli schemas update-entity` — Replaces the full JSON Schema for an object type. **settings** — Manage settings - `clarify-pp-cli settings delete-workspace` — Removes the stored value of a workspace setting so it falls back to its default. - `clarify-pp-cli settings read-all-workspace` — Returns every workspace setting keyed by name, with defaults applied for settings the workspace has not overridden. - `clarify-pp-cli settings read-workspace` — Returns the value of a single workspace setting; the default value when the workspace has not overridden it. - `clarify-pp-cli settings write-workspace` — Sets the value of a workspace setting by key. **users** — Manage users - `clarify-pp-cli users get` — Returns the workspace’s users as a paginated JSON:API list. Each user includes their roles. - `clarify-pp-cli users get-workspaces` — Returns a single workspace user as a JSON:API resource, including their roles and the time they were last active. **workflows** — Manage workflows - `clarify-pp-cli workflows create` — Creates a workflow from a trigger and a set of blocks. - `clarify-pp-cli workflows delete` — Deletes a workflow. The deletion is applied asynchronously and the response body is empty. This cannot be undone. - `clarify-pp-cli workflows get` — Returns the workspace’s workflows as an offset-paginated list of JSON:API resources. - `clarify-pp-cli workflows get-workspaces` — Returns a single workflow as a JSON:API resource - `clarify-pp-cli workflows update` — Applies a partial update to a workflow: only the fields present in `attributes` are changed. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash clarify-pp-cli which "" ``` `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 ### Prep for your next call ```bash clarify-pp-cli prep --next --agent ``` Attendees, their company, open deals, and past-transcript excerpts in one compact payload. ### Find the week's dropped balls ```bash clarify-pp-cli followup --since 7d --json ``` Meetings with no follow-up activity, comment, or task on the linked deal or company. ### Narrow a big deal query for an agent ```bash clarify-pp-cli objects resources get my-workspace deal --agent --select data.attributes.name,data.attributes.amount,data.attributes.stage ``` JSON:API responses are deep; --select with dotted paths keeps only the fields the agent needs. ### Upsert a lead by email ```bash clarify-pp-cli objects records create my-workspace person --match-on email_addresses --data-type person --data-attributes '{"name":{"first_name":"Jane","last_name":"Doe"},"email_addresses":{"items":["jane@example.com"]}}' --dry-run ``` match_on turns the insert into an upsert against the person unique field; drop --dry-run to send it. ### Weekly dupe sweep ```bash clarify-pp-cli dupes --type company --json ``` Likely duplicates by shared domain or normalized name, each with a ready-to-run merge command. ## Auth Setup Clarify authenticates with an API key sent as `Authorization: api-key ` — not a Bearer token. Create a Personal key in Clarify under Settings, API Keys, then set `CLARIFY_API_KEY` to the raw key; the CLI adds the `api-key` scheme prefix for you. Every request is scoped to a workspace slug (visible in your Clarify login URL); set it once with `CLARIFY_WORKSPACE` or the config file. Run `clarify-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. - **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 clarify-pp-cli comments get mock-value mock-value --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, and use `--ignore-missing` only when a missing delete target 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 `CLARIFY_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `CLARIFY_CONFIG_DIR`, `CLARIFY_DATA_DIR`, `CLARIFY_STATE_DIR`, `CLARIFY_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `CLARIFY_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 `clarify-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": { "clarify": { "command": "clarify-pp-mcp", "env": { "CLARIFY_HOME": "/srv/clarify" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `CLARIFY_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 `CLARIFY_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 clarify-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", "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": ["", "clarify-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 `clarify-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 -