pp-bento

What this skill does

<!-- 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:
   ```bash
   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.3 or newer):

```bash
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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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