pp-kit

name	pp-kit
description	Printing Press CLI for Kit.
author	Cathryn Lavery
license	Apache-2.0
argument-hint	<command> [args] | install cli|mcp
allowed-tools	Read Bash
metadata	{"openclaw":{"requires":{"bins":["kit-pp-cli"]},"install":[{"kind":"go","bins":["kit-pp-cli"],"module":"github.com/mvanhorn/printing-press-library/library/marketing/kit/cmd/kit-pp-cli"}]}}

Kit — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the kit-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:

   npx -y @mvanhorn/printing-press-library install kit --cli-only
   

2. Verify: kit-pp-cli --version
3. Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

go install github.com/mvanhorn/printing-press-library/library/marketing/kit/cmd/kit-pp-cli@latest

If --version reports "command not found" after install, the install step did not put the binary on $PATH. Do not proceed with skill commands until verification succeeds.

Agentic Kit Workflows

Prefer these read-only workflows before raw endpoint mirrors when the user asks for planning, diagnosis, audit, support, or account context:

• kit-pp-cli workflow creator-snapshot --agent — one operating snapshot with account, growth, audience, content, webhook, and broadcast stats.
• kit-pp-cli workflow audience-health --agent — subscriber status counts, growth stats, and largest tags by subscriber count.
• kit-pp-cli workflow content-inventory --agent — sequences, sequence emails, snippets, forms, email templates, and recent broadcast stats for content planning.
• kit-pp-cli workflow subscriber-lookup --email <email> --agent — one subscriber profile with custom fields, tags, attribution, and email stats.

Use raw endpoint commands when the user needs a specific CRUD operation, exact endpoint parity, pagination beyond a workflow limit, or a write operation. These workflows call real Kit v4 endpoints; they are not cached summaries or mock payloads.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Creator operations

• workflow creator-snapshot — One-call read-only operating snapshot for Kit account, growth, audience, content, webhooks, and broadcast stats.

  Use this first when an agent needs current creator-account context without manually fanning out across endpoint mirrors.

  kit-pp-cli workflow creator-snapshot --agent
  

Audience intelligence

• workflow audience-health — Read-only subscriber status counts, recent growth stats, and largest tags by subscriber count.

  Use this before list cleaning, segmentation, or campaign planning to avoid multiple fragile subscriber and tag calls.

  kit-pp-cli workflow audience-health --agent
  

• workflow subscriber-lookup — Read-only subscriber dossier by email or id with profile, custom fields, tags, attribution, and email stats.

  Use this for support, segmentation checks, and personalization debugging before raw subscriber endpoint calls.

Content planning

• workflow content-inventory — Read-only inventory of sequences, sequence emails, snippets, forms, templates, and recent broadcast stats.

  Use this for content audits and planning instead of separately listing each Kit content surface.

  kit-pp-cli workflow content-inventory --agent
  

Trends and ranking

• growth-trends — Correlates account growth stats with broadcast performance over a date range. Optionally caches results via the typed UpsertBroadcastsStats write path.
• tag-performance — Ranks tags by subscriber count with share-of-total percentages; optional --subscriber-query uses SearchSubscribers to narrow to a segment.

MCP intent tools

Four first-class MCP intent tools expose the workflow commands with typed input schemas and read-only annotations. Use these via the MCP server (kit-pp-mcp) when an agent host wants typed parameters and explicit safety hints:

• intent_workflow_creator_snapshot
• intent_workflow_audience_health
• intent_workflow_content_inventory
• intent_workflow_subscriber_lookup

The MCP server supports both stdio and streamable HTTP transports (--transport http --addr :7777 or PP_MCP_TRANSPORT=http).

Command Reference

workflow — Kit-specific compound workflows for agents

• kit-pp-cli workflow creator-snapshot — Summarize account, audience, content, and broadcast health
• kit-pp-cli workflow audience-health — Summarize subscriber status, recent growth, and largest tags
• kit-pp-cli workflow content-inventory — Inventory sequences, emails, snippets, forms, templates, and broadcasts
• kit-pp-cli workflow subscriber-lookup — Fetch one subscriber with tags, custom fields, attribution, and email stats

account — Manage account

• kit-pp-cli account list — Get current account
• kit-pp-cli account list-colors — List colors
• kit-pp-cli account list-creatorprofile — Get Creator Profile
• kit-pp-cli account list-emailstats — Get email stats
• kit-pp-cli account list-growthstats — Get growth stats for a specific time period. Defaults to last 90 days.
  
  NOTE: We return your stats in your...
• kit-pp-cli account update — Update colors

broadcasts — Manage broadcasts

• kit-pp-cli broadcasts create — Draft or schedule to send a broadcast to all or a subset of your subscribers.
  
  To save a draft, set...
• kit-pp-cli broadcasts delete — Delete a broadcast
• kit-pp-cli broadcasts get — Get a broadcast
• kit-pp-cli broadcasts list — List broadcasts
• kit-pp-cli broadcasts list-stats — Get stats for a list of broadcasts
• kit-pp-cli broadcasts update — Update an existing broadcast. Continue to draft or schedule to send a broadcast to all or a subset of your...

bulk — Manage bulk

