---
name: pp-pinterest
description: "Every Pinterest v5 endpoint plus period-over-period analytics, Pin hygiene audits, and offline Pin search. Trigger phrases: `how did my Pinterest do this month`, `audit my Pins for missing alt text`, `what's trending on Pinterest that we haven't pinned`, `pull a Pinterest ads report`, `use pinterest-pp-cli`, `run pinterest`."
author: "Elizabeth Stone"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - pinterest-pp-cli
    install:
      - kind: go
        bins: [pinterest-pp-cli]
        module: github.com/mvanhorn/printing-press-library/library/marketing/pinterest/cmd/pinterest-pp-cli
---
<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/pinterest/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/". -->

# Pinterest — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `pinterest-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 pinterest --cli-only
   ```
2. Verify: `pinterest-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/pinterest/cmd/pinterest-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.

> **First time?** Pinterest's API needs your own (free) Pinterest developer app before you can log in. Follow [Auth Setup](#auth-setup) once, then come back here.

Covers boards, Pins, analytics, trends, ads, catalogs, and audiences from one binary with --dry-run on writes, no interactive prompts, and explicit --yes confirmation. A bounded local sync powers offline search, the 'pins audit' hygiene report, and 'trends gaps'; 'perf compare' and 'pins funnel' turn raw analytics into answers.

## When to Use This CLI

Use this CLI to inspect or operate a Pinterest business account: boards, Pins, organic analytics, trends, and ads. It is the right tool for weekly performance reviews, Pin SEO cleanup, safe pre-publish validation, and ads reporting.

## Anti-triggers

Do not use this CLI for:
- Scraping other people's public Pinterest profiles or boards without OAuth
- Designing Pin images or generating Pin copy (use a design or writing tool)
- Bulk mutation of live Pins without explicit human approval

## Unique Capabilities

### Analytics that answer the question

- **`perf compare`** — See whether impressions, saves, and outbound clicks grew versus the previous equal-length period, with absolute and percent deltas.

  _Reach for this for a weekly or monthly 'did we grow?' answer instead of calling account analytics twice and doing date math._

  ```bash
  pinterest-pp-cli perf compare --days 28 --agent
  ```
- **`pins funnel`** — Rank your top Pins by impressions (or --sort-by metric), compute save and outbound-click rates, and flag Pins that get saved but don't send traffic.

  _Use to decide which Pins to refresh or repurpose to drive site traffic._

  ```bash
  pinterest-pp-cli pins funnel --days 30 --limit 25 --agent
  ```
- **`trends gaps`** — List trending keywords for a region with how many of your synced Pins cover each, zero-coverage first. Coverage counts need a synced local store.

  _Use when planning the next content batch to find trends you have nothing on._

  ```bash
  pinterest-pp-cli trends gaps --region US --agent
  ```

### Local state that compounds

- **`pins audit`** — Find published Pins missing alt text, a destination link, a title, or UTM tracking, grouped by board. Reads the local store; run sync first.

  _Use before an SEO cleanup pass to get the exact Pin IDs that need fixing._

  ```bash
  pinterest-pp-cli pins audit --group-by board --agent
  ```
- **`pins preflight`** — Validate a proposed Pin (field limits, board and section by name, UTM link) and get a ready-to-send create body without writing anything. Board names resolve from the local store; run sync first.

  _Use before pins create so an agent never publishes an incomplete or misrouted Pin._

  ```bash
  pinterest-pp-cli pins preflight --board "Recipes" --link https://example.com/blog/meal-prep?utm_source=pinterest --image-url https://example.com/img/meal-prep.jpg --title "Weeknight dinner ideas" --alt-text "Bowl of pasta on a table" --agent
  ```

### Agent-native plumbing

- **`ads report`** — Create, wait for, and download an ads performance report in one command. Requires the ads:read scope and --ad-account-id (or PINTEREST_AD_ACCOUNT_ID).

  _Use for campaign or ad performance instead of manually polling the async report endpoint._

  ```bash
  pinterest-pp-cli ads report --level campaign --days 7 --agent
  ```

