pp-semrush

What this skill does

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

# Semrush — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `semrush-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 semrush --cli-only
   ```
2. Verify: `semrush-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/semrush/cmd/semrush-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 to query Semrush data the same way more than once — weekly drift, keyword gap, backlink gap, Site Audit regression — or when you're orchestrating Semrush through an agent that should not re-spend credits on data already pulled. It's not the right tool for one-off ad-hoc lookups (the official Semrush UI is faster) or for Trends API workflows (out of scope by design).

## Unique Capabilities

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

### Local state that compounds
- **`drift`** — Diff this week's domain + keyword snapshot against last week's to see what moved, without re-spending credits on the data you already pulled.

  _When an agent is asked 'what changed for this domain this week', this is the single command that answers it from the local store with no API spend._

  ```bash
  semrush-pp-cli drift apple.com --since 7d --agent
  ```
- **`snapshot`** — Tag the current local-store state of any resource (e.g. monday-baseline) and later diff any two tags to see exactly what moved between them.

  _Lets an agent reason about state across multiple weeks of conversations without re-paying for the same data._

  ```bash
  semrush-pp-cli snapshot tag monday && semrush-pp-cli snapshot diff monday today --select phrase,position --agent
  ```
- **`backlink new`** — Show only the referring domains and backlinks first seen in a window, so the 'did anything new link to us this week' question is a one-liner.

  _Saves an agent from re-pulling and diffing two full backlink reports to answer a recency question._

  ```bash
  semrush-pp-cli backlink new apple.com --since 7d --json
  ```
- **`tracking drift`** — Window-function over Position Tracking snapshots: which keywords moved more than N positions, dropped off page 1, or entered page 1, per region and device.

  _Answers 'what tracked keywords moved this month' in one command — the question Position Tracking emails fail to answer._

  ```bash
  semrush-pp-cli tracking drift 12345 --since 30d --min-delta 3 --agent
  ```
- **`audit regression`** — Diff the latest two Site Audit snapshots for a project: new issue IDs introduced, issues resolved, count delta per severity.

  _Lets an agent tell you exactly what your tech-SEO state regressed on between two crawls._

  ```bash
  semrush-pp-cli audit regression 12345 --agent
  ```

### Cost transparency
- **`budget`** — Every API call's documented unit cost is logged locally; budget rolls up spend by day, command, resource, and projects month-end burn from the current balance probe.

  _Tells an agent before a request 'this would cost N units' and after a month 'here is where the units went' — neither answerable from the upstream alone._

  ```bash
  semrush-pp-cli budget --since 30d --group-by command --agent
  ```

### Cross-domain joins the API can't do
- **`keyword gap`** — Set-difference of organic keywords across two or more domains in the same database, with intersection and unique-to-each modes.

  _Replaces the manual two-CSV VLOOKUP that every SEO consultant does by hand._

  ```bash
  semrush-pp-cli keyword gap myco.com competitor1.com competitor2.com --database us --kd-max 40 --agent
  ```
- **`backlink gap`** — Find referring domains that link to a competitor but not to you, filtered by authority score.

  _Directly surfaces link-building targets an agent can hand to an outreach workflow._

  ```bash
  semrush-pp-cli backlink gap myco.com competitor.com --min-ascore 70 --agent
  ```
- **`domain regions`** — Run Domain Overview across multiple country databases in one shot, persist all rows with the database key so later cross-region drift queries work.

  _Lets an agent answer 'how does this domain perform across our top 5 markets' as one call rather than five._

  ```bash
  semrush-pp-cli domain regions apple.com --databases us,uk,de,fr,it --agent
  ```

### SEO content patterns no competitor exposes
- **`audit triage`** — Rank Site Audit pages by weighted issue severity (errors x3, warnings x1, notices x0.1) so you fix the highest-impact pages first.

  _Turns a Site Audit dump into a prioritized action list an agent can hand to the next step._

  ```bash
  semrush-pp-cli audit triage 12345 --top 20 --agent
  ```
- **`serp-features`** — Time-series view of which SERP features (featured snippet, People Also Ask, video, image pack) have appeared and disappeared for a tracked keyword.

  _Tells a content-strategy agent when an opportunity (e.g. featured snippet slot opening) appeared or closed._

  ```bash
  semrush-pp-cli serp-features 'best running shoes' --since 30d --agent
  ```
- **`cannibalization`** — List phrases where the same domain ranks for multiple URLs (a known SEO problem) with the URLs and their respective positions.

  _Surfaces a high-value SEO problem in one command — most consultants charge to find this._

  ```bash
  semrush-pp-cli cannibalization apple.com --database us --agent
  ```

## Command Reference

**account** — Account utilities (API units balance)

- `semrush-pp-cli account` — Get remaining API units balance (free probe; no units cost)

**audit** — Site Audit: enable, run, list snapshots, drill into issues and pages

- `semrush-pp-cli audit campaign-info` — Get Site Audit campaign configuration and current status.
- `semrush-pp-cli audit edit` — Edit Site Audit campaign settings (page limit, user-agent, scope, etc.).
- `semrush-pp-cli audit enable` — Enable Site Audit on a project. One-time per project. Free (config call).
- `semrush-pp-cli audit history` — Site Audit snapshots history (time series of issue counts and score).
- `semrush-pp-cli audit issue` — Detailed report for one issue in a snapshot (affected pages, status).
- `semrush-pp-cli audit issue-catalog` — Get text descriptions for all Site Audit issue codes. Free.
- `semrush-pp-cli audit page` — Get full details for one crawled page (issues found, status, metrics).
- `semrush-pp-cli audit page-by-url` — Look up the page_id for a given URL within a snapshot.
- `semrush-pp-cli audit run` — Trigger a new Site Audit crawl. Free to launch; counts against page-credit pool.
- `semrush-pp-cli audit snapshot-info` — Get aggregated counts for a snapshot (errors/warnings/notices, total checks).
- `semrush-pp-cli audit snapshots` — List Site Audit snapshots for a project. Free (no API units).

**backlink** — Backlinks: overview, list, referring domains/IPs, anchors, competitors, history

- `semrush-pp-cli backlink anchors` — Anchors. 40 units/line. Anchor texts used in backlinks pointing at a target.
- `semrus