Pp Keyword Planner

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

Google Keyword Planner — Printing Press CLI

Installation and first check

Use keyword-planner-pp-cli from PATH. Its default evidence portfolio is ~/.local/share/keyword-planner/snapshots.db. Follow Prerequisites: Install the CLI below.

keyword-planner-pp-cli --version
keyword-planner-pp-cli doctor --json

When to Use This CLI

Use this CLI when an agent needs Google Keyword Planner ideas or historical monthly metrics with explicit language, geography, range, and network context. Use the local portfolio commands to reopen evidence offline, trace a value to its raw receipt, compare saved collections, preserve variant lineage, or prepare a safe DuckDB handoff. Treat the returned volumes and bids as Planner signals for YouTube subject research, not as measured YouTube demand, RPM, or revenue.

Anti-triggers

Do not use this press for campaign or bid changes, account administration, Google Trends, automatic scoring, forecasts, schedules, or revenue predictions. Planner estimates are not measured YouTube demand or RPM.

Workflow

1. Choose six to eight seeds at the subject's level. Avoid replacing the subject with narrow title wording.
2. Specify language and geo resources. Inspect the complete request with --dry-run if needed.
3. Use ideas to discover related terms, then historical for selected terms.
4. Inspect saved coverage before interpretation. Follow snapshot IDs and preserve short-window, null, and ambiguity flags.
5. Use local portfolio commands for trace, comparison, export, and safe descriptive statistics. Reach Google again only for an explicitly requested fresh collection.

Auth Setup

Authentication uses the OAuth refresh-token flow with GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_REFRESH_TOKEN loaded from ~/.env. The approved grant must carry the AdWords scope. The CLI refreshes a short-lived access token in memory and sends Authorization: Bearer. GOOGLE_ADS_CUSTOMER_ID selects the operating account; GOOGLE_ADS_LOGIN_CUSTOMER_ID supplies optional manager routing. Token responses never enter the portfolio. An invalid grant, permission error, or customer routing failure is an account-setup problem, not a reason to repeat the same request.

Google retired developer tokens on September 9, 2026. The CLI no longer loads or sends GOOGLE_ADS_DEVELOPER_TOKEN. API access belongs to the Google Cloud project that owns the OAuth client. Enable Google Ads API in that project and obtain Basic or Standard access: Explorer access excludes the Keyword Planner methods. New Basic access applications require completed brand verification. Browser cookies are not used.

Run keyword-planner-pp-cli doctor to verify setup.

Command Reference

Snapshot examples below use example IDs that must be replaced with IDs from your own portfolio. Run keyword-planner-pp-cli portfolio list --agent to choose compatible IDs in another portfolio; latest and previous can refer to different endpoints.

Unique Capabilities

These local evidence views extend the direct API with receipt, coverage, lineage, comparison, integrity, and descriptive-statistics views.

Evidence that compounds

• portfolio trace — Trace one stored monthly value back to the exact request and raw receipt that produced it.

  Reach for this when a number needs a receipt-backed explanation that a direct Planner call cannot provide.

  keyword-planner-pp-cli portfolio trace 2c2f465c-6253-430a-a533-aa30fabbfbff --keyword "beef steak" --month 2026-07 --agent

• portfolio coverage — See requested, returned, missing, unavailable, raw-only, and incomplete coverage for a saved collection.

  Use this before consuming a collection when the API response alone cannot explain what was absent or incomplete.

  keyword-planner-pp-cli portfolio coverage latest --agent

• portfolio diff — Compare two preserved collections to see changed terms, monthly values, flags, and coverage.

  Use this when the question is what changed between saved collections rather than what one live call returns.

  keyword-planner-pp-cli portfolio diff 2c2f465c-6253-430a-a533-aa30fabbfbff c6ea4780-190b-42f4-8f4d-a8b7207a2395 --agent

Safe warehouse handoff

• portfolio variants — Follow submitted keywords through returned terms and close variants without double-counting demand.

  Pick this when a Planner result must be interpreted with its returned-term and close-variant relationships intact.

  keyword-planner-pp-cli portfolio variants latest --limit 10 --agent --json

• portfolio integrity — Verify that raw receipts, hashes, normalized rows, and coverage still reconcile.

  Run this before a warehouse handoff when evidence integrity matters more than a fresh remote request.

  keyword-planner-pp-cli portfolio integrity latest --agent

• portfolio safe-stats — Compute descriptive monthly aggregates while excluding unavailable, ambiguous, anomalous, and incomplete rows.

  Choose this for mechanical local summaries that must preserve warnings and avoid turning Planner signals into forecasts.

  keyword-planner-pp-cli portfolio safe-stats --snapshot latest --agent

Recipes

Check local readiness

keyword-planner-pp-cli doctor --json

Confirm local setup and portfolio schema without a network call.

Collect subject-level ideas

keyword-planner-pp-cli ideas --seed "beef steak" --seed "ribeye steak" --seed "beef brisket" --seed "pork chops" --seed "meat cutting" --seed "butchery" --language languageConstants/1000 --geo geoTargetConstants/2840 --agent

Use explicit resource names and preserve all pages for the six-to-eight-seed research pass.

Retrieve historical wording

keyword-planner-pp-cli historical --keyword "beef steak" --keyword "beef brisket" --language languageConstants/1000 --geo geoTargetConstants/2840 --agent

Keep the submitted terms, returned terms, variant links, and every monthly value.

Compare preserved collections

keyword-planner-pp-cli portfolio diff 2c2f465c-6253-430a-a533-aa30fabbfbff c6ea4780-190b-42f4-8f4d-a8b7207a2395 --agent

Compare two compatible snapshots selected from portfolio list without replacing either or calling Google again.

Export a DuckDB-ready slice

keyword-planner-pp-cli portfolio export --snapshot latest --agent --select keyword,month,monthly_searches

Emit a narrow, traceable local relation for the read-only warehouse consumer.

Preview a complete collection request

keyword-planner-pp-cli historical --keyword "beef steak" --keyword "beef brisket" --language languageConstants/1000 --geo geoTargetConstants/2840 --dry-run --json

Inspect resolved targeting and the closed-month range without reading credentials, contacting Google, or writing the portfolio.

Export one closed month as CSV

keyword-planner-pp-cli portfolio export --snapshot 2c2f465c-6253-430a-a533-aa30fabbfbff --start 2026-07 --end 2026-07 --format csv

Keep the month bound explicit and export local evidence for a spreadsheet.

Inspect a small available search slice

keyword-planner-pp-cli portfolio search "beef steak" --snapshot 2c2f465c-6253-430a-a533-aa30fabbfbff --available-only --limit 10 --json

Show available saved monthly values with their flags and provenance; availability alone is not the safe-aggregate policy.

Authentication

Live collection loads only the Google Ads bindings from ~/.env, with explicit environment overrides. Keep that file private. Access tokens exist only in memory; token responses and credential values never enter the portfolio or command output.

The operating target and manager context are separate bindings. Equal values are allowed after the target has been verified; manager status alone does not establish eligibility. Currency comes from a live account lookup and retains its provenance. Use doctor --live to check the configured target and both Planner methods. The default doctor is offline.