• kit-pp-cli bulk create — See 'Bulk & async processing' for more information.
• kit-pp-cli bulk create-customfields — Bulk update subscriber custom field values
• kit-pp-cli bulk create-forms — Adding subscribers to double opt-in forms will trigger sending an Incentive Email. Subscribers already added to the...
• kit-pp-cli bulk create-subscribers — See 'Bulk & async processing' for more information.
• kit-pp-cli bulk create-tags — See 'Bulk & async processing' for more information.
• kit-pp-cli bulk create-tags-2 — The subscribers being tagged must already exist. Subscribers can be created in bulk using the '[Bulk create...
• kit-pp-cli bulk delete — See 'Bulk & async processing' for more information.

custom-fields — Manage custom fields

• kit-pp-cli custom-fields create — Create a custom field for your account. The label field must be unique to your account. Whitespace will be removed...
• kit-pp-cli custom-fields delete — This will remove all data in this field from your subscribers.
• kit-pp-cli custom-fields list — A custom field allows you to collect subscriber information beyond the standard fields of first name and email...
• kit-pp-cli custom-fields update — Updates a custom field label (see Create a custom field for...

email-templates — Manage email templates

• kit-pp-cli email-templates — List email templates

forms — Manage forms

• kit-pp-cli forms — List forms

posts — Manage posts

• kit-pp-cli posts get — Get a post
• kit-pp-cli posts list — List posts

purchases — Manage purchases

• kit-pp-cli purchases create — Create a purchase
• kit-pp-cli purchases get — Get a purchase
• kit-pp-cli purchases list — List purchases

segments — Manage segments

• kit-pp-cli segments — List segments

sequences — Manage sequences

• kit-pp-cli sequences create — Creates an empty sequence — the container that holds sequence emails. After creating the shell, use [Create a...
• kit-pp-cli sequences delete — Soft-deletes a sequence. The sequence is removed from active delivery immediately, with cleanup of associated state...
• kit-pp-cli sequences get — Fetches a single sequence by id. Use this when you need the current schedule, the active / repeat / hold...
• kit-pp-cli sequences list — Returns every sequence on the account. A sequence is a self-contained set of automated emails — subscribers join,...
• kit-pp-cli sequences update — Updates any sequence settings — name, email_address, schedule (send_days, send_hour, time_zone),...

snippets — Manage snippets

• kit-pp-cli snippets create — Snippets are reusable pieces of email content you can drop into a broadcast or sequence email using Liquid: `{{...
• kit-pp-cli snippets get — Fetches a single snippet by id. Unlike List snippets, this endpoint...
• kit-pp-cli snippets list — Returns every snippet on the account. Each snippet's key is the identifier used in Liquid — {{ snippet.key }}...
• kit-pp-cli snippets update — Rename a snippet, replace its body, or archive/restore it. Updates apply on the next send of any email that...

subscribers — Manage subscribers

• kit-pp-cli subscribers create — Behaves as an upsert. If a subscriber with the provided email address does not exist, it creates one with the...
• kit-pp-cli subscribers create-filter — Filter subscribers based on engagement
• kit-pp-cli subscribers get — Get a subscriber
• kit-pp-cli subscribers list — List subscribers
• kit-pp-cli subscribers update — If you include a custom field key that does not exist on your account, the request returns an error. Use [List...

tags — Manage tags

• kit-pp-cli tags create — Create a tag
• kit-pp-cli tags list — List tags
• kit-pp-cli tags update — Update tag name

webhooks — Manage webhooks

• kit-pp-cli webhooks create — Available event types:
  - subscriber.subscriber_activate
  - subscriber.subscriber_unsubscribe
  -...
• kit-pp-cli webhooks delete — Delete a webhook
• kit-pp-cli webhooks list — Webhooks are automations that will receive subscriber data when a subscriber event is triggered, such as when a...

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

kit-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.

Auth Setup

Run kit-pp-cli auth setup to print the URL and steps for getting a key (add --launch to open the URL). Then set:

export KIT_API_KEY="<your-key>"

Or persist it in ~/.config/kit-pp-cli/config.toml.

Run kit-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:

  kit-pp-cli account list --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

• Explicit retries — use --idempotent only when an already-existing create should count as success, and --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:

{
  "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.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

kit-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
kit-pp-cli feedback --stdin < notes.txt
kit-pp-cli feedback list --json --limit 10

Entries are stored locally at ~/.kit-pp-cli/feedback.jsonl. They are never POSTed unless KIT_FEEDBACK_ENDPOINT is set AND either --send is passed or KIT_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
stdout	Default; write to stdout only
file:<path>	Atomically write output to <path> (tmp + rename)
webhook:<url>	POST the output body to the URL (application/json or application/x-ndjson when --compact)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

kit-pp-cli profile save briefing --json
kit-pp-cli --profile briefing account list
kit-pp-cli profile list --json
kit-pp-cli profile show briefing
kit-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show kit-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

1. Install the MCP server:

   go install github.com/mvanhorn/printing-press-library/library/marketing/kit/cmd/kit-pp-mcp@latest
   

2. Register with Claude Code:

   claude mcp add kit-pp-mcp -- kit-pp-mcp
   

3. Verify: claude mcp list

Direct Use

1. Check if installed: which kit-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Prefer the Agentic Kit Workflows above for broad account, audience, content, or subscriber-context requests.
3. Match narrower user queries to the best command from the Command Reference above.
4. Execute with the --agent flag:

   kit-pp-cli <command> [subcommand] [args] --agent
   

5. If ambiguous, drill into subcommand help: kit-pp-cli <command> --help.