`--ca-cert`, `PINTEREST_CA_CERT`, or `ca_cert` adds a PEM CA bundle to the system trust roots. `--tls-server-name`, `PINTEREST_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

**ad-accounts** — View analytical information about advertising.

Note: If the current operation_user_account (defined by the access token)
has access to another user's Ad Accounts via
<a href='/docs/getting-started/using-business-access/'>Pinterest Business Access</a>,
you can modify your request to use the current operation_user_account's
permissions to those Ad Accounts by including the ad_account_id in the path
parameters for the request (e.g. .../?ad_account_id=12345&...).

- `pinterest-pp-cli ad-accounts create` — Create a new ad account. Different ad accounts can support different currencies, payment methods, etc.
- `pinterest-pp-cli ad-accounts get` — Get an ad account
- `pinterest-pp-cli ad-accounts list` — Get a list of the ad_accounts that the 'operation user_account' has access to.

**advanced-auction** — View, create, or update advanced auction item bid options.

- `pinterest-pp-cli advanced-auction items-get-post` — Get the bid options for a batch of retail catalog items. The catalog must be owned by the 'operation user_account'. _(gated: not available to all users)_
- `pinterest-pp-cli advanced-auction items-submit-post` — This endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for _(gated: not available to all users)_

**boards** — View, create, update, or delete information about boards.

- `pinterest-pp-cli boards create` — Create a board owned by the 'operation user_account'.
- `pinterest-pp-cli boards delete` — Delete a board owned by the 'operation user_account'.
- `pinterest-pp-cli boards get` — Get a board owned by the operation user_account - or a group board that has been shared with this account.
- `pinterest-pp-cli boards list` — Get a list of the boards owned by the 'operation user_account' + group boards where this account is a collaborator
- `pinterest-pp-cli boards update` — Update a board owned by the 'operating user_account'.

**business-access** — Manage business access

- `pinterest-pp-cli business-access brand-accounts-create` — Create a Brand Account that will be a child business of a business hierarchy.
- `pinterest-pp-cli business-access brand-accounts-update` — Update an existing Brand Account

**businesses** — Manage businesses

- `pinterest-pp-cli businesses get-business-employers` — Get all of the viewing user's business employers.
- `pinterest-pp-cli businesses respond-business-access-invites` — Accept or decline invites or requests.

**catalogs** — Manage information about shopping product catalogs and items.

- `pinterest-pp-cli catalogs available-filter-values` — Get the available filter attributes and values associated with a given feed or catalog owned by the 'operation
- `pinterest-pp-cli catalogs create` — Create a new catalog owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs feed-processing-results-list` — Fetch a feed processing results owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs feeds-create` — Create a new feed owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs feeds-delete` — Delete a feed owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs feeds-get` — Get a single feed owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs feeds-ingest` — Ingest items for a given feed owned by the 'operation user_account'. _(restricted to a specific group of users)_
- `pinterest-pp-cli catalogs feeds-list` — Fetch feeds owned by the 'operation user_account'. - By default, the 'operation user_account' is the token user_account.
- `pinterest-pp-cli catalogs feeds-update` — Update a feed owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs items-batch-get` — Get a single catalogs items batch owned by the 'operating user_account'. [See detailed documentation here.
- `pinterest-pp-cli catalogs items-batch-post` — This endpoint supports multiple operations on a set of one or more catalog items owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs items-issues-list` — List item validation issues for a given feed processing result owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs items-post` — Get the items of the catalog owned by the 'operation user_account'. [See detailed documentation here.
- `pinterest-pp-cli catalogs list` — Fetch catalogs owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-group-pins-list` — Get a list of product pins for a given Catalogs Product Group Id owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-create` — Create product group to use in Catalogs owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-create-many` — Create product group to use in Catalogs owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-delete` — Delete a product group owned by the 'operation user_account' from being in use in Catalogs.
- `pinterest-pp-cli catalogs product-groups-delete-many` — Delete product groups owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-get` — Get a single product group for a given Catalogs Product Group Id owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-list` — Get a list of product groups for a given Catalogs Feed Id owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-product-counts-get` — Get a product counts for a given Catalogs Product Group owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs product-groups-update` — Update product group owned by the 'operation user_account' to use in Catalogs.
- `pinterest-pp-cli catalogs products-by-product-group-filter-list` — List products Pins owned by the 'operation user_account' that meet the criteria specified in the Catalogs Product Group
- `pinterest-pp-cli catalogs reports-create` — Async request to create a report of the catalog owned by the 'operation user_account'.
- `pinterest-pp-cli catalogs reports-get` — This returns a URL to a report given a token returned from [Build catalogs
- `pinterest-pp-cli catalogs reports-stats` — List aggregated numbers of issues for a catalog owned by the 'operation user_account'.

**integrations** — View, create, or update commerce integrations.

- `pinterest-pp-cli integrations commerce-del` — Delete commerce integration metadata for the given external business ID. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations commerce-get` — Get commerce integration metadata associated with the given external business ID. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations commerce-patch` — Update commerce integration metadata for the given external business ID. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations commerce-post` — Create commerce integration metadata to link an external business ID with a Pinterest merchant & ad account. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations get-by-id` — Get integration metadata by ID. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations get-list` — Get integration metadata list. _(beta: contact your Pinterest account manager)_
- `pinterest-pp-cli integrations logs-post` — This endpoint receives batched logs from integration applications on partner platforms. _(beta: contact your Pinterest account manager)_

**media** — Register and manage media uploads.

- `pinterest-pp-cli media create` — Register your intent to upload media.
- `pinterest-pp-cli media get` — Get details for a registered media upload, including its current status.
- `pinterest-pp-cli media list` — List media uploads filtered by given parameters.

**notifications** — Send notifications.

- `pinterest-pp-cli notifications` — Used by third-party partners to send notifications to Pinterest. _(gated: Pinterest must grant access)_

**oauth** — Generate and refresh OAuth access tokens.

