--- name: pp-pingenerator description: "Every Pin Generator MCP tool as a typed command, with credit-safe dry runs, preflight pricing and a local spend ledger. Trigger phrases: `pin my latest blog post`, `schedule pins with Pin Generator`, `how many Pin Generator credits do I have`, `pin products from my Etsy store`, `use pingenerator`, `run pingenerator`." author: "Elizabeth Stone" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - pingenerator-pp-cli install: - kind: go bins: [pingenerator-pp-cli] module: github.com/mvanhorn/printing-press-library/library/marketing/pingenerator/cmd/pingenerator-pp-cli --- # Pin Generator — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `pingenerator-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 pingenerator --cli-only ``` 2. Verify: `pingenerator-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.10 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/marketing/pingenerator/cmd/pingenerator-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. Drive Pin Generator from scripts and agents: discover profiles and boards, turn posts or store products into pins with pin-post and pin-products, and check plans with preflight before spending. Anything that costs credits previews for free until you pass --execute. ## When to Use This CLI Use this CLI when an agent or script needs to create, schedule or automate Pinterest pins through a Pin Generator account: blog posts to pins, store products to pins, design profiles, recurring automations, and queue or credit checks. Every credit-spending command, including create-automation and run-automation-batch, prints a free preview until --execute is passed; a preview has "dry_run": true (typed tools) or "executed": false (pin-post), so check those fields before reporting that anything was scheduled. Design-profile setup and updates change account state immediately but spend no credits; use --dry-run to preview them. get_account_status, list_scheduled_pins and list_pinterest_profiles response fields were confirmed live; other tools' response fields are parsed tolerantly. ## Anti-triggers Do not use this CLI for: - Reading Pinterest analytics, impressions or saves; use a Pinterest API CLI instead - Editing or deleting a pin that is already scheduled; Pin Generator exposes no tool for it - Managing Pinterest boards directly; Pin Generator only lists and AI-creates boards during scheduling ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Credit-safe pin pipelines - **`pin-post`** — Turn a blog post URL into a scheduled Pinterest pin in one command, previewed for free before any credit is spent. _Reach for this when an agent must pin a specific post; it previews cost and skips posts this CLI already pinned (spend ledger). Use unpinned-posts to check the account's queue first._ ```bash pingenerator-pp-cli pin-post https://example.com/best-beaches --pinterest-profile myprofile --board-id 992269799088633298 --agent ``` - **`preflight`** — Price a planned batch in credits and confirm the profile, board and design profile exist before spending anything. _Run this before any --execute batch so a bad board ID or low balance fails free._ ```bash pingenerator-pp-cli preflight --pinterest-profile myprofile --board-id 992269799088633298 --tool generate-and-schedule-ai-pin --count 5 --agent ``` - **`pin-products`** — Turn a connected store's products into a batch of scheduled pins, skipping products this CLI already pinned (spend ledger). _Use this for e-commerce pinning in bulk; the dry run shows the total credit cost first._ ```bash pingenerator-pp-cli pin-products --store-id store_123 --search linen --pinterest-profile myprofile --board-id 992269799088633298 --agent ``` ### Queue and coverage insight - **`unpinned-posts`** — List sitemap posts that have no scheduled pin and no ledgered spend. _Start a blog-to-pins run here so only new posts get pinned._ ```bash pingenerator-pp-cli unpinned-posts --website-url https://example.com --limit 50 --agent ``` - **`ledger`** — See every credit-spending call this CLI executed, including unconfirmed ones that may have spent, with totals by tool and time window. _Check this after an agent run, or before a retry; an unconfirmed entry means check list-scheduled-pins before trying again._ ```bash pingenerator-pp-cli ledger --since 7d --agent ``` - **`queue-gaps`** — Find empty and overloaded days in the scheduled-pin queue, per board. _Use this to keep a steady posting cadence across client accounts._ ```bash pingenerator-pp-cli queue-gaps --days 14 --per-day 5 --agent ``` - **`credit-runway`** — Estimate weekly credit burn from active automations and how many days of credit remain. _Run weekly for accounts with automations so batches do not fail on an empty balance._ ```bash pingenerator-pp-cli credit-runway --agent ``` `--ca-cert`, `PINGENERATOR_CA_CERT`, or `ca_cert` adds a PEM CA bundle to the system trust roots. `--tls-server-name`, `PINGENERATOR_TLS_SERVER_NAME`, or `tls_server_name` is the name checked against the certificate. Precedence is flag, then environment, then the config file. A config file other users can change does not supply these settings. `doctor` reports the trust in use and names the setting that fixes a chain or hostname failure. ## Command Reference **mcp** — Raw Pin Generator MCP JSON-RPC access (escape hatch for tools not yet typed) - `pingenerator-pp-cli mcp` — Send a raw JSON-RPC request to the Pin Generator MCP endpoint. **credit-runway** - `pingenerator-pp-cli credit-runway` — Estimate weekly credit burn from active automations and how many days of credit remain. **ledger** - `pingenerator-pp-cli ledger` — See every credit-spending call this CLI executed, including unconfirmed ones that may have spent, with totals by tool and time window. **pin-post** - `pingenerator-pp-cli pin-post` — Turn a blog post URL into a scheduled Pinterest pin in one command, previewed for free before any credit is spent. **pin-products** - `pingenerator-pp-cli pin-products` — Turn a connected store's products into a batch of scheduled pins, skipping products this CLI already pinned (spend ledger). **preflight** - `pingenerator-pp-cli preflight` — Price a planned batch in credits and confirm the profile, board and design profile exist before spending anything. **queue-gaps** - `pingenerator-pp-cli queue-gaps` — Find empty and overloaded days in the scheduled-pin queue, per board. **unpinned-posts** - `pingenerator-pp-cli unpinned-posts` — List sitemap posts that have no scheduled pin and no ledgered spend. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash pingenerator-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. `--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 ### Pin every new post ```bash pingenerator-pp-cli unpinned-posts --website-url https://example.com --agent --select unpinned.url,unpinned.title ``` List posts with no scheduled, queued or ledgered pin, then pass each URL to pin-post. ### Price before you spend ```bash pingenerator-pp-cli preflight --pinterest-profile myprofile --board-id 992269799088633298 --tool generate-and-schedule-ai-pin --count 5 ``` Shows the credit range and checks the board exists, spending nothing. ### Trim template output ```bash pingenerator-pp-cli list-templates --agent --select templates.name,templates.style ``` Keeps only template names and styles from a large response. ### Audit agent spending ```bash pingenerator-pp-cli ledger --since 7d --agent ``` Every executed spend this week with credit totals; unconfirmed rows may have spent and should be checked in list-scheduled-pins before a retry. ## Auth Setup Pin Generator's account access key (pingenerator.com/profile, API access key) authorizes the MCP endpoint as a Bearer token. Set PINGENERATOR_ACCESS_KEY. The web app's richer REST API needs a Firebase login session and is not used. Run `pingenerator-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). `--csv` prefixes `'` on a cell or header key that starts with `=`, `+`, `-`, `@`, tab, CR, or LF (fullwidth `＝＋－＠` too) so a spreadsheet does not run it as a formula; a plain signed number such as `-5` or `+2.5e3` is unchanged. - `--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 pingenerator-pp-cli mcp --jsonrpc 2.0 --agent ``` - **Previewable** — `--dry-run` shows the request without sending - **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 ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `PINGENERATOR_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `PINGENERATOR_CONFIG_DIR`, `PINGENERATOR_DATA_DIR`, `PINGENERATOR_STATE_DIR`, `PINGENERATOR_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `PINGENERATOR_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 `pingenerator-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": { "pingenerator": { "command": "pingenerator-pp-mcp", "env": { "PINGENERATOR_HOME": "/srv/pingenerator" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `PINGENERATOR_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 `PINGENERATOR_HOME`, or `doctor` will not find credentials left under the former root. Local data is unencrypted and relies on OS account permissions plus disk encryption. GET responses are cached for five minutes under the cache dir. `local-data purge` previews what it would erase (store files, response cache, learn journal) and deletes only with `--yes`; it is not exposed over MCP. `PINGENERATOR_NO_LOCAL_DATA=1` disables the response cache and store writes, turns `auto` reads into live reads, and blocks `sync`. ## 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) pingenerator-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": ["", "pingenerator-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 `pingenerator-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; `pingenerator-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` (pe