pp-meta-ads

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/meta-ads/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/". -->

# Meta Ads — Printing Press CLI

## Prerequisites: Install the CLI

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

Use this CLI when you need creative-fatigue diagnostics, audience overlap cartography, learning-phase forensics, or attribution drift detection across Meta ad accounts. Best when paired with a daily sync into the local store so trend queries are instant. Read-only by design — never used to modify campaigns, budgets, or audiences.

## Anti-triggers

Do not use this CLI for:
- Do not use this CLI to create, pause, modify, or delete campaigns, adsets, ads, audiences, or creatives — it is read-only.
- Do not use this CLI for budget management or bid-strategy changes — that is what Meta Ads Manager or facebook-business-sdk are for.
- Do not use this CLI for write-side audience uploads — custom audience creation from customer files is out of scope.

## Unique Capabilities

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

### Local state that compounds
- **`fatigue`** — Detect ads whose CPM is drifting up, frequency is climbing, and CTR is falling across a configurable window.

  _Use this to decide which ads to retire. Spending on a fatigued creative is the highest-leverage waste in any account._

  ```bash
  meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent
  ```
- **`decay`** — Compare a creative's first-impression CTR against its current CTR, with projected dead-date.

  _Use for retire/refresh decisions on a single creative. The slope and projected dead-date are the deciding factor._

  ```bash
  meta-ads-pp-cli decay --creative-id 120208734567 --agent
  ```
- **`overlap`** — Pairwise overlap percentages across custom audiences, with cannibalization recommendations.

  _Use when ad strategy is mature and ROAS feels diluted across similar audiences. Surfaces consolidate-or-exclude decisions._

  ```bash
  meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent
  ```
- **`learning`** — Surface adsets stuck in algorithmic learning >N days with root-cause hint (budget too low, audience too narrow, events too sparse).

  _Use when ROAS collapses across multiple adsets simultaneously. Stuck-in-learning adsets eat budget without optimizing._

  ```bash
  meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent
  ```

### Forensic queries
- **`reconcile`** — Per-day diff between Meta-reported account spend and sum-of-insights spend; flags days where attribution drift exceeds threshold.

  _Use monthly for attribution audits. Surfaces specific days where Meta and insights disagree, usually delayed conversion attribution._

  ```bash
  meta-ads-pp-cli reconcile --account act_4327210487520472 --since 30d --threshold 5 --agent
  ```
- **`bottleneck`** — Highest-spend adsets with worst ROAS, ranked with 'why' column joining learning state and effective status.

  _Use weekly to decide what to pause. Highest-leverage targets surface first._

  ```bash
  meta-ads-pp-cli bottleneck --account act_4327210487520472 --limit 10 --agent
  ```

### Account hygiene
- **`stale`** — Active ads with zero impressions in N days.

  _Use quarterly for account hygiene. Active ads with zero impressions are usually misconfigured or post-deletion zombies._

  ```bash
  meta-ads-pp-cli stale --days 90 --agent
  ```
- **`inventory`** — Group every ad in an account by effective_status, surface ads where configured status='ACTIVE' but effective_status='WITH_ISSUES' or 'DISAPPROVED'.

  _Use first thing every morning. DISAPPROVED-but-still-ACTIVE ads cost real spend without delivering._

  ```bash
  meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent
  ```

## Command Reference

**adcreatives** — Manage adcreatives

- `meta-ads-pp-cli adcreatives <adId>` — Get creatives attached to an ad

**ads** — Ad-level read operations

- `meta-ads-pp-cli ads <adAccountId>` — List ads in an ad account

**adsets** — Ad set-level read operations

- `meta-ads-pp-cli adsets <adAccountId>` — Returns ad sets with targeting summary, budget, optimization goal, and bid strategy.

**campaigns** — Campaign-level read operations

- `meta-ads-pp-cli campaigns <adAccountId>` — Returns campaigns with status, objective, and budget metadata.

**customaudiences** — Manage customaudiences

- `meta-ads-pp-cli customaudiences <adAccountId>` — List custom audiences in an ad account

**delivery-estimate** — Manage delivery estimate

- `meta-ads-pp-cli delivery-estimate <adAccountId>` — Get reach/impressions delivery estimate

**insights** — Performance and delivery insights (the creative-fatigue observatory)

- `meta-ads-pp-cli insights get-account` — Returns aggregated insights across the entire ad account.
- `meta-ads-pp-cli insights get-ad` — Ad-level insights with frequency, CPM, CTR over time.
- `meta-ads-pp-cli insights get-ad-set` — Get ad set-level insights
- `meta-ads-pp-cli insights get-campaign` — Get campaign-level insights

**me** — Manage me

- `meta-ads-pp-cli me` — Returns every ad account the access token has been granted access to.


### Finding the right command

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

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

### Triage creative fatigue across a campaign

```bash
meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent --select ad_id,ad_name,cpm_slope,frequency_now,ctr_slope,verdict
```

Returns one row per ad with CPM slope, current frequency, CTR slope, and a retire/keep verdict. Narrow output by selecting only the fatigue-relevant fields to keep agent context bounded.

### Find audience cannibalization risk

```bash
meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent
```

Returns pairwise overlap percentages and a recommendation per pair. Anything above 30% is a candidate for consolidation or exclusion.

### Spot stuck-in-learning adsets

```bash
meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent
```

Surfaces adsets where learning_stage_info has been LEARNING for >7 days. The 'why' column hints at budget/audience/event sparsity.

### Daily inventory roll-up first thing

```bash
meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent
```

Groups every ad by effective_status. The DISAPPROVED-but