Pp Bento

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/bento/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Bento — Printing Press CLI

Prerequisites: Install the CLI

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

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

2. Verify: bento-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):

go install github.com/mvanhorn/printing-press-library/library/marketing/bento/cmd/bento-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.

When to Use This CLI

Reach for bento-pp-cli when you need a fast offline view over your Bento account (FTS, JOINs, cohort builds), when you're scripting CI/CD imports, when you need transactional send from a Go process without dragging in Node, or when you're bridging Vendure / non-native ecom platforms to Bento via webhook + $purchase events. Pair with Claude Desktop / Cursor via MCP for natural-language access to every command.

Unique Capabilities

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

Sync Integrity

• sync diff — Show exactly which subscribers, tags, fields, or templates changed between two local snapshots since Bento has no since filter.

  Use this when you need to detect drift between Bento and your local source of truth, or audit what changed since the last sync.

  bento sync diff --since 2026-05-19 --resource subscribers --json

• tags drift — Surface tags whose subscriber counts swung more than N% week-over-week, catching misfiring workflows.

  Run weekly to catch silently-broken automations adding or removing tags unexpectedly.

  bento tags drift --window 30d --threshold 25 --json

List Hygiene

• hygiene scrub — Run validation + jesses_ruleset + blacklist + content_moderation in one pass and emit a clean CSV plus a rejected CSV with reasons.

  Reach for this before importing any list you didn't generate yourself. Bad list = ISP penalty.

  bento hygiene scrub --in leads.csv --out-clean clean.csv --out-rejected rejected.csv

Vendure Bridge

• events purchase-replay — Dry-run a Vendure order export against the Bento $purchase mapping and show the exact batch payload before sending.

  Use before any Vendure -> Bento purchase sync to catch shape mismatches without polluting subscriber history.

  bento events purchase-replay --from vendure-orders.json --dry-run --json

• events review-window — Emit a dated Bento event stream for orders shipped N days ago, skipping any order your existing third-party review platform already triggered.

  Use when running a Bento-side review trigger alongside a third-party review platform without double-mailing.

  bento events review-window --shipped-csv orders.csv --delay 10d --skip-stamped --dry-run

• fields lint — Diff local custom fields against a Vendure customer-schema file and flag missing, renamed, or type-mismatched fields.

  Use after any Vendure schema change to verify Bento custom fields still align.

  bento fields lint --against vendure-schema.json --json

Safety Rails

• events lint — Warn when a payload uses /fetch/commands subscribe but the intent (welcome flow, tag-triggered automation) requires /batch/events to fire automations.

  Run this on any payload bound for /fetch/commands or /batch/events to catch silent automation misfires.

  bento events lint --file events.jsonl --json

• subscribers pre-delete — Show tags, events, revenue, and active automations a subscriber set carries before you file a GDPR data_deletion_request.

  Always run before any GDPR/CCPA batch deletion to confirm the right cohort and surface revenue impact.

  bento subscribers pre-delete --emails-from gdpr-batch.txt --json

Retention

• subscribers churn-risk — Rank subscribers by days-since-last-open/click against your cohort baseline before the next broadcast goes out.

  Use before queuing a broadcast to identify the cohort most likely to mark as spam.

  bento subscribers churn-risk --threshold high --limit 100 --json

• subscribers winback — Build a CSV of customers who bought once, lapsed 180+ days, and never opened the last 3 broadcasts.

  Reach for this when scoping a reactivation campaign with a custom decay window.

  bento subscribers winback --lapsed 180d --last-purchased 90d --csv

Campaign Planning

• broadcasts whatif — Estimate audience size, predicted opens, and hygiene-risk count for a draft broadcast before you queue it in the dashboard.

  Use before any broadcast send to sanity-check audience size and deliverability risk.

  bento broadcasts whatif --segment seg_abc --json

Discovery

• subscribers find — Full-text search subscriber notes/fields plus structured filters in one query, exportable as CSV.

  Reach for this when building any ad-hoc cohort that isn't worth a segment in the dashboard.

  bento subscribers find "first order" --tagged customer --purchased-after 365d --csv

Command Reference

batch — Manage batch

• bento-pp-cli batch create — This endpoint allows you to create multiple email broadcasts efficiently.
• bento-pp-cli batch create-emails — This endpoint allows you to create and send multiple emails efficiently.
• bento-pp-cli batch create-events — This endpoint allows you to send multiple events to your site.
• bento-pp-cli batch create-subscribers — This endpoint allows for efficient bulk creation and updating of subscribers.

experimental — Access experimental APIs designed for specific use cases. Use with caution as these may change.

• bento-pp-cli experimental create — This endpoint will return an opinionated moderation score based on the content provided.
• bento-pp-cli experimental create-gender — This endpoint allows you to guess the gender of a subscriber based on their first name and last name.
• bento-pp-cli experimental create-validation — This experimental endpoint provides basic validation for email addresses and associated user information.
• bento-pp-cli experimental list — This experimental endpoint allows you to check if a domain or IP address is present on various blacklists.
• bento-pp-cli experimental list-geolocation — This endpoint allows you to geolocate an IP address.

fetch — Manage fetch

• bento-pp-cli fetch create — This endpoint allows you to execute various commands to modify subscriber data.
• bento-pp-cli fetch create-fields — Creates a new custom field in your account. Custom fields allow you to store additional data about your subscribers.
• bento-pp-cli fetch create-subscribers — Creates a new subscriber in your account and queues them for indexing.
• bento-pp-cli fetch create-tags — Creates a new tag in your account for subscriber segmentation.
• bento-pp-cli fetch list — Fetches a list of all broadcasts in your account, providing an overview of your email campaigns.
• bento-pp-cli fetch list-fields — Fetches a list of all custom fields defined in your account.
• bento-pp-cli fetch list-search — This endpoint allows for advanced searching of your subscriber base.
• bento-pp-cli fetch list-subscribers — Fetch detailed information about one or multiple subscribers in your account.
• bento-pp-cli fetch list-tags — Fetches a list of all tags in your account. Tags are useful for segmenting your subscriber base.

stats — Retrieve statistical data about your account. IMPORTANT — Never use these endpoints in client-side code.

• bento-pp-cli stats list — Fetches statistics for a specific segment in your account.
• bento-pp-cli stats list-site — Fetches overall statistics for your site. This includes counts of users, subscribers, and unsubscribers.

Finding the right command

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

bento-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

Pre-import list hygiene before any cold outreach

bento hygiene scrub --in cold-leads.csv --out-clean clean.csv --out-rejected rejected.csv --json

Chains validation + jesses_ruleset + blacklist + content_moderation in one pipeline so a dirty list never tanks deliverability.

Vendure -> Bento purchase event with dedupe

bento events purchase-replay --from vendure-orders.json --skip-already-tracked --json --select 'events[].email,events[].details.unique.key'

Maps Vendure order JSON to Bento $purchase shape, validates dedupe keys, and emits the batch payload. --select narrows the deep nested response to just the fields agents need to confirm.

Find lapsed VIPs for a win-back broadcast

bento subscribers winback --lapsed 180d --last-purchased 90d --tagged vip --csv > winback.csv

Three-way local JOIN that no Bento segment builder supports.

Audit before a GDPR batch deletion

bento subscribers pre-delete --emails-from gdpr-batch.txt --json

Shows revenue, active automations, and tag exposure for each email before you queue irreversible anonymization.