npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

pinterest-ads-cli

v1.0.4

Published

Pinterest Ads CLI for AI agents

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

bennhuangbennhuang

Keywords

pinterest-adsadscliai-agentapi

Readme

pinterest-ads-cli

Pinterest Ads CLI for AI agents (and humans). Analyze campaign performance, browse product catalogs, discover regional search trends, pull analytics with attribution windows, and more.

Works with: OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.

Installation

npm install -g pinterest-ads-cli

Or run directly: npx pinterest-ads-cli --help

How it works

Built on the official Pinterest REST API v5. Handles OAuth2 Bearer token authentication. Every command outputs structured JSON to stdout, ready for agents to parse without extra processing.

Core endpoints covered:

  • Ad Accounts -- list and inspect ad accounts
  • Campaigns -- list campaigns
  • Ad Groups -- list ad groups
  • Ads -- list ads
  • Keywords -- list targeting keywords
  • Audiences -- list audiences and customer lists
  • Conversion Tags -- list conversion tracking tags
  • Billing -- billing profiles and order lines
  • Lead Forms -- lead generation forms
  • Catalogs -- product catalogs and feeds (Pinterest Shopping)
  • Trends -- trending search terms by region
  • Analytics -- account, campaign, ad group, and ad level performance metrics

Setup

Step 1: Create a Pinterest app

  1. Go to Pinterest Developer Apps and sign in.
  2. Create a new app. You need a Pinterest Business account.
  3. Note your App ID and App Secret.

Step 2: Get an OAuth2 access token

Use the Pinterest OAuth2 flow to get an access token with the ads:read scope. See Pinterest OAuth docs.

Step 3: Place the credentials file

Choose one of these options:

# Option A: Default path (recommended)
mkdir -p ~/.config/pinterest-ads-cli
cat > ~/.config/pinterest-ads-cli/credentials.json << EOF
{
  "access_token": "YOUR_ACCESS_TOKEN"
}
EOF

# Option B: Environment variable
export PINTEREST_ADS_ACCESS_TOKEN=your_access_token

# Option C: Pass per command
pinterest-ads-cli --credentials /path/to/credentials.json accounts

Credentials are resolved in this order:

  1. --credentials <path> flag
  2. PINTEREST_ADS_ACCESS_TOKEN env var
  3. ~/.config/pinterest-ads-cli/credentials.json (auto-detected)

Step 4: Find your Ad Account ID

pinterest-ads-cli accounts

Usage

All commands output pretty-printed JSON by default. Use --format compact for compact single-line JSON.

Pagination uses cursor-based --bookmark values returned in the response.

accounts

List ad accounts the user has access to.

pinterest-ads-cli accounts
pinterest-ads-cli accounts --page-size 50

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

account

Get details of a specific ad account.

pinterest-ads-cli account 123456789

campaigns

List campaigns for an ad account.

pinterest-ads-cli campaigns 123456789
pinterest-ads-cli campaigns 123456789 --entity-statuses ACTIVE,PAUSED
pinterest-ads-cli campaigns 123456789 --order DESCENDING --page-size 100

Options:

  • --campaign-ids <ids> -- filter by campaign IDs (comma-separated, max 250)
  • --entity-statuses <statuses> -- filter by status (comma-separated)
  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order: ASCENDING or DESCENDING
  • --bookmark <cursor> -- pagination cursor

adgroups

List ad groups for an ad account.

pinterest-ads-cli adgroups 123456789
pinterest-ads-cli adgroups 123456789 --campaign-ids campaign_1,campaign_2

Options:

  • --campaign-ids <ids> -- filter by campaign IDs
  • --ad-group-ids <ids> -- filter by ad group IDs
  • --entity-statuses <statuses> -- filter by status
  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order
  • --bookmark <cursor> -- pagination cursor

ads

List ads for an ad account.

pinterest-ads-cli ads 123456789
pinterest-ads-cli ads 123456789 --campaign-ids campaign_1 --entity-statuses ACTIVE

Options:

  • --campaign-ids <ids> -- filter by campaign IDs
  • --ad-group-ids <ids> -- filter by ad group IDs
  • --ad-ids <ids> -- filter by ad IDs
  • --entity-statuses <statuses> -- filter by status
  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order
  • --bookmark <cursor> -- pagination cursor

keywords

List keywords for an ad account.

pinterest-ads-cli keywords 123456789
pinterest-ads-cli keywords 123456789 --ad-group-id adgroup_1

Options:

  • --ad-group-id <id> -- filter by ad group ID
  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

audiences

List audiences for an ad account.

pinterest-ads-cli audiences 123456789

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order: ASCENDING or DESCENDING
  • --bookmark <cursor> -- pagination cursor

customer-lists

List customer lists for an ad account.