- `pinterest-pp-cli oauth conversion-token` — Generate a new and long-lived OAuth access token dedicated for sending conversions using a valid access token.
- `pinterest-pp-cli oauth token` — Generate a new OAuth access token using an authorization code
- `pinterest-pp-cli oauth token-revoke` — Revokes an access or refresh token. Only tokens issued for system users are currently supported.

**pins** — View, create, update, or delete information about Pins.

- `pinterest-pp-cli pins create` — Create a Pin on a board or board section owned by the 'operation user_account'.
- `pinterest-pp-cli pins delete` — Delete a Pins owned by the 'operation user_account' - or on a group board that has been shared with this account.
- `pinterest-pp-cli pins get` — Get a Pin owned by the 'operation user_account' - or on a group board that has been shared with this account.
- `pinterest-pp-cli pins list` — Get a list of the Pins owned by the 'operation user_account'.
- `pinterest-pp-cli pins multi-analytics` — **This endpoint is currently in beta and not available to all apps.**
- `pinterest-pp-cli pins update` — Update a pin owned by the 'operating user_account'. _(beta)_

**pinterest-search** — Manage pinterest search

- `pinterest-pp-cli pinterest-search partner-pins` — **This endpoint is currently in beta and not available to all apps.**
- `pinterest-pp-cli pinterest-search user-boards-get` — Search for boards for the 'operation user_account'. This includes boards of all board types.
- `pinterest-pp-cli pinterest-search user-pins-list` — Search for pins for the 'operation user_account'. - By default, the 'operation user_account' is the token user_account.

**resources** — View metadata about available metrics and targeting options in the Pinterest API.

- `pinterest-pp-cli resources ad-account-countries-get` — Get Ad Accounts countries
- `pinterest-pp-cli resources delivery-metrics-get` — Get the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints.
- `pinterest-pp-cli resources interest-targeting-options-get` — Get details of a specific interest given interest ID. Click [here](https://docs.google.
- `pinterest-pp-cli resources lead-form-questions-get` — Get a list of all lead form question type names. Some questions might not be used.
- `pinterest-pp-cli resources metrics-ready-state-get` — Learn whether conversion or non-conversion metrics are finalized and ready to query.
- `pinterest-pp-cli resources targeting-options-get` — You can use targeting values in ads placement to define your intended audience.

**terms** — View related and suggested terms for ads targeting.

- `pinterest-pp-cli terms related-list` — Get a list of terms logically related to each input term.
- `pinterest-pp-cli terms suggested-list` — Get popular search terms that begin with your input term.

**trends** — View trending terms, topics, and product categories.

- `pinterest-pp-cli trends editorial-articles-list` — Get a list of published editorial articles.
- `pinterest-pp-cli trends featured-topics-list` — Enables advertisers to pull top five trending topics by interest and market
- `pinterest-pp-cli trends product-categories-details-list` — Enables advertisers to retrieve demographic information, related pins, and trend lines for specified product categories
- `pinterest-pp-cli trends product-categories-trending-list` — Get a list of growing Shopping Product Categories in ranked order allowing filtering by engagement type, vertical, age
- `pinterest-pp-cli trends trending-keywords-list` — Get the top trending search keywords among the Pinterest user audience.

**user-account** — View user accounts associated with a given access token.

- `pinterest-pp-cli user-account analytics` — Get analytics for the 'operation user_account' - By default, the 'operation user_account' is the token user_account.
- `pinterest-pp-cli user-account analytics-top-pins` — Gets analytics data about a user's top pins (limited to the top 50).
- `pinterest-pp-cli user-account analytics-top-video-pins` — Gets analytics data about a user's top video pins (limited to the top 50).
- `pinterest-pp-cli user-account boards-user-follows-list` — Get a list of the boards a user follows. The request returns a board summary object array.
- `pinterest-pp-cli user-account follow-user-update` — **This endpoint is currently in beta and not available to all apps.**
- `pinterest-pp-cli user-account followers-list` — Get a list of your followers.
- `pinterest-pp-cli user-account get` — Get account information for the 'operation user_account' - By default
- `pinterest-pp-cli user-account linked-business-accounts-get` — Get a list of your linked business accounts.
- `pinterest-pp-cli user-account unverify-website-delete` — Unverify a website verified by the signed-in user.
- `pinterest-pp-cli user-account user-following-get` — Get a list of who a certain user follows.
- `pinterest-pp-cli user-account user-websites-get` — Get user websites, claimed or not
- `pinterest-pp-cli user-account verify-website-update` — Verify a website as a signed-in user.
- `pinterest-pp-cli user-account website-verification-get` — Get verification code for user to install on the website to claim it.

**users** — Manage users

- `pinterest-pp-cli users interests user-account-followed` — List the interests a user follows.


**ads** — Novel ads workflow (async report in one command)


- `pinterest-pp-cli ads report` — Create, wait for, and download an ads performance report in one command. Requires the ads:read scope and --ad-account-id (or PINTEREST_AD_ACCOUNT_ID).


**perf** — Account performance comparisons


- `pinterest-pp-cli perf compare` — See whether impressions, saves, and outbound clicks grew versus the previous equal-length period, with absolute and percent deltas.


**pins (workflow commands)**


-