pinterest-ads-cli customer-lists 123456789

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order: ASCENDING or DESCENDING
  • --bookmark <cursor> -- pagination cursor

conversion-tags

List conversion tags for an ad account.

pinterest-ads-cli conversion-tags 123456789

conversion-tag

Get a specific conversion tag.

pinterest-ads-cli conversion-tag 123456789 tag_abc

billing-profiles

List billing profiles for an ad account.

pinterest-ads-cli billing-profiles 123456789
pinterest-ads-cli billing-profiles 123456789 --is-active

Options:

  • --is-active -- only return active profiles
  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

order-lines

List order lines for an ad account.

pinterest-ads-cli order-lines 123456789

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order: ASCENDING or DESCENDING
  • --bookmark <cursor> -- pagination cursor

order-line

Get a specific order line.

pinterest-ads-cli order-line 123456789 orderline_abc

lead-forms

List lead generation forms for an ad account.

pinterest-ads-cli lead-forms 123456789

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --order <order> -- sort order: ASCENDING or DESCENDING
  • --bookmark <cursor> -- pagination cursor

lead-form

Get a specific lead form.

pinterest-ads-cli lead-form 123456789 leadform_abc

catalogs

List catalogs.

pinterest-ads-cli catalogs

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

feeds

List catalog feeds.

pinterest-ads-cli feeds

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

product-groups

List catalog product groups.

pinterest-ads-cli product-groups

Options:

  • --page-size <n> -- results per page (default 25, max 250)
  • --bookmark <cursor> -- pagination cursor

trends

Get trending search terms for a region.

pinterest-ads-cli trends US --trend-type growing
pinterest-ads-cli trends US --trend-type monthly --interests fashion --limit 20

Options:

  • --trend-type <type> -- trend type: growing, monthly, yearly, seasonal (required)
  • --interests <interests> -- filter by interests (comma-separated)
  • --genders <genders> -- filter by genders (comma-separated)
  • --ages <ages> -- filter by age groups (comma-separated)
  • --limit <n> -- number of results (default 50)

analytics

Get ad account-level analytics.

pinterest-ads-cli analytics 123456789 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1 \
  --granularity DAY

Options:

  • --start-date <date> -- start date, YYYY-MM-DD (required)
  • --end-date <date> -- end date, YYYY-MM-DD (required)
  • --columns <cols> -- metrics, comma-separated (required). Common: SPEND_IN_MICRO_DOLLAR, IMPRESSION_1, CLICKTHROUGH_1, CPC_IN_MICRO_DOLLAR, ECPM_IN_MICRO_DOLLAR, CTR, TOTAL_CONVERSIONS
  • --granularity <gran> -- TOTAL, DAY, HOUR, WEEK, MONTH (default DAY)
  • --click-window-days <n> -- click attribution window (0, 1, 7, 14, 30, 60)
  • --view-window-days <n> -- view attribution window (0, 1, 7, 14, 30, 60)

campaign-analytics

Get campaign-level analytics.

pinterest-ads-cli campaign-analytics 123456789 \
  --campaign-ids campaign_1,campaign_2 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1

Options:

  • --campaign-ids <ids> -- campaign IDs, comma-separated (required)
  • --start-date <date> -- start date (required)
  • --end-date <date> -- end date (required)
  • --columns <cols> -- metrics (required)
  • --granularity <gran> -- TOTAL, DAY, HOUR, WEEK, MONTH (default DAY)

adgroup-analytics

Get ad group-level analytics.

pinterest-ads-cli adgroup-analytics 123456789 \
  --ad-group-ids adgroup_1 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1

Options:

  • --ad-group-ids <ids> -- ad group IDs, comma-separated (required)
  • --start-date <date> -- start date (required)
  • --end-date <date> -- end date (required)
  • --columns <cols> -- metrics (required)
  • --granularity <gran> -- TOTAL, DAY, HOUR, WEEK, MONTH (default DAY)

ad-analytics

Get ad-level analytics.

pinterest-ads-cli ad-analytics 123456789 \
  --ad-ids ad_1 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --columns SPEND_IN_MICRO_DOLLAR,IMPRESSION_1

Options:

  • --ad-ids <ids> -- ad IDs, comma-separated (required)
  • --start-date <date> -- start date (required)
  • --end-date <date> -- end date (required)
  • --columns <cols> -- metrics (required)
  • --granularity <gran> -- TOTAL, DAY, HOUR, WEEK, MONTH (default DAY)

Error output

Errors are written to stderr as JSON with an error field and a non-zero exit code:

{"error": "Not authorized to access the requested resource"}

API Reference

  • Official docs: https://developers.pinterest.com/docs/api/v5/
  • Authentication: https://developers.pinterest.com/docs/getting-started/authentication/

Related

License

Apache-